Ambits

A code-reading tool for AI agents, and a memory of what they have read.

Coding agents read whole files to find one function, re-read code they already know, and lose all of it the moment the context window compacts. ambits addresses both halves of that:

• Reading — search, callers and symbol lookup that answer in symbols rather than files. The agent asks for App/process_compaction, not for 2,000 lines of app.rs.
• Remembering — ambits records every symbol the agent reads, at what depth, throughout the session. After a compaction it hands that history back, so the agent knows what it already understands instead of rediscovering it.

Both surfaces are plain text and JSON with no vendor coupling. Ingestion is currently built and tested against Claude Code.

Quick start

cargo install ambits   # or a prebuilt binary from Releases

# Hand read history back automatically after every compaction
ambits hook install --project .

# Watch the session live (and keep the read journal)
ambits -p .

For the agent

Search, with every hit attributed to a symbol — ripgrep's flags, or GNU grep's via ambits grep:

ambits -p . rg 'is_binary' -t rust

src/search.rs:390:4:[full is_binary] fn is_binary(buf: &[u8]) -> bool {
src/search.rs:495:8:[— search_file]     if is_binary(&buf) || !matcher.worth_searching(&buf) {

The bracket shows the enclosing symbol and how deeply this session has read it. → Searching Code

Find callers from the grammar's call nodes, never from comments or strings:

ambits -p . callers centered_rect

→ Finding Callers

Read one symbol, not the file — by id or content hash, as JSON:

ambits -p . show 'src/app.rs::App/process_compaction' b3:53a28842

→ Reading by Symbol

Recall what it has already read, with line ranges that stay correct after edits:

ambits -p . restore-context

### src/digest.rs — 47 symbols (~13.7k tok)
grouped:64-84, symbol_label:104-119, fit_names:126-141, …

→ Restoring Context

For you

The TUI (ambits -p .) tails the session log live: a symbol tree shaded by read depth, coverage stats, an activity feed, per-agent filtering for sub-agents, and compaction history. → TUI

Coverage reports for scripts and CI:

ambits -p . --coverage                                   # table
ambits -p . --coverage --format json | jq '.totals.full_percent'

→ Coverage and Multi-Agent

Snapshots and sharing: a session's reads and writes as durable, content-addressed history, shared through any directory:

ambits -p . snapshot && ambits -p . remote add origin /mnt/team/ambits && ambits -p . push
ambits -p . fetch && ambits -p . restore origin/<session>   # on another machine

→ Snapshots, Sharing

Traces: every tool call a span, subagents nested under their delegation, for any OpenTelemetry backend or Perfetto:

ambits -p . trace > session.otlp.json
ambits -p . trace --format chrome > session.trace.json   # open in ui.perfetto.dev

→ Traces

Languages

Search covers every text file; a file no parser handles simply has no symbols.

Documentation

Full docs are in the wiki:

• Getting Started — install, hook, skill, first session
• Configuration — read journal, scope filters, tools.toml, logging
• Portability — formats and provider seams
• Architecture — the memory loop and query pipelines
• CLI Reference — every command and flag

The wiki's source is docs/wiki/; edit it there.

Building from source

Requires Rust 1.88+ (declared as rust-version in Cargo.toml).

cargo build --release
cargo test