# Context Cost

> Report harness context overhead (KB, words, estimated tokens) for a given path by walking the directory tree and collecting all CLAUDE.md, agents.md, and @-import files the Claude Code harness auto-loads. Use when the user types /context-cost or /ctx-cost, asks how much context overhead a directory has, or wants to know what files the harness is auto-loading.

- Skill: `horizonbrute/context-cost` (Agent Skill)
- Install (CLI): `npx skillmds@latest add horizonbrute/context-cost`
- Raw SKILL.md: https://api.skillmd.com/api/skills/horizonbrute/context-cost/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: HorizonBrute (https://skillmd.com/u/horizonbrute)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/horizonbrute/context-cost

---


# Skill: /context-cost

**Model preference:** `#lowcost` (per `horizon_aios_model_prefs.md`; overridable by a prompt directive).

Report how much context overhead the Claude Code harness will auto-load for a given path — walking up the directory tree and collecting every `CLAUDE.md`, `CLAUDE.local.md`, `agents.md`, and `@`-import file it will pull in at session start.

---

## Arguments

`/context-cost [path]`

- `path` — optional; defaults to the current working directory if omitted.

---

## Step-by-step execution

### Step 1 — Resolve the target path

1.1 If the user provided a path argument, use it. Otherwise use the current working directory.

1.2 Run:
```
python "$HORIZON_SYSTEM/bin/context_cost.py" <path> --json
```

Capture the JSON output. If the command fails (non-zero exit, missing script, bad path), report the error clearly and stop.

### Step 2 — Parse and format the output

The JSON structure is:
```json
{
  "path": "...",
  "files": [
    {"level": N, "path": "...", "kb": N, "words": N, "tokens": N, "imported_by": "..." or null}
  ],
  "total_kb": N,
  "total_words": N,
  "total_tokens": N
}
```

### Step 3 — Present the report

3.1 Print a header line: `Context overhead for: <path>`

3.2 Print a table of the collected files, sorted by `level` (outermost first):

```
Level  File                              KB     Words   ~Tokens
-----  --------------------------------  -----  ------  -------
  0    /path/to/CLAUDE.md                1.2    210     280
  1    /path/to/agents.md                3.4    580     775
       (imported by CLAUDE.md)
```

- Show `(imported by <basename>)` on a sub-line when `imported_by` is non-null.
- Round KB to one decimal place; tokens and words are integers.

3.3 Print a totals line:
```
Total: N files — X.X KB — Y words — ~Z tokens
```

3.4 Threshold flags (after totals):
- If you know the size of the context window
- If total_tokens >= 12% context window print a notice: `[WARN] High context load: ~Z tokens. Consider trimming CLAUDE.md files or @-imports above this path.` 
- Else  if total_tokens >= 4%  print a notice: `[NOTE] Moderate context load: ~Z tokens.  Worth reviewing.`,
- If you dont know the size of the context window:
- If `total_tokens` >=  20000 : print a warning: `[WARN] High context load: ~Z tokens. Consider trimming CLAUDE.md files or @-imports above this path.`
- Else if `total_tokens` >= 8000: print a notice: `[NOTE] Moderate context load: ~Z tokens. Worth reviewing if sessions feel slow.`
- Otherwise: no flag.

---

## Notes for the executing agent

- `$HORIZON_SYSTEM` must be set in the environment. If it is not, report that the AIOS environment is not active and the user should source their profile or run the AIOS switcher.
- The script walks upward from the given path to `$HORIZON_ROOT`, collecting files at each level. Level 0 is the given path; higher numbers are ancestor directories.
- Imported files (via `@`-imports in CLAUDE.md) are included in the table and counted in totals. The `imported_by` field names the file that referenced them.
- Do not reimplement the walk logic — the script is the single source of truth. Just run it and format its output.