Claude Skill

ambit

Coverage-aware agent workflow tool. Use PROACTIVELY to search and read code and Markdown docs — `ambits rg`/`ambits grep` find matches and name the symbol or section each lands in, `ambits show` fetches exactly that definition — and before modifying files, making architecture dec

LLM Mart · 0 points · 1 views 156 listing impressions 0 install-command copies
Download joshlong145-ambits-skills_ambit-c0fa147.zip · 10 KB

Install

skills CLI npx skills add https://github.com/joshLong145/ambits/tree/main/skills/ambit
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install joshlong145-ambits@llmmart
Git git clone https://github.com/joshLong145/ambits.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole joshlong145/ambits collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

/ambit - Coverage-Aware Agent Workflow

Ambit tracks which parts of a codebase this agent has actually read, at symbol resolution. Use it to verify you have enough context before acting — and to identify blind spots before making changes that touch unfamiliar code.

PROACTIVE USE: When to Check Without Being Asked

BEFORE modifying a file — if you haven't verified you've read it this session:

mcp__ambit__coverage_file  →  check the specific file(s) you're about to change

BEFORE architectural decisions — if you're proposing design changes across multiple files:

mcp__ambit__coverage  →  check overall module coverage; proceed only if Seen% > 60%

When a bug is hard to reproduce or diagnose — low coverage on the relevant file is a likely root cause of bad recommendations:

mcp__ambit__coverage_file  →  if Full% < 50%, read the file before diagnosing

After receiving a multi-file task — check coverage of the involved files before starting; flag which ones need reading first.

When your suggestion might be wrong — if a user pushes back, check coverage. You may have missed implementation details.

When looking for code or docs — search with ambits rg, then show the symbol or Markdown section it found, instead of Grep and a whole-file Read (see Finding and Reading Code and Docs).

Finding and Reading Code and Docs

Search, then fetch exactly what the search found — not the whole file:

ambits -p . rg 'fn enclosing'                                   # 1. find it
# src/symbols/mod.rs:158:9:[— FileSymbols/enclosing]     pub fn enclosing(…
ambits -p . show 'src/symbols/mod.rs::FileSymbols/enclosing'    # 2. read that symbol

Every match names the symbol it landed in and how deeply you have read it, so the search tells you what to fetch and whether you need to. show returns that one definition — a function, a type, or a section of a Markdown file — and counts as reading it; a Read of the whole file would cost the rest of the file too. Use ambits rg in place of your Grep tool and of shell grep/rg, and show in place of Read whenever you know the symbol.

Searching: ambits rg

ripgrep's flags — the dialect your Grep tool is built on:

ambits -p . rg 'depth_of'                    # every use and definition
ambits -p . rg -F 'Vec<(String, u32)>'       # a literal, no regex escaping
ambits -p . rg -w -i 'journal'               # whole word, any case
ambits -p . rg 'fn enclosing' -t rust        # one file type (-t md for Markdown)
ambits -p . rg 'TODO' -g '!tests/**'         # globs; ! excludes
ambits -p . rg 'Journal::open' -C 3          # context: -A after, -B before, -C both
ambits -p . rg 'unwrap\(\)' -c               # matching lines per file
ambits -p . rg 'Matcher' -l                  # just the files
ambits -p . rg 'fn [a-z_]+' -o src/text.rs   # only the matched text, scoped to a path
ambits -p . rg '^\s*(pub )?fn ' src/text.rs  # a file's outline: each fn, with its id and depth

Scope a broad search first (-l, -c), then narrow: output is capped at 200 matches (--head-limit 0 for all, -m N per file) and lines at 300 columns (-M 0), and all of it lands in your context.

Each match is file:line:column:[depth symbol] line:

Bracket Meaning
[full name] You have read this symbol in full: no need to show it
[signature name], [overview name], [name name] Seen at that depth — name is what an earlier search earns — but not its body: show it before relying on it
[— name] You have not seen it
[name] No coverage journal loaded: unknown, not unread
[-] Not inside any symbol — a use line, or a file no parser handles

The show id is the file and the bracket's name path joined by :: — src/symbols/mod.rs:158:9:[— FileSymbols/enclosing] is src/symbols/mod.rs::FileSymbols/enclosing — or take symbol.id verbatim from --json (ripgrep's JSON Lines, with a symbol on each match and a coverage object on the summary).

  • Exit codes are grep's: 0 matched, 1 nothing matched, 2 error — safe to chain with &&.
  • Results are sorted by path, line, column. Every text file is searched, not only parseable ones: a hit in TOML is real, it just has no symbol.
  • Not supported: -P/--pcre2, -r/--replace, -f/--file. No backreferences or lookaround — ripgrep's regex engine, and its limits.

ambits grep is the same search with GNU grep's flags, for when you are writing grep by habit. The two give the same letters opposite meanings (-L, -z, -r), so they are separate commands. Under grep, line numbers are opt-in (-n), there is no column, -h is --no-filename (help is --help), and -P is refused rather than silently matching something else:

ambits -p . grep -rn 'break-lock' docs/

Markdown: sections are symbols

In a Markdown file every heading is a symbol, nested under the headings above it, so the same search-then-fetch works on documentation:

ambits -p . rg '^#{1,3} ' docs/wiki/Sharing.md          # its outline, with what you have read
ambits -p . rg -t md 'break-lock'                        # which sections mention it
# docs/wiki/Sharing.md:53:51:[— Sharing/Push] … `ambits push --break-lock` removes it …
ambits -p . show 'docs/wiki/Sharing.md::Sharing/Push'    # that section, heading to the next

A section's id is the file and its heading path: # Sharing › ## Push is docs/wiki/Sharing.md::Sharing/Push. Fetching the top heading returns the whole document, so fetch the section you need. ambits -p . --dump --depth 2 outlines every file (Markdown headings included) with line ranges and token estimates.

Fetching: ambits show

ambits -p . show 'src/app.rs::App/process_compaction'
ambits -p . show 'src/digest.rs::grouped' 'src/app.rs::App/handle_key'   # batched: one call
ambits -p . show b3:2b6c1e45                                               # by content_hash, 8+ characters
ambits -p . show --no-body 'docs/wiki/TUI.md::TUI'                        # where, and how big
ambits -p . show --max-bytes 4000 'src/main.rs::main'                     # capped

It returns JSON: id, name, lines, bytes, content_hash, label (fn, struct, h2, …), estimated_tokens, and definition — the exact source span. Check a large one's size with --no-body first; a definition cut by --max-bytes is flagged "truncated": true, as it is no longer valid source.

Ambiguity is reported, not resolved. matches is an array: ids are not unique (a type may have several inherent impl blocks in one file). Prefer the hash when you need exactly one. An empty matches means no such symbol, and for an id comes with suggestions — the ids you likely meant (generics like ContentRow<'a> and a Markdown heading's full path forgiven): show one of them. "selector": "unrecognized" means the query was neither an id nor a hash.

What counts as reading

Coverage is credited from the session log, for what the tool calls could have put in front of you:

Command Credited
show <id> Each symbol named, as read in full — and what is inside it (an impl's methods, a section's subsections), unless --max-bytes is given
show --no-body <id> Each symbol named, at name depth only
rg / grep Each symbol a printed match sits in, at name depth — seen, not read

The brackets are your own reads. In a subagent, [full …] means you read it — not your parent, not another subagent. --json (and show) name you as coverage.agent and your parent as coverage.parent_agent; to see what your parent has read, ask for it: ambits -p . --agent <parent_agent> show …. If coverage.agent is null, the depths are the whole session's (scope_reason says why) — treat them as hints and show what you rely on.

A search counts toward Seen%, never Full%: after one, show what you need rather than reasoning from the matched lines — it is both the complete definition and the credit for having read it. -l, -c and -q print no symbols and credit nothing.

Each ambits invocation in a command is credited on its own (ambits show A --no-body && ambits show B reads B in full), found by the word ambits — so call it by that name, not through a shell variable.

Finding callers

ambits -p . callers centered_rect

Each call site and the symbol containing it, as an id show takes. Comments and strings are never reported — the answer comes from parsed call nodes, not text — so prefer it over rg when you want calls specifically. Matching is by callee name: callers new returns calls to every new (--format json marks this name_matched_only: true).

Decision Thresholds

Threshold Arguments

Thresholds can be passed directly when invoking the skill:

/ambit --proceed=80 --adequate=50
Argument Default Meaning
--proceed=N 80 Minimum Full% to proceed without reading more
--adequate=N 50 Minimum Full% for targeted/interface-only changes
--module=N 60 Minimum Seen% across a module for architectural tasks

If no thresholds are provided and the task is non-trivial, ask the user:

"What coverage level is acceptable before I proceed? (default: 80% full body)"

Use the user's answer for all subsequent threshold decisions in the session.

Applying Thresholds

Full% on a file vs --proceed Action
≥ proceed Sufficient context — proceed
≥ adequate, < proceed Adequate for targeted changes — note gaps
< adequate Read the file before making changes
0% Do not make recommendations without reading first

For architectural or refactoring tasks, also check module-level Seen% against --module.

Primary Interface: MCP Tools

Prefer these over bash when the MCP server is available (check mcp__ambit__* in your allowed tools):

Tool When to use
mcp__ambit__coverage Overall project coverage for the current session
mcp__ambit__coverage_file Coverage for one specific file — fastest check before editing
mcp__ambit__symbol_tree Full symbol tree — use when you need to understand project structure
mcp__ambit__list_sessions Find available sessions — use when session context is unclear

After a Compaction

When context has just been compacted, the summary describes what a model remembered while it was losing that context. restore-context instead reports what this session demonstrably read:

ambits -p . restore-context

Treat the symbols it lists as known — no need to re-read them. Anything it does not list is not covered, and a Not included line names files holding symbols it withheld, so you can read those directly.

A heading marked reconstructed from session logs means the coverage journal was unavailable and the history was rebuilt from the logs afterwards, rather than recorded as the session ran.

Entries are listed as name:first-last — current line numbers, taken from a fresh scan rather than stored, so they are accurate even for files edited since the read. Use them: read that range directly instead of re-reading the file or spending a find_symbol call to locate the symbol.

An entry marked (was src/old.rs) moved since you read it. Its body is byte-identical — you still know it — but the address you remember is stale, so use the one given. Renames are not tracked this way and will appear as no-longer-present instead.

Use --max-tokens N to fit a budget (default 3000), and --format json for programmatic use.

Automatic injection

To have this happen without being asked, register the hook once:

ambits hook install --project .

That adds a SessionStart hook with matcher: "compact" to .claude/settings.json, so Claude Code runs restore-context and injects the result the moment a compaction completes. It merges into existing settings and is safe to re-run. When there is nothing to restore it emits nothing.

Inspecting the journal

ambits -p . cache status        # sessions, symbols, size on disk
ambits -p . cache clear --session <id>
ambits -p . cache clear --all

Nothing is deleted automatically. A journal is the only record of what a session read and what the code looked like at the time, so removing one means any later restore of that session must be reconstructed from logs instead. Journals are small — one entry per symbol read, bounded by what an agent can read in a session, not by repository size.

Bash Fallback

If MCP tools are unavailable:

# Coverage for the current session
ambits -p . --coverage

# Coverage for a specific file (pipe and grep)
ambits -p . --coverage | grep "src/my_file.rs"

# Specific session
ambits -p . --coverage --session <session-id>

# Full symbol tree
ambits -p . --dump

Reading the Output

File                              Seen%    Full%
──────────────────────────────────────────────────────────
src/app.rs                        100.0%   85.0%   ← well understood
src/parser/rust.rs                 40.0%   10.0%   ← blind spot
src/ingest/mod.rs                  0.0%    0.0%   ← unread
  • Seen% — symbols viewed at any depth (name, signature, overview, or full body)
  • Full% — symbols where the complete implementation was read

A file at 100% Seen / 10% Full means you saw the signatures but not the bodies. For anything you're actively modifying, Full% matters more than Seen%.

Interpreting Low Coverage

High Seen%, Low Full% — You know the structure but not the implementations. Safe for interface-only changes; risky for behaviour changes.

Low Seen%, Low Full% — Genuine blind spot. Read the file before touching it.

Specific symbol at 0% — If the task involves that symbol, read it first: ambits show <id>, Read, or Serena's find_symbol with include_body: true.

Coverage Improvement Loop

If coverage on files you need is insufficient:

  1. Identify low-coverage files with mcp__ambit__coverage_file or ambits --coverage
  2. Read the specific symbols you need: ambits show <id> (ids from rg, or from restore-context), find_symbol with include_body: true, or Read for the full file
  3. Re-check — coverage updates immediately after each read
  4. Proceed once thresholds are met

Flags Reference (Bash)

Flag Description
-p Project root path (required)
-s Session ID (auto-detects latest)
--coverage Print coverage report
--dump Print symbol tree
--serena Use Serena LSP symbols (more languages, finer detail)
--agent Whose reads to report (id or prefix): --coverage's filter, and for rg/grep/show in place of your own

Troubleshooting

No session found — Sessions live in ~/.claude/projects/<slug>/ where the slug is your project path with / replaced by -. The latest .jsonl file is the current session.

Coverage shows 0% for a file you've read — Coverage tracks read tool calls only (Read, grep, find_symbol, etc.). Edits are recorded as writes, not reads — editing a symbol does not mark it read. Mentioning a file in conversation without reading it via a tool does not count.

When was this last changed by an agent? — ambits touched <file|symbol-id> shows the latest agent write, whether that version is still on disk, and which commit it landed in. For a symbol it counts only writes attributed to that symbol or one nested in it (App covers App/handle_key). A write the log could attribute only to the whole file is not counted, so "no writes" for a symbol means none that ambits could attribute; query the file to see those.

File not in the coverage report — The file may not have parseable symbols (empty file, non-code file, or unsupported language without --serena).

Files (ambits)
  • coverage-guide.md 2.7 KB
    Loading…
  • examples.md 2.5 KB
    Loading…
  • session-management.md 1.5 KB
    Loading…
  • SKILL.md 16.6 KB
    ---
    name: ambit
    description: "Coverage-aware agent workflow tool. Use PROACTIVELY to search and read code and Markdown docs — `ambits rg`/`ambits grep` find matches and name the symbol or section each lands in, `ambits show` fetches exactly that definition — and before modifying files, making architecture decisions, debugging, or reviewing code. Reports which symbols Claude has read (Seen%) vs read in full (Full%). Use MCP tools mcp__ambit__coverage or mcp__ambit__coverage_file when available; fall back to bash."
    allowed-tools: Bash(ambits *)
    ---
    
    # /ambit - Coverage-Aware Agent Workflow
    
    Ambit tracks which parts of a codebase this agent has actually read, at symbol
    resolution. Use it to verify you have enough context before acting — and to
    identify blind spots before making changes that touch unfamiliar code.
    
    ## PROACTIVE USE: When to Check Without Being Asked
    
    **BEFORE modifying a file** — if you haven't verified you've read it this session:
    ```
    mcp__ambit__coverage_file  →  check the specific file(s) you're about to change
    ```
    
    **BEFORE architectural decisions** — if you're proposing design changes across
    multiple files:
    ```
    mcp__ambit__coverage  →  check overall module coverage; proceed only if Seen% > 60%
    ```
    
    **When a bug is hard to reproduce or diagnose** — low coverage on the relevant
    file is a likely root cause of bad recommendations:
    ```
    mcp__ambit__coverage_file  →  if Full% < 50%, read the file before diagnosing
    ```
    
    **After receiving a multi-file task** — check coverage of the involved files
    before starting; flag which ones need reading first.
    
    **When your suggestion might be wrong** — if a user pushes back, check coverage.
    You may have missed implementation details.
    
    **When looking for code or docs** — search with `ambits rg`, then `show` the
    symbol or Markdown section it found, instead of `Grep` and a whole-file `Read`
    (see [Finding and Reading Code and Docs](#finding-and-reading-code-and-docs)).
    
    ## Finding and Reading Code and Docs
    
    Search, then fetch exactly what the search found — not the whole file:
    
    ```bash
    ambits -p . rg 'fn enclosing'                                   # 1. find it
    # src/symbols/mod.rs:158:9:[— FileSymbols/enclosing]     pub fn enclosing(…
    ambits -p . show 'src/symbols/mod.rs::FileSymbols/enclosing'    # 2. read that symbol
    ```
    
    Every match names the symbol it landed in and how deeply you have read it, so
    the search tells you what to fetch and whether you need to. `show` returns
    that one definition — a function, a type, or a section of a Markdown file —
    and **counts as reading it**; a `Read` of the whole file would cost the rest
    of the file too. Use `ambits rg` in place of your `Grep` tool and of shell
    `grep`/`rg`, and `show` in place of `Read` whenever you know the symbol.
    
    ### Searching: `ambits rg`
    
    ripgrep's flags — the dialect your `Grep` tool is built on:
    
    ```bash
    ambits -p . rg 'depth_of'                    # every use and definition
    ambits -p . rg -F 'Vec<(String, u32)>'       # a literal, no regex escaping
    ambits -p . rg -w -i 'journal'               # whole word, any case
    ambits -p . rg 'fn enclosing' -t rust        # one file type (-t md for Markdown)
    ambits -p . rg 'TODO' -g '!tests/**'         # globs; ! excludes
    ambits -p . rg 'Journal::open' -C 3          # context: -A after, -B before, -C both
    ambits -p . rg 'unwrap\(\)' -c               # matching lines per file
    ambits -p . rg 'Matcher' -l                  # just the files
    ambits -p . rg 'fn [a-z_]+' -o src/text.rs   # only the matched text, scoped to a path
    ambits -p . rg '^\s*(pub )?fn ' src/text.rs  # a file's outline: each fn, with its id and depth
    ```
    
    Scope a broad search first (`-l`, `-c`), then narrow: output is capped at
    **200 matches** (`--head-limit 0` for all, `-m N` per file) and lines at 300
    columns (`-M 0`), and all of it lands in your context.
    
    Each match is `file:line:column:[depth symbol] line`:
    
    | Bracket | Meaning |
    |---|---|
    | `[full name]` | You have read this symbol in full: no need to `show` it |
    | `[signature name]`, `[overview name]`, `[name name]` | Seen at that depth — `name` is what an earlier search earns — but not its body: `show` it before relying on it |
    | `[— name]` | You have **not** seen it |
    | `[name]` | No coverage journal loaded: *unknown*, not unread |
    | `[-]` | Not inside any symbol — a `use` line, or a file no parser handles |
    
    The `show` id is the file and the bracket's name path joined by `::` —
    `src/symbols/mod.rs:158:9:[— FileSymbols/enclosing]` is
    `src/symbols/mod.rs::FileSymbols/enclosing` — or take `symbol.id` verbatim
    from `--json` (ripgrep's JSON Lines, with a `symbol` on each match and a
    `coverage` object on the summary).
    
    - **Exit codes are grep's**: `0` matched, `1` nothing matched, `2` error — safe
      to chain with `&&`.
    - Results are sorted by path, line, column. Every text file is searched, not
      only parseable ones: a hit in TOML is real, it just has no symbol.
    - Not supported: `-P/--pcre2`, `-r/--replace`, `-f/--file`. No backreferences
      or lookaround — ripgrep's regex engine, and its limits.
    
    **`ambits grep`** is the same search with GNU grep's flags, for when you are
    writing grep by habit. The two give the same letters opposite meanings (`-L`,
    `-z`, `-r`), so they are separate commands. Under `grep`, line numbers are
    opt-in (`-n`), there is no column, `-h` is `--no-filename` (help is `--help`),
    and `-P` is refused rather than silently matching something else:
    
    ```bash
    ambits -p . grep -rn 'break-lock' docs/
    ```
    
    ### Markdown: sections are symbols
    
    In a Markdown file every heading is a symbol, nested under the headings above
    it, so the same search-then-fetch works on documentation:
    
    ```bash
    ambits -p . rg '^#{1,3} ' docs/wiki/Sharing.md          # its outline, with what you have read
    ambits -p . rg -t md 'break-lock'                        # which sections mention it
    # docs/wiki/Sharing.md:53:51:[— Sharing/Push] … `ambits push --break-lock` removes it …
    ambits -p . show 'docs/wiki/Sharing.md::Sharing/Push'    # that section, heading to the next
    ```
    
    A section's id is the file and its heading path: `# Sharing` › `## Push` is
    `docs/wiki/Sharing.md::Sharing/Push`. Fetching the top heading returns the
    whole document, so fetch the section you need. `ambits -p . --dump --depth 2`
    outlines every file (Markdown headings included) with line ranges and token
    estimates.
    
    ### Fetching: `ambits show`
    
    ```bash
    ambits -p . show 'src/app.rs::App/process_compaction'
    ambits -p . show 'src/digest.rs::grouped' 'src/app.rs::App/handle_key'   # batched: one call
    ambits -p . show b3:2b6c1e45                                               # by content_hash, 8+ characters
    ambits -p . show --no-body 'docs/wiki/TUI.md::TUI'                        # where, and how big
    ambits -p . show --max-bytes 4000 'src/main.rs::main'                     # capped
    ```
    
    It returns JSON: `id`, `name`, `lines`, `bytes`, `content_hash`, `label`
    (`fn`, `struct`, `h2`, …), `estimated_tokens`, and `definition` — the exact
    source span. Check a large one's size with `--no-body` first; a definition cut
    by `--max-bytes` is flagged `"truncated": true`, as it is no longer valid source.
    
    **Ambiguity is reported, not resolved.** `matches` is an array: ids are not
    unique (a type may have several inherent impl blocks in one file). Prefer the
    hash when you need exactly one. An empty `matches` means no such symbol, and
    for an id comes with `suggestions` — the ids you likely meant (generics like
    `ContentRow<'a>` and a Markdown heading's full path forgiven): `show` one of
    them. `"selector": "unrecognized"` means the query was neither an id nor a hash.
    
    ### What counts as reading
    
    Coverage is credited from the session log, for what the tool calls could have
    put in front of you:
    
    | Command | Credited |
    |---|---|
    | `show <id>` | Each symbol named, as read in **full** — and what is inside it (an impl's methods, a section's subsections), unless `--max-bytes` is given |
    | `show --no-body <id>` | Each symbol named, at **name** depth only |
    | `rg` / `grep` | Each symbol a printed match sits in, at **name** depth — seen, not read |
    
    **The brackets are your own reads.** In a subagent, `[full …]` means *you*
    read it — not your parent, not another subagent. `--json` (and `show`) name
    you as `coverage.agent` and your parent as `coverage.parent_agent`; to see what
    your parent has read, ask for it: `ambits -p . --agent <parent_agent> show …`.
    If `coverage.agent` is `null`, the depths are the whole session's
    (`scope_reason` says why) — treat them as hints and `show` what you rely on.
    
    A search counts toward Seen%, never Full%: after one, `show` what you need
    rather than reasoning from the matched lines — it is both the complete
    definition and the credit for having read it. `-l`, `-c` and `-q` print no
    symbols and credit nothing.
    
    Each `ambits` invocation in a command is credited on its own (`ambits show A
    --no-body && ambits show B` reads `B` in full), found by the word `ambits` —
    so call it by that name, not through a shell variable.
    
    ### Finding callers
    
    ```bash
    ambits -p . callers centered_rect
    ```
    
    Each call site and the symbol containing it, as an id `show` takes. Comments
    and strings are never reported — the answer comes from parsed call nodes, not
    text — so prefer it over `rg` when you want calls specifically. Matching is by
    callee **name**: `callers new` returns calls to every `new` (`--format json`
    marks this `name_matched_only: true`).
    
    ## Decision Thresholds
    
    ### Threshold Arguments
    
    Thresholds can be passed directly when invoking the skill:
    
    ```
    /ambit --proceed=80 --adequate=50
    ```
    
    | Argument | Default | Meaning |
    |----------|---------|---------|
    | `--proceed=N` | 80 | Minimum Full% to proceed without reading more |
    | `--adequate=N` | 50 | Minimum Full% for targeted/interface-only changes |
    | `--module=N` | 60 | Minimum Seen% across a module for architectural tasks |
    
    If no thresholds are provided and the task is non-trivial, **ask the user**:
    > "What coverage level is acceptable before I proceed? (default: 80% full body)"
    
    Use the user's answer for all subsequent threshold decisions in the session.
    
    ### Applying Thresholds
    
    | Full% on a file vs `--proceed` | Action |
    |-------------------------------|--------|
    | ≥ proceed                     | Sufficient context — proceed |
    | ≥ adequate, < proceed         | Adequate for targeted changes — note gaps |
    | < adequate                    | **Read the file before making changes** |
    | 0%                            | **Do not make recommendations without reading first** |
    
    For architectural or refactoring tasks, also check module-level Seen% against `--module`.
    
    ## Primary Interface: MCP Tools
    
    Prefer these over bash when the MCP server is available (check `mcp__ambit__*`
    in your allowed tools):
    
    | Tool | When to use |
    |------|-------------|
    | `mcp__ambit__coverage` | Overall project coverage for the current session |
    | `mcp__ambit__coverage_file` | Coverage for one specific file — fastest check before editing |
    | `mcp__ambit__symbol_tree` | Full symbol tree — use when you need to understand project structure |
    | `mcp__ambit__list_sessions` | Find available sessions — use when session context is unclear |
    
    ## After a Compaction
    
    When context has just been compacted, the summary describes what a model
    *remembered* while it was losing that context. `restore-context` instead
    reports what this session demonstrably read:
    
    ```bash
    ambits -p . restore-context
    ```
    
    Treat the symbols it lists as known — no need to re-read them. Anything it does
    not list is not covered, and a `Not included` line names files holding symbols
    it withheld, so you can read those directly.
    
    A heading marked `reconstructed from session logs` means the coverage journal
    was unavailable and the history was rebuilt from the logs afterwards, rather
    than recorded as the session ran.
    
    Entries are listed as `name:first-last` — current line numbers, taken from a
    fresh scan rather than stored, so they are accurate even for files edited since
    the read. Use them: read that range directly instead of re-reading the file or
    spending a `find_symbol` call to locate the symbol.
    
    An entry marked `(was src/old.rs)` moved since you read it. Its body is
    byte-identical — you still know it — but the address you remember is stale, so
    use the one given. Renames are not tracked this way and will appear as
    no-longer-present instead.
    
    Use `--max-tokens N` to fit a budget (default 3000), and `--format json` for
    programmatic use.
    
    ### Automatic injection
    
    To have this happen without being asked, register the hook once:
    
    ```bash
    ambits hook install --project .
    ```
    
    That adds a `SessionStart` hook with `matcher: "compact"` to
    `.claude/settings.json`, so Claude Code runs `restore-context` and injects the
    result the moment a compaction completes. It merges into existing settings and
    is safe to re-run. When there is nothing to restore it emits nothing.
    
    ### Inspecting the journal
    
    ```bash
    ambits -p . cache status        # sessions, symbols, size on disk
    ambits -p . cache clear --session <id>
    ambits -p . cache clear --all
    ```
    
    Nothing is deleted automatically. A journal is the only record of what a
    session read *and what the code looked like at the time*, so removing one
    means any later restore of that session must be reconstructed from logs
    instead.
    Journals are small — one entry per symbol read, bounded by what an agent can
    read in a session, not by repository size.
    
    ## Bash Fallback
    
    If MCP tools are unavailable:
    
    ```bash
    # Coverage for the current session
    ambits -p . --coverage
    
    # Coverage for a specific file (pipe and grep)
    ambits -p . --coverage | grep "src/my_file.rs"
    
    # Specific session
    ambits -p . --coverage --session <session-id>
    
    # Full symbol tree
    ambits -p . --dump
    ```
    
    ## Reading the Output
    
    ```
    File                              Seen%    Full%
    ──────────────────────────────────────────────────────────
    src/app.rs                        100.0%   85.0%   ← well understood
    src/parser/rust.rs                 40.0%   10.0%   ← blind spot
    src/ingest/mod.rs                  0.0%    0.0%   ← unread
    ```
    
    - **Seen%** — symbols viewed at any depth (name, signature, overview, or full body)
    - **Full%** — symbols where the complete implementation was read
    
    A file at 100% Seen / 10% Full means you saw the signatures but not the bodies.
    For anything you're actively modifying, Full% matters more than Seen%.
    
    ## Interpreting Low Coverage
    
    **High Seen%, Low Full%** — You know the structure but not the implementations.
    Safe for interface-only changes; risky for behaviour changes.
    
    **Low Seen%, Low Full%** — Genuine blind spot. Read the file before touching it.
    
    **Specific symbol at 0%** — If the task involves that symbol, read it first:
    `ambits show <id>`, Read, or Serena's `find_symbol` with `include_body: true`.
    
    ## Coverage Improvement Loop
    
    If coverage on files you need is insufficient:
    
    1. Identify low-coverage files with `mcp__ambit__coverage_file` or `ambits --coverage`
    2. Read the specific symbols you need: `ambits show <id>` (ids from `rg`, or
       from `restore-context`), `find_symbol` with `include_body: true`, or `Read`
       for the full file
    3. Re-check — coverage updates immediately after each read
    4. Proceed once thresholds are met
    
    ## Flags Reference (Bash)
    
    | Flag | Description |
    |------|-------------|
    | `-p` | Project root path (required) |
    | `-s` | Session ID (auto-detects latest) |
    | `--coverage` | Print coverage report |
    | `--dump` | Print symbol tree |
    | `--serena` | Use Serena LSP symbols (more languages, finer detail) |
    | `--agent` | Whose reads to report (id or prefix): `--coverage`'s filter, and for `rg`/`grep`/`show` in place of your own |
    
    ## Troubleshooting
    
    **No session found** — Sessions live in `~/.claude/projects/<slug>/` where the
    slug is your project path with `/` replaced by `-`. The latest `.jsonl` file is
    the current session.
    
    **Coverage shows 0% for a file you've read** — Coverage tracks read tool calls
    only (Read, grep, find_symbol, etc.). Edits are recorded as writes, not reads —
    editing a symbol does not mark it read. Mentioning a file in conversation
    without reading it via a tool does not count.
    
    **When was this last changed by an agent?** — `ambits touched <file|symbol-id>`
    shows the latest agent write, whether that version is still on disk, and which
    commit it landed in. For a
    symbol it counts only writes attributed to that symbol or one nested in it
    (`App` covers `App/handle_key`). A write the log could attribute only to the
    whole file is not counted, so "no writes" for a symbol means none that ambits
    could attribute; query the file to see those.
    
    **File not in the coverage report** — The file may not have parseable symbols
    (empty file, non-code file, or unsupported language without `--serena`).
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.