# Ambit

> A capability graph for AI agent environments, and a meta-MCP server: what you, your agents, and your machines can jointly do, what breaks downstream, and what is worth setting up next.

Ambit reads the configs of OpenCode, Claude Code, Cursor, Windsurf, Gemini CLI, Claude Desktop, and Codex CLI into one local SQLite graph. Every tool, model, skill, and credential becomes a node; everything one needs in order to work becomes an edge. Three surfaces read that graph: a terminal CLI (`ambit`), an MCP server (`ambit mcp`, 60 tools), and a web map. Discovery, verification, and the work ledger write to the graph, so MCP tools such as `ambit_run_begin` and `ambit_work_event` record rows in the local database. Your agent configuration is different: it changes only through a proposal a person approves, or through the map's editor for entries that already exist, which a person operates and which cannot create an entry. Nothing leaves the machine except two opt-in pushes to ntfy: `ambit notify <topic>` sends the attention digest (capability names, intervention counts, suggested fixes) and `ambit notify-approvals <topic>` sends the ids and goals of approved proposals awaiting apply.

Vocabulary: a *capability* is one thing the setup can do. Its *era* is how far up the curated tree it sits. A capability is *reached* (something provides it), *next* (prerequisites met, nothing detected), or *blocked* (a prerequisite is missing). *State* is structural (configured or not); *lifecycle* is health (its declared check passed or not), and availability decisions gate on lifecycle.

## Docs

- [README](https://github.com/zz-plant/ambit/blob/main/README.md): what it is, install, the CLI, the MCP surface, security invariants
- [Deep dive](https://github.com/zz-plant/ambit/blob/main/docs/deep-dive.md): nodes, assurance checks, authority contracts, the work ledger, every MCP tool
- [FAQ](https://github.com/zz-plant/ambit/blob/main/docs/faq.md): short answers to the common questions
- [Why Ambit](https://github.com/zz-plant/ambit/blob/main/docs/why-ambit.md): the argument for modelling capability as a property of the whole system
- [Agent guide](https://github.com/zz-plant/ambit/blob/main/AGENTS.md): repository layout and the invariants a change must not break
- [Security](https://github.com/zz-plant/ambit/blob/main/SECURITY.md): loopback only, no entry creation over HTTP, local data only

## Use it from an agent

- Register: `claude mcp add ambit -- ambit mcp`
- On connect, read the resource `ambit://briefing`: what is reached and proven, what is failing, what is waiting on a person, what blocked work recently, and what is worth reaching next, in about 1,200 tokens
- Before running a tool you have not used this session, call `ambit_can` with the capability. `yes` act, `ask` put it to the person, `no` do not retry it under another name — the refusal has already been recorded as a deficit
- To close a gap, call `ambit_next` or `ambit_goal`, then `ambit_propose`; a person approves and applies from the terminal or the map
- A skill you wrote yourself goes on the map with `ambit_register_skill`, which requires a read-only command that proves it works and runs it immediately
- Before touching a target you have not touched, call `ambit_objects` with it: what may be done there, and what has been proved there. Evidence about one repository is not a claim about another
- `ambit_promotions` lists grants that have earned a threshold nobody has set. Surface them: a person who sets one is never asked about that action again. Setting it is their act, never yours

## Optional

- [Live demo](https://zz-plant.github.io/ambit/?demo=1): the map on example data, nothing to install
- [Roadmap](https://github.com/zz-plant/ambit/blob/main/docs/roadmap.md): where the data model is heading
- [Changelog](https://github.com/zz-plant/ambit/blob/main/CHANGELOG.md)