**How it works:**
- Extracts the user's latest message
- Classifies complexity (simple/standard/complex)
- Keeps only allowed files, discards the rest
- Sets `context.bootstrapFiles` to the filtered list

**Savings:**
- Simple greetings → 2 files (99% token reduction)
- Standard tasks → 3 files (90%+ reduction)
- Complex tasks → all files (full context)

**Rationale:** Simple messages don’t need documentation, memory logs, or tool references. Only identity and personality are required.

### 2. Heartbeat Optimizer (`token-heartbeat`)

**Event:** `agent:bootstrap` (for heartbeat polls)

Optimizes heartbeat check schedule to dramatically reduce API calls.

**Config:** `~/.openclaw/hooks/token-heartbeat/config.json`

**How it works:**
- Determines if enough time has elapsed since last check
- Skips checks that are not due
- Honors quiet hours (23:00–08:00 by default)
- Returns `HEARTBEAT_OK` when nothing needs checking

**Optimization Table:**

| Check | Default Interval | Optimized | Reduction |
|-------|------------------|-----------|-----------|
| Email | 60 min | 120 min | 50% |
| Calendar | 60 min | 240 min | 75% |
| Weather | 60 min | 240 min | 75% |
| Monitoring | 30 min | 120 min | 75% |

**Result:** 48 checks/day → 12 checks/day (**75% fewer API calls**)

### 3. Shared Module (`token-shared`)

Pure functions used by both hooks:
- `classifyComplexity(message)` → complexity level
- `getAllowedFiles(level, config)` → file list
- `isValidFileName(name)` → path traversal protection
- `loadConfigCached(logFn)` → 60s TTL config caching
- Maybe/Either patterns (no exceptions for control flow)

---

## External Endpoints

This skill does **not** call any external network endpoints. All operations are local to your machine.

---

## Security & Privacy

- **100% local execution** – No data leaves your system.
- **No external telemetry** – No calls to third‑party servers.
- **Configuration** read only from local hook configs.
- **File validation** prevents path traversal attacks.
- **No environment secrets** required.

---

## Model Invocation Note

Hooks run automatically:

- `token-context` runs on every `agent:bootstrap` (every user message).
- `token-heartbeat` runs on heartbeat polls.
No manual intervention needed after enabling the hooks.

---

## Trust Statement

By installing this skill, you trust that the code operates locally and does not transmit your workspace data. Review the open‑source implementation on GitHub before installing.

---

## CLI Commands

After installation, the `tokenqrusher` command is available.

### `tokenqrusher context <prompt>`

Recommends which context files should be loaded for a given prompt.

### `tokenqrusher status [--verbose]`

Shows system status.

### `tokenqrusher install [--hooks] [--all]`

Installs/enables hooks.

---

## Configuration

All hook configs are JSON files stored in:
`~/.openclaw/hooks/<hook-name>/config.json`

You can edit these to customize behavior (e.g., adjust file lists, intervals, or quiet hours). Changes are reloaded after 60 seconds (config cache TTL).

---

## Design Principles

- **Deterministic** – Same input → same output.
- **Pure functions** – No hidden side effects.
- **Immutability** – Frozen data structures.
- **No exceptions for control flow** – Uses Result/Either types.
- **Thread‑safe** – RLock protected shared state.
- **Exhaustive typing** – Full type hints.

---

## Performance

| Operation | Latency | Memory |
|-----------|---------|--------|
| Context classification | <1 ms | <1 MB |
| Heartbeat check | <0.5 ms | <0.5 MB |

Negligible overhead per agent message.

---

## Troubleshooting

### Hook not loading?

### Changes not taking effect?

Config cache TTL is 60 seconds. Restart the gateway for immediate effect.

---

## Migration from v2.0.x

v2.1.0 removes non‑functional components. If upgrading:

1. Disable and remove old hooks:

{
  "enabled": true,
  "logLevel": "info",
  "dryRun": false,
  "files": {
    "simple": ["SOUL.md", "IDENTITY.md"],
    "standard": ["SOUL.md", "IDENTITY.md", "USER.md"],
    "complex": ["SOUL.md", "IDENTITY.md", "USER.md", "TOOLS.md", "AGENTS.md", "MEMORY.md", "HEARTBEAT.md"]
  }
}

{
  "enabled": true,
  "intervals": {
    "email": 7200,
    "calendar": 14400,
    "weather": 14400,
    "monitoring": 7200
  },
  "quietHours": { "start": 23, "end": 8 }
}

$ tokenqrusher context "hi"
Complexity: simple (confidence: 95%)
Files: SOUL.md, IDENTITY.md
Savings: 71%

$ tokenqrusher status
=== tokenQrusher Status ===

Hooks:
  ✓ token-context   (Filters context)
  ✓ token-heartbeat (Optimizes heartbeat)