ambit · diff
git:20260208.2ee1660 to git:20260316.de3920f
118 added, 71 removed. Audit A to A.
---
name: ambit
- description: "Check source code coverage using ambit - analyze how much of your codebase Claude has seen during a session"
+ description: "Coverage-aware agent workflow tool. Use PROACTIVELY 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 - Source Code Coverage Analysis
-
- Ambit analyzes Claude Code session logs to determine which parts of your codebase were viewed during a coding session. It provides visibility metrics showing how much of your code Claude has "seen" versus examined in full detail.
-
- ## When to Use
+ # /ambit - Coverage-Aware Agent Workflow
- - Understand how much of a codebase Claude has examined
- - Verify coverage before making architectural decisions
- - Identify blind spots in code review sessions
- - Track historical session coverage
+ 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.
- ## Quick Start
+ ## PROACTIVE USE: When to Check Without Being Asked
- ### Current Project Coverage (Most Recent Session)
- ```bash
- ambits -p . --coverage
+ **BEFORE modifying a file** — if you haven't verified you've read it this session:
```
-
- ### Specific Session Coverage
- ```bash
- ambits -p . --coverage --session <session-id>
+ mcp__ambit__coverage_file → check the specific file(s) you're about to change
```
- ### Interactive TUI Mode
- ```bash
- ambits -p .
+ **BEFORE architectural decisions** — if you're proposing design changes across
+ multiple files:
```
+ mcp__ambit__coverage → check overall module coverage; proceed only if Seen% > 60%
+ ```
- ### With Serena LSP Symbols (more languages, finer detail)
- ```bash
- ambits -p . --serena
+ **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
+ ```
- ## Understanding the Output
+ **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.
+
+ ## Decision Thresholds
+
+ ### Threshold Arguments
+
+ Thresholds can be passed directly when invoking the skill:
+
```
- Coverage Report (Session: abc123...)
- ──────────────────────────────────────────────────────────
- File Seen% Full%
- ──────────────────────────────────────────────────────────
- src/main.rs 100.0% 75.0%
- src/parser/rust.rs 80.0% 40.0%
- src/coverage.rs 100.0% 100.0%
- ──────────────────────────────────────────────────────────
+ /ambit --proceed=80 --adequate=50
```
- - **Seen%**: Percentage of symbols Claude viewed at any depth (overview, signature, or full body)
- - **Full%**: Percentage of symbols where Claude read the complete implementation
+ | 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 |
- ## Coverage Patterns
+ 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)"
- | Seen% | Full% | Interpretation |
- |-------|-------|----------------|
- | High | High | Thoroughly examined - Claude understands implementation details |
- | High | Low | Scanned/overviewed but not deeply read - knows structure but not internals |
- | Low | Low | Barely touched - potential blind spot |
- | Low | High | Specific functions read without broader context |
+ Use the user's answer for all subsequent threshold decisions in the session.
- **Critical files** (core business logic, security) should have high Full%.
- Low coverage on bug-related files suggests Claude may be missing context.
+ ### Applying Thresholds
- ## Examples
+ | 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 |
+
+ ## Bash Fallback
+
+ If MCP tools are unavailable:
+
```bash
- # Check coverage for current project (latest session)
+ # Coverage for the current session
ambits -p . --coverage
- # Check a specific session
- ambits -p . --coverage --session 34e212cf-a176-4059-ba12-eca94b56e43b
+ # Coverage for a specific file (pipe and grep)
+ ambits -p . --coverage | grep "src/my_file.rs"
- # Launch interactive TUI with symbol-level depth
- ambits -p .
+ # Specific session
+ ambits -p . --coverage --session <session-id>
- # Dump symbol tree to stdout
+ # Full symbol tree
ambits -p . --dump
+ ```
- # Use Serena's LSP symbol cache
- ambits -p . --serena --coverage
+ ## 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
+ ```
- ## Flags Reference
+ - **Seen%** — symbols viewed at any depth (name, signature, overview, or full body)
+ - **Full%** — symbols where the complete implementation was read
- | Flag | Description |
- |---|---|
- | `--project`, `-p` | Path to the project root (required) |
- | `--session`, `-s` | Session ID to track (auto-detects latest) |
- | `--dump` | Print symbol tree to stdout and exit |
- | `--coverage` | Print coverage report to stdout and exit |
- | `--serena` | Use Serena's LSP symbol cache instead of tree-sitter |
- | `--log-dir` | Path to Claude Code log directory (auto-derived) |
+ 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%.
- ## Troubleshooting
+ ## Interpreting Low Coverage
- **"No session found"**: Ensure Claude Code sessions exist in `~/.claude/projects/`. The project slug is derived from your absolute project path with `/` replaced by `-`.
+ **High Seen%, Low Full%** — You know the structure but not the implementations.
+ Safe for interface-only changes; risky for behaviour changes.
- **Low coverage numbers**: Coverage only tracks what Claude explicitly read via tools. Files mentioned in conversation but not read via Read/Edit tools won't be tracked.
+ **Low Seen%, Low Full%** — Genuine blind spot. Read the file before touching it.
- **Session not loading**: Verify the session ID matches a `.jsonl` file in the projects directory. Check file permissions.
+ **Specific symbol at 0%** — If the task involves that symbol, read it first using
+ Read or Serena's `find_symbol` with `include_body: true`.
- ## Reference Documentation
+ ## Coverage Improvement Loop
- For detailed guidance, see:
- - [coverage-guide.md](coverage-guide.md) - Deep analysis of coverage patterns and strategic interpretation
- - [session-management.md](session-management.md) - Finding and managing session files
- - [examples.md](examples.md) - Extended usage examples and workflow patterns
+ 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 (`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` | Filter to a specific agent ID |
+
+ ## 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 tool calls only
+ (Read, Edit, find_symbol, etc.). Mentioning a file in conversation without reading
+ it via a tool does not count.
+
+ **File not in the coverage report** — The file may not have parseable symbols
+ (empty file, non-code file, or unsupported language without `--serena`).