# Ambits

> A Rust CLI that gives AI coding agents symbol-level search, caller lookup, and a read history they can restore after context compaction. Built and tested against Claude Code.

Ambits is a Rust command-line tool that helps AI coding agents read code by symbol instead of by file, and remember what they have already read. The README describes two problems it targets: agents loading whole files to find one function, and agents losing everything they learned when the context window compacts. Ingestion is currently built and tested against Claude Code.

## What It Is

Ambits is a code-reading and memory layer for agents. For reading, it answers searches, caller lookups, and symbol fetches in terms of symbols, so an agent can request one function by ID rather than a two-thousand-line file. For remembering, it records every symbol the agent reads and how deeply, then hands that history back after a compaction so the agent does not have to rediscover it.

## Symbol-Aware Search and Lookup

Search wraps ripgrep, or GNU grep through `ambits grep`, and tags every hit with its enclosing symbol and how much of that symbol the current session has read. Caller lookup uses the grammar's call nodes, so matches in comments or strings are ignored. The `show` command returns a single symbol by ID or content hash as JSON, and `restore-context` replays the session's reads with line ranges that stay correct after edits.

## Claude Code Setup

Two one-time commands wire Ambits into Claude Code. `hook install` adds a SessionStart hook to Claude Code's settings so read history is handed back automatically after each compaction. `skill install` writes an agent skill that teaches the agent when to check its coverage and how to fetch definitions. If no project flag is given, Ambits finds the project by walking up to the nearest folder with `.git` or `.ambits`.

## TUI and Coverage Reports

Running Ambits in a project opens a live terminal UI that tails the session log and keeps the read journal. It shows a symbol tree shaded by read depth, coverage stats, an activity feed, per-agent filtering for sub-agents, and compaction history. Coverage can also be printed as a table or JSON for scripts and CI.

## Languages and Portability

tree-sitter is the default parser, covering Rust, Python, TypeScript, and Markdown. The `--serena` flag hands symbol work to Serena for any language it supports. Search still covers every text file; files with no parser simply have no symbols. All output is plain text or JSON with no vendor lock-in, according to the README.

## Update: Version 0.20.0

Version 0.20.0 is the latest GitHub release and is also the newest version published on crates.io. The project requires Rust 1.82 or later and runs CI through GitHub Actions with Codecov coverage tracking.

## Features
- Symbol-attributed search wrapping ripgrep or GNU grep
- Caller lookup from grammar call nodes
- Read a single symbol by ID or content hash as JSON
- Session read journal with per-symbol read depth
- restore-context to hand read history back after compaction
- Line ranges that stay correct after edits
- Claude Code SessionStart hook installer
- Claude Code agent skill installer
- Live TUI with symbol tree, coverage stats, and activity feed
- Per-agent filtering for sub-agents
- Compaction history view
- Coverage reports as table or JSON
- tree-sitter parsing for Rust, Python, TypeScript, and Markdown
- Serena backend for other languages
- Automatic project root detection
- Plain text and JSON output with no vendor coupling

## Integrations
Claude Code, Serena, ripgrep, GNU grep, tree-sitter

## Platforms
CLI

## Pricing
Free

## Version
0.20.0

## Links
- Website: https://github.com/joshLong145/ambits
- Documentation: https://github.com/joshLong145/ambits/wiki
- Repository: https://github.com/joshLong145/ambits
- EveryDev.ai: https://www.everydev.ai/tools/ambits