AmbitGet startedFAQReferenceGlossaryAll docsGitHubLive demo

Ambit

Every MCP server your AI agents have, on one local map: what they can do together, what one more step would open, and which pieces actually work.

Ambit reads the MCP configs of Claude Code and its plugins, Codex, Cursor, OpenCode and 12 other agents into one local graph, drawn as a tree of capabilities in eras. What you, your agents and your machines can jointly do is your ambit: this shows where its edge is and how to move it.

CI Release Node License: MIT Glama Score

Try the live demo · Get started · Connect it to your agent · FAQ · Docs


Ambit showing one developer setup as a map: Embeddings, a next step, is selected and simulating it rings in blue the two capabilities it would make reachable; then Shell Execution is switched off, what depends on it turns red, and nine working capabilities would stop; a second view colors the tools that interrupt a person most often, and a proposed config change waits for approval

Pick a next step and the map shows what it opens. Switch off something you rely on and it counts what stops.

npx ambit-cli, or brew install zz-plant/tap/ambit && ambit, or open the hosted demo and install nothing.


When you'd reach for it

When Run What it tells you
You want your agent to do something it cannot yet ambit goal "deploy on merge" The steps from what you already have, in order, each with a setup estimate
You use two agents and cannot say which has what ambit Every agent's MCP servers on one map, Claude Code's plugins included, and the step that would open the most
A server stopped answering, or a token expired ambit verify --mcp --remote Which servers answer, local or remote; ambit impact <id> names what stops with one that does not
You start on a new project ambit repo What the project uses, and the server to add for it, with the command that adds it
You approve the same permission prompt all day ambit authority What may run without asking, beside what Claude Code's own rules say

Under each answer is one graph of what your servers, models and skills add up to. Tools compose: a vector store plus local embeddings gives you semantic retrieval, which neither config mentions. Three providers that share one API credential show up as one point of failure.

Run it once to see what you have, then again after any change. A token that expired, a server that moved, or a binary that broke shows up as failing, and the next check proves the repair.

Your agents can ask the same questions, over MCP or through a skill: what they can do before they try, and at a limit, what would lift it, drafted as a change you approve. The graph is a local SQLite file, with no telemetry.

Three facts stay apart: configured, working, and allowed. A configured server may fail its check, and a working one may still not be permitted to run without asking. Ambit reports each separately, and never lets one stand in for another.

On a small setup, Ambit mostly answers what to add next. On a larger one, with several runtimes and a second machine, it mostly answers which configured tools fail their checks and what would stop with them. The words it uses are defined further down.

If it answers a question your config files could not, a star is how the next person with the same stack finds it.

Get started

Way in What it gives you
In the browser Open the hosted demo for a sample setup, or drop in your own MCP config from Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, Cline, Roo Code, Copilot CLI, Kiro or OpenCode, and it is placed on the map in the tab, uploading nothing, with what one more step would open for it. No file at hand? Tick the servers you run.
On your machine npx ambit-cli (Node 22.18 or newer), or brew install zz-plant/tap/ambit && ambit, reads your real agent configs, names what it found, and shows what one more step would open. It ends on one thing to do, npx ambit-cli web: the same readout on the map, served on localhost. npm install -g ambit-cli puts ambit on your path.
From a checkout git clone https://github.com/zz-plant/ambit.git && cd ambit && ./bootstrap.sh web builds the graph from your own configs and serves the same map from source.
In a cloud IDE Open in GitHub Codespaces A full checkout with the map running, in a browser tab, touching nothing on your machine. The container holds none of your configs, so the map it shows has nothing of yours on it: a way to try the code, not to map your setup.
From your agent Register Ambit over MCP, or install its skill in any agent that reads Agent Skills, and the agent can ask what it is able to do before it tries. Connect it to your agent has both.

What it reads. The MCP configs of OpenCode, Claude Code, Cursor, Windsurf, Gemini CLI, Claude Desktop, Codex CLI, Cline, Roo Code, Continue, Zed, VS Code, Copilot CLI, Amp, Goose and Kiro; from Claude Code, also the servers and skills of each plugin you have turned on, and by name the servers a project commits in its .mcp.json; the skill directories ~/.agents/skills, ~/.opencode/skills and ~/.config/opencode/skills; and the names of the models Ollama and LM Studio keep on disk. Where each AI agent keeps its MCP config gives every path.

Where it runs. npm installs the tagged release on macOS, Linux and Windows, and Homebrew on macOS and Linux. On Windows ./bootstrap.sh does not run, ambit weigh cannot start a server launched through a .cmd such as npx, and a check written for sh stays unverified unless Git Bash or another sh is on the PATH. In a checkout, ./bootstrap.sh builds the graph, prints the same readout npx ambit-cli does, and links ambit into ~/.local/bin when that directory is on your PATH (or prints the ln -s line when it is not); --dry-run writes nothing and reports whether there is an OpenCode config, a running Ollama and a skills directory.

The My Setup view: MCP servers, agents, and models read from local config, one row each, with what the engine has proved about them and the capabilities each provides
My Setup lists every server, agent, and model found on the machine: whether it is on, what its check said, and which capabilities on the map it provides

Where Ambit sits in the stack

Ambit sits beside the agent, above the protocol and below workflow orchestration. Its CLI and MCP server neither route an agent's calls nor run them. Its one hook on the call path, ambit gate for Claude Code, can only deny a call or ask about it. The one part that can run a step is the control plane, a reference implementation you start yourself from a checkout.

If you want to Use What Ambit adds
Find a tool by name or description Smithery, the MCP registries, tool-RAG Which ones your setup already has what it needs for, and what each would open
Order the steps of one task A workflow engine such as LangGraph Nothing inside the task; what the setup can do before one starts
Install a binary Nix, Homebrew No installing; what is missing, in order, as a change you approve
Allow or refuse each call as it happens Your runtime's permission mode, or an MCP gateway No place on the call path; ambit authority shows Claude Code's rules beside your grants, and the gate only adds a deny or an ask
Keep one server list in every runtime A config sync tool such as vsync or mcp-sync Which of those servers work, and what they add up to
Track tokens, cost and plan quota ccusage and the tools around it Tokens per model in Time & cost, beside what the setup can do
Scan tool descriptions for poisoning A scanner such as Snyk Agent Scan Nothing on that; what each tool may do without asking
See what the whole setup can do, which pieces work, and what to add next Ambit

The ideas behind Ambit says what is new and where it comes from, From A to B walks one setup through seven steps, and Building alone is the launch checklist for a one-person company.


Ask from the terminal

Command What it answers
ambit status Environment health: what is reached and how much of it is verified, what is failing its declared check, what has a single provider, pending approvals, and the one command to type next
ambit goal <name or "sentence"> The path to a capability, in order, with setup estimates; a sentence is routed to the tree first
ambit repo [dir] What to add for the project you are in, from its dependencies and the servers you already run
ambit impact <id> What downstream stops working if this dependency fails
ambit graph combos Compound capabilities, including the ones you are one prerequisite away from
ambit authority Per-action permissions: what runs unattended, what needs confirmation, and where Claude Code's own rules disagree
ambit verify [id] Run a capability's declared check and record whether it passes; --mcp --remote asks each MCP server, local or remote, whether it answers
ambit history [since <when> [<until>]] How the frontier, the edge of what you reach, moved, separating what you acquired from what emerged
ambit share A self-contained HTML snapshot of the map, written locally and safe to post

ambit help covers a first session. ambit help plan, or any of the five group names, lists what that group holds, one line a command; ambit help goal shows one command with its options, ambit help frontier explains one word, and ambit help --all is the full surface. --help after any command says what it does without running it.

The commands above read the capability graph. A second group (attention, work, usage, opportunities, roi, audit) reads a local session history: the human time and cost of running the stack. Until sessions are recorded they say which data is missing instead of printing a number, and they say more once a few weeks are recorded. The FAQ explains how to start recording.

ambit status — where the environment stands

$ ambit status

    15 of 46 reached, and 20 of your own · 0 verified · 8 with a single provider
    ────────────────────────────────────────────────────────────────────────
    verified        0
  › unverified     15  11 provable now · 4 with no check
    failing         0
    entries        24  from your config, and 4 built into the runtime
    last check  never

    Provable now  Automated Tests, Browser Automation, Code Intelligence, Continuous Delivery, Data Access, File Editing, Local Runtime, Shell Execution and 3 more

    By domain
      ████░░░░░░ ai-ml     5/13
      ██████░░░░ backend   7/11
      █████░░░░░ devops    4/8
    …

    Next  ambit verify · turns 11 of the unverified into evidence

This is a fresh graph, before any check has run: reached and verified lead, the curated capabilities first and then the servers, models and runtimes of your own, the four counts under the rule add up to the two reached figures together with the four built-ins every runtime brings, the › marks the count that wants a person, and the last line names the next command to type. CI captures the block from a fixture graph and fails if it drifts from what the command prints.

ambit impact — downstream dependency impact

$ ambit impact mcp:playwright

    If playwright went away
    ───────────────────────
  › Stops working  Automated Tests, Browser Automation, Continuous Delivery, Observability · and the 3 actions they confer
    Survives  Tool Protocol (12 other providers)

Affected capabilities are listed first, marked with ›, through the full dependency chain: if Continuous Delivery requires Automated Tests, it fails as well. Surviving capabilities show their remaining provider count, accounting for shared credentials that would fail together. Given a credential, impact answers what revoking it ends, matching ambit credentials.

ambit share — what may leave the graph, and what may not

ambit share builds its HTML from an allow-list: name, kind, category, domain, era, state, lifecycle, edges. Commands, URLs, paths, descriptions and economics cannot enter the file, people render as "a person", and --redact replaces every non-curated name with its category. Nothing is uploaded; writing the file locally is the whole command.

From a script, or an agent's shell

--json prints any answer as data, color is drawn only on a terminal, and the exit code says whether the command worked. Two commands can gate a script the way git diff --exit-code does:

ambit can shell-execution --exit-code     # 0 go ahead, 1 put it to the person, 2 stop
ambit verify shell-execution --exit-code  # 1 unless every check that ran passed

The CLI reference has every exit code and flag.


Connect it to your agent

You can try Ambit before connecting it to anything: ambit status reads local agent configs and session token logs (Claude Code, Codex, OpenCode, Amp) and writes only to Ambit's own database (~/.local/share/ambit/graph.db). It modifies no configuration file and makes no network request, and deleting that file removes what it recorded. llms.txt outlines when an agent should recommend Ambit, and For agents shows session metrics from before and after.

Claude Code

Install the plugin from the marketplace:

claude plugin marketplace add zz-plant/ambit
claude plugin install ambit@ambit

Then type /ambit in a session for the readout of your own setup: what it read, how much of the tree that reaches, and the step that would open the most. The plugin registers the MCP server, gives the agent a briefing at session start, and logs tool execution and approval spans to ~/.local/state/ambit/claude-code.jsonl. It reads token usage from local session logs without writing to them. To disable recording, set AMBIT_NO_LEDGER=1.

To register manually without the plugin:

claude mcp add ambit -- ambit mcp --profile=agent

--profile=agent advertises ten tools, the planning and verification ones an agent uses to check before it acts, in about 4.4KB of prompt context. Omitting the flag advertises every tool (~18.6KB). The server answers an unlisted tool by name either way, but most clients call only what they were shown, so under --profile=agent the connect instructions send the agent to the ambit command for the rest: single points of failure, budgets, incidents, the audit trail, everything ambit help --all lists. The deep dive lists every tool and explains how calls are dispatched.

ambit-gate@ambit is a companion plugin that puts ambit gate on every tool call, so what you refused or set to ask first in Ambit is denied or put to you. The hook block below does the same by hand. Without the plugin, ambit connect claude-code --gate adds the same hook to ~/.claude/settings.json. Until one of them is on, a grant is a record ambit can answers from and a tool call that does not ask still runs; ambit authority grant, ambit budget set and ambit doctor say so.

Ambit also publishes ambit://briefing, a resource a client reads on connect: what is reached and verified, what is failing, what is waiting on you, what blocked work in the last week, and what is worth reaching next with what each step would reach, in about 1,200 tokens. To put it at the top of every session yourself, add a hook to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "ambit briefing" }] }],
    "PreToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "ambit gate", "timeout": 10 }] }]
  }
}

The PreToolUse hook puts Ambit's brake on Claude Code. Before each tool call, ambit gate identifies the capability exercised: forbidden actions are denied, actions requiring human confirmation prompt the user, and permitted or unmapped actions defer to Claude Code's standard permission flow. Despite the command's name it works as a brake: it can stop a call or ask, and never allows one. It adds about 130 ms per call (measured with 0.6.0 on an Apple M1 Max). Run ambit gate directly in a terminal to inspect its output.

ambit statusline prints a segment for Claude Code's status bar, refreshed after each message: failing checks, pending proposals, and verified capability counts (e.g. ! 1 failing: Browser Automation · › 2 proposals to decide). Inactive categories are omitted, so a healthy graph displays 12 verified. It queries the database read-only, writes nothing, and returns in about 80 ms (measured with 0.6.0 on an Apple M1 Max). Because plugins cannot configure status lines automatically, ambit connect claude-code --statusline adds the entry to ~/.claude/settings.json, backing up the existing file to settings.json.bak and never overwriting a status line you already have. To configure manually:

{ "statusLine": { "type": "command", "command": "ambit statusline" } }

Claude Code runs one status line command. To keep yours and add Ambit's, save these two lines as a script, with your command in place of npx ccstatusline, and point command at the script:

input=$(cat)
printf '%s  %s\n' "$(printf '%s' "$input" | npx ccstatusline)" "$(printf '%s' "$input" | ambit statusline)"

OpenCode

ambit connect opencode adds the entry to ~/.config/opencode/opencode.json in whichever shape the file already uses, OpenCode 1's or 2's, and keeps what the file held in opencode.json.bak first. A file with comments is left alone, since writing it back would delete them. By hand, in OpenCode 1's shape:

{
  "mcp": {
    "ambit": {
      "type": "local",
      "command": ["ambit", "mcp", "--profile=agent"],
      "enabled": true
    }
  }
}

OpenCode 2 puts the same entry under mcp.servers, with "disabled": false in place of "enabled": true.

Both clients assume ambit is on your PATH. Homebrew and npm install -g ambit-cli put it there, and bootstrap.sh does when ~/.local/bin is already on your PATH. Otherwise use npx -y ambit-cli mcp --profile=agent, or the absolute path to cli.js. An agent can read the map, ask what a goal is missing, and propose a configuration change. Applying one always requires an approval, and approving is a separate local operation, not an MCP tool.

Cursor

ambit connect cursor adds the server to ~/.cursor/mcp.json. With --ledger it also adds a hook to ~/.cursor/hooks.json on four events, beside any hooks already there, keeping what the file held in hooks.json.bak; --dry-run prints the hook's command and events and writes nothing. The hook appends one line per event to the file the Claude Code plugin writes, ~/.local/state/ambit/claude-code.jsonl: when it ran and the conversation's id; for a shell command or MCP call that ran, the server's and tool's names and how long Cursor says it took, your wait for approval left out; for a failed call, Cursor's id for it, its error text, its failure kind and whether you stopped it; and why a conversation ended. Never a command's text or output, an MCP call's arguments or result, a file, your prompt or your email. Cursor's hooks report no token counts and no approval prompts, so a Cursor run records neither. The hook asks Cursor for nothing, so it can neither block a call nor allow one, and AMBIT_NO_LEDGER=1 turns it off. By hand, with the path the dry run prints:

{
  "version": 1,
  "hooks": {
    "afterShellExecution": [{ "command": "node /path/to/ambit-cli/plugins/cursor/ambit-ledger.mjs", "timeout": 5 }],
    "afterMCPExecution": [{ "command": "node /path/to/ambit-cli/plugins/cursor/ambit-ledger.mjs", "timeout": 5 }],
    "postToolUseFailure": [{ "command": "node /path/to/ambit-cli/plugins/cursor/ambit-ledger.mjs", "timeout": 5 }],
    "sessionEnd": [{ "command": "node /path/to/ambit-cli/plugins/cursor/ambit-ledger.mjs", "timeout": 5 }]
  }
}

Any agent that reads skills

Codex CLI, Cursor, Gemini CLI, Copilot and most other agents read Agent Skills folders. skills/ambit/SKILL.md teaches one to ask ambit can before a tool it has not used, and which command answers which question, through the ambit command, with no MCP connection. Install it with npx skills add zz-plant/ambit, or copy the skills/ambit folder into ~/.agents/skills/. The npm package ships it too.

The one habit worth teaching

Before running a tool you have not used this session, call ambit_can with the tool's own name or the capability. On yes, act. On ask, put it to the person. On no, it has already recorded the deficit, so do not retry it under another name.

The server sends this instruction in the MCP handshake. For clients that do not expose server instructions to the model context, ambit init-rules writes the guidance into CLAUDE.md, AGENTS.md, or .cursorrules. Agents with shell access but no MCP connection can check permissions using ambit can <capability> --exit-code --record. Either way the question can name the tool as the runtime does (Bash, mcp__github__create_issue, or Bash(git push origin main)), and the answer lists each capability the call exercises, with the Claude Code permission rule that names it when one does. With --record a refusal is recorded as a deficit in the session history, and a deficit that recurs moves up the ranking of what to set up next; a person typing ambit can records nothing.

An agent hits a missing capability, asks Ambit why over MCP, and drafts a proposal; a person approves and applies it; the frontier moves and Local Embeddings unlocks through composition
Agent: hits a block, records the deficit, asks goal, drafts a proposal · Human: approve, apply · One config patch, four capabilities. Every frame is real engine output, re-recorded by scripts/demo-agent-loop.ts.

The map

The Ambit capability map: tools and skills drawn as connected nodes in themed eras
Filled nodes are reached · Bright rings are a next step, with their setup time · Dashed nodes are blocked, with a prerequisite missing · The line on top is what the map found

ambit web serves five views over the graph the CLI reads (./bootstrap.sh web in a checkout).

Selecting a node displays downstream dependencies that fail if it goes down, or missing prerequisites and estimated setup times needed to reach it. Simulate an outage renders that cascade, filled red for broken dependencies, a red outline for unconfigured nodes, and amber for capabilities losing redundant providers. Simulate unlocking highlights nodes made reachable by acquiring a single prerequisite. Neither simulation writes data. Three lenses filter the map: Standard (reached, next step, blocked), Attention (tools causing frequent human interruptions), and Authority (unattended, human confirmation required, forbidden).

When an agent proposes a configuration change over MCP, the Proposals view shows it as a plan before you sign: its steps, which of them cannot be undone, the capabilities it would unlock, its costs, and earlier approvals that bear on it. Approving creates a signed artifact, and ambit apply writes the change into Claude Code, Cursor, OpenCode or whichever runtime --to names, or prints that runtime's own command where it cannot.

The reference covers the rest: what each mark means, focus, the minimap, the timeline that replays the map as it was, deciding several drafts at once, and pushing one to your phone.


How it works

An ambit (from Latin ambitus: circuit, perimeter, sphere of action) is the boundary of what someone can reach. Working with agents, yours is set by a stack spread across LLM providers, MCP servers, local CLI tools, skill directories, credentials and machines, each with its own config file.

What an agent setup can do is not written in any configuration file. It is composed from pieces configured separately, a configured piece may not work, and none of it says what the setup is allowed to do. Ambit computes that reach and helps you widen it: a declared check says whether a piece works, a grant you set says what may run without asking, and a session history records whether a change saved you time.

Every server, model, skill and declared credential is a node in one model, the capability graph, as is every capability of the curated tree, and an edge records what one needs from another or provides to it. The edge of what you reach is the frontier, with the next steps just past it.

Discovery reads your host configs into an embedded SQLite graph, and three surfaces read it back out: the CLI, the MCP server and the map. Discovery, verification and the session history write to the graph. Your agent configuration changes only through a proposal you approve, or through the map's switch for an entry that already exists, which cannot create one.

Each client is read from its own standard config path, and every server stays attributed to the client that listed it. If two runtimes reference the same server, Ambit models it as a single capability with two providers, so one binary listed twice is not counted as redundancy. Local models are found in the folders Ollama and LM Studio keep on disk, so neither server has to be running. Each is filed under a local provider, keeping it separate from hosted inference costs.

Discovered capabilities are placed in a curated tree of nine eras: seven for the agent setup, from Foundation and Model Access through Tool Use, Memory, Autonomy and Assurance to Sovereignty, and two for the product it builds, Product (hosting, a production database, accounts, payments, email) and Operations (error tracking, analytics, uptime, backups, and Launch Ready, reached when the launch checklist is done). Each capability names its prerequisites, so what is reached is computed from them, not taken from what a config claims.

Configured is not working

Of the three facts, Ambit stores the first two on each capability:

Availability is decided by lifecycle, not state, and a check can only take availability away: an unverified capability stays in plans, and one whose check fails is excluded from plans, simulations, goals, authority checks, and opportunity rankings. A single successful check restores a broken capability to unverified status, and it is marked as recovering until five consecutive checks pass. ambit status reports verified, unverified and failing counts, and the map badges each reached node: ✓ for a passing check, ! for a failing one, nothing for configured but never verified, or recovering.

Fragility is computed, not guessed


The words Ambit uses

The terminal and the map use the same words.


The control plane

A step routed through the control plane runs only if the graph says it may: prerequisites present, the capability passing its check, and the caller authorized. It is a reference implementation that runs from a checkout, not part of the ambit command, and by default it runs nothing: its executor merges a change into a JSON file. An opt-in Docker adapter runs an approved step in a throwaway container with no network. It is kept as it is and not extended, since the runtimes' own permission modes and MCP gateways now own the call path. The control plane describes it in full.


Security invariants

Ambit reads developer toolchains and writes to agent configs, so the properties below are fixed. SECURITY.md states each in full, with what is in scope and what is not; the servers guide says where each is enforced.

  1. Loopback only. The API server binds 127.0.0.1. No LAN, no tunnel.
  2. Origin allowlist. A request whose Origin is not Ambit's own page, a page on another localhost port included, is rejected with 403 before routing, because a simple request skips preflight and response headers alone would not stop it.
  3. No entry creation over HTTP. The HTTP layer edits entries that already exist and nothing else. An MCP entry carries a command the runtime later executes, so creating one over HTTP would be remote code execution; adding a server returns a snippet for you to paste.
  4. No egress you did not type. The graph is an embedded SQLite database on your machine, and there is no telemetry. Nothing opens a socket, starts a server or runs a check unless you type the command or an agent calls the tool, and the server never does any of it. The FAQ lists every command that can reach the network, what it sends and where.

Documentation


Contributing

Ambit is in focused mode: it takes fixes, reports of where it read a setup wrong, and work that makes the capabilities it already has more reliable, and declines new integrations added for completeness. CONTRIBUTING.md lists three kinds of small, self-contained change worth starting with; an issue carries good first issue once somebody files one against them. CONTRIBUTING.md gets you from a clone to a passing pull request and lists every check CI runs.


Support the project

Ambit is a personal project. It has one maintainer, so the fastest help is telling it where it got your setup wrong.


License

MIT © Kanav Jain

See what your own agents can reach

Ambit reads the MCP configs of Claude Code, Cursor, OpenCode and thirteen more agents into one local map: every server, which ones work, what one more step would open, and what breaks if a piece goes.

Open the live demoa sample setup in your browser, nothing to install

On your machine: npx ambit-cli, with Node 22.18 or newer on macOS or Linux.

MIT licensed · one local SQLite file, no telemetry · on npm and in the official MCP registry