AmbitGet startedFAQReferenceGlossaryAll docsGitHubLive demo

FAQ

Ambit reads the MCP and agent configs on a machine into one local map: what the setup can do, which pieces work, and what one more step would open. Terms are defined in the README, and ambit help <term> looks any of them up from the terminal.

Is this for me

How is this different from listing my MCP servers?

A list shows what is configured; Ambit shows what the list adds up to. It records what each capability needs, so it can answer the questions a list cannot: what breaks downstream if this credential is revoked, which capability you are one prerequisite away from, and which tools interrupt you most. The comparison table in the README places it next to tool-RAG, workflow graphs, and package managers, and the ideas behind Ambit says what in it is new.

Do I need Claude Code for this?

No. Ambit reads each of these runtimes from its standard config path: OpenCode, Claude Code, Cursor, Windsurf, Gemini CLI, Claude Desktop, Codex CLI, Cline, Roo Code, Continue, Zed, VS Code, Copilot CLI, Amp, Goose, and Kiro. Where each AI agent keeps its MCP config gives every path. It also reads the skill directories ~/.agents/skills, ~/.opencode/skills and ~/.config/opencode/skills, and the names of the models in Ollama's folder (~/.ollama/models, or $OLLAMA_MODELS) and LM Studio's (~/.lmstudio/models, or ~/.cache/lm-studio/models from older versions; AMBIT_LMSTUDIO_MODELS names a folder you moved). A model file is never opened, and a model server is never asked. A server that two clients both list is one capability with two providers, not two capabilities. Adding a reader for another client is one of the most useful contributions; CONTRIBUTING.md points at where they live.

I use Jev. Where does it fit?

Ambit maps TypeSafe's Jev as Typed Judgment, in the Model Access era (a column of the map), and finds it however it arrives: as one of its MCP servers, as TypeSafe listed as a provider, or as an open clone that serves the same API. Cloudflare's Clef models answer in the same shape and are mapped the same way. A clone such as Kev or LitJev running on your own hardware also reaches Local Typed Judgment in the Sovereignty era. The difference matters because the hosted API may keep requests for a while unless you have a zero-retention agreement, and a local clone keeps the state it judges on your machine. ambit verify combo:local-typed-judgment asks the clone one trivial question on this machine and records whether it answered; it never contacts the hosted API. A clone can also route goals the tree's words do not cover: ambit goal "triage incoming bug reports" --judge puts the sentence to it as a Choice over the tree, and prints the likeliest capability with its probability as a suggestion. It writes nothing.

Use Jev to decide what to try, and ambit_can to decide whether it may run. Jev returns a probability, and text inside the state it reads can move that probability. In one published test, injected text dropped Jev's probability of blocking rm -rf ~/.ssh from 0.76 to 0.48. Ambit's answer to whether an action may run comes from a grant a person set, so nothing an agent reads can widen it.

MCP servers

How do I list every MCP server I have?

Run ambit status: it reads every runtime's config at once and names each server, whether it passes its check, and the next step. Without Ambit, read each file by hand; Where each AI agent keeps its MCP config has the path and key for all sixteen.

Why isn't my MCP server working, or not showing up?

Three faults look the same from the agent's side: the server is not declared, it is declared and fails to start, or it works and the agent is not permitted to call it. ambit status separates them. My Setup lists what was declared, a failing check marks a server that starts and fails, and ambit authority shows what may run without asking. ambit verify <id> runs the check again, and ambit impact <id> shows what stops with it.

How much of my context window do my MCP tools use?

Each MCP server's tool list is sent to the model every session, whether or not a tool is called. ambit weigh starts each local server your user-level configs declare, asks for its tools, and reports what the list costs in context, per runtime, plus which servers the session history, Ambit's local record of agent runs, never saw called. It starts the servers once, so run it when you are willing to.

Does Ambit send my code or config anywhere?

Not unless you type a command that does. Does anything leave my machine? lists each one, with what it sends and where.

How do I get from here to a goal?

State the goal in a sentence. ambit goal "launch my saas" routes it to a capability on the map and prints the steps in order, each with setup time and the usual ways to do it. A step you have half done says so. If no phrase in the curated tree matches, --judge asks a judgment model on this machine and returns a suggestion that writes nothing.

Installing and running

What do I need installed?

Node 22.18 or newer, and nothing else. The engine, the CLI, the API server, and the test runner all use node:sqlite; the map is Vite, which runs on Node too. Python is only needed for npm run demo:incident, the terminal walkthrough.

Can I npx it?

Yes. npx ambit-cli reads the MCP and agent configs on this machine, builds the graph, and shows what one more step would open, with nothing installed. To keep the ambit command:

npm install -g ambit-cli          # or: brew install zz-plant/tap/ambit

ambit web opens the map on localhost from any install, served by the same loopback-only server a checkout runs; --port=N picks the port. ambit share writes the map as one HTML file to send to someone.

How do I reset the graph?

Delete the database file ambit where names and run ambit seed (or ./bootstrap.sh in a checkout) again. Discovery is idempotent, and *.db is gitignored so a checkout never commits one.

What it touches

Does anything leave my machine?

Not unless you ask it to. The graph is a local SQLite file (ambit where prints its path), there is no telemetry, and the API server binds loopback only. Five commands open a socket from Ambit's own code, and the declared checks and ambit weigh can reach the network through the commands they run, as can a control-plane step you gave a network; those are the ones to check if you are auditing egress.

Command What it sends Where it goes
ambit notify <topic> The attention digest: which capabilities interrupted you, how often, and the suggested fix for each. One HTTP POST to ntfy, or to the server you name in NTFY_SERVER.
ambit notify <topic> --approvals Proposals waiting to be applied, by id and goal; and unapproved drafts, each with its id, goal, cost, recurring billing, and up to three capabilities it would unlock. The same POST.
ambit dispatch <id> (and propose/approve with --dispatch) One proposal: its id, goal, cost and what it unlocks, with the approve and reject commands; once approved, the signed artifact too. Never a command to run. One POST to the URL in AMBIT_APPROVAL_WEBHOOK or --to, in Slack, Discord, Telegram, ntfy or plain JSON shape. Nothing is sent without one.
ambit incidents Nothing. It sends an empty GET to each device status URL and service URL named in your infrastructure manifest ($INFRA_MANIFEST, or ~/.config/opencode/infrastructure.json), to see which are answering, and records what it found in the local graph. Those hosts, and nowhere else.
ambit goal "<sentence>" --judge (and goal --spec <path> --judge) The sentence you typed, and the name and one-line description of every node in the curated tree, with a "none of these" option, as one Choice question. Only when no goal phrase in the tree matches it. With --spec, one question for each task no goal phrase matches. One POST to a judgment model on this machine: --judge=<url>, AMBIT_JUDGE_URL, or Kev's default http://127.0.0.1:8009. If nothing answers there, the same sentence and nodes go to an embedding model on this machine instead: a GET of the server's model list (Ollama's, else the OpenAI-style /v1/models), unless AMBIT_EMBED_MODEL names one, and one POST to /api/embed, or /v1/embeddings if that is a 404, at AMBIT_EMBED_URL or http://127.0.0.1:11434. Any other host is refused before anything is sent.
ambit verify [cap] (and ambit apply, which runs the check of what it applied) Whatever the check's command sends. A declared check is a command, and the curated one for Web Research fetches https://example.com. An agent's ambit_verify call runs the same checks; the server never does. Wherever that command reaches.
ambit weigh [server] Whatever your tool servers send when they start. It starts each local server your user-level configs declare, as your runtime does, asks for its tools over stdio and stops it; npx fetching a package is the usual network traffic. It never contacts a remote server, and the server never runs it. Wherever those servers reach.
The control plane's exec, with AMBIT_ADAPTER=docker Nothing by default: the step's container has no network, and the adapter never pulls an image. With AMBIT_DOCKER_NETWORK=bridge and a grant for the network action on the step's capability, whatever the step's command sends. Wherever that command reaches, and only then.
ambit share [--redact] Nothing. It writes an HTML file you send yourself. Your disk.

Neither notify command sends anything without a topic. An ntfy topic is readable by anyone who knows its name, so pick one you would not guess. The share file is built from an allow-list; ambit share in the README says what may enter it. SECURITY.md lists the invariants.

What does Ambit store about my machine?

Names and structure. A credential is a node you declared in a credentials block, holding a name and a note; the schema has no column a secret could be written to, and discovery never reads one. The one command column in the database belongs to declared_checks, which holds a check a skill registered for itself, never anything read from your config. Discovery reads your config files and writes only the database. Writing back to one takes a person.

Can an agent change my configuration through Ambit?

Not on its own. An agent can read the graph, ask what a goal is missing, and propose a change over MCP. Read the proposal the way you read a pull request: what the file will say, what undoes it, and who signed it. Approving is the review; ambit apply is the merge, and ambit rollback is the revert. Approving and applying are not MCP tools. They run from the terminal or the map, outside the MCP tool surface, and ambit apply writes a .bak beside any file it edits. The visualizer also has a direct editor for entries that already exist, such as the switch that turns an MCP server on or off, in the detail panel and in the My Setup list. It writes to the config on a person's click without a proposal, after copying the file it replaces to a .bak, and offers the switch only for a server your config names; it cannot create an entry, because an entry carries a command your runtime executes. An approval is valid only for the capability named in the proposal that was approved, so an approval to install a linter cannot be spent on a deploy.

Where do I report a security problem?

Privately, through GitHub security advisories. Anything that lets a web page reach the local API, turns an HTTP request into a new executable config entry, or moves the graph off the machine is in scope, and an exfiltration path is high severity. SECURITY.md has the full scope.

Reading what it tells you

I ran ambit attention and it says nothing is recorded. Is it broken?

No. attention, work, usage, opportunities, roi, and audit price the human cost of running your stack, and they read from the session history, Ambit's local record of agent runs, which starts empty. They become useful after a few weeks of recorded runs.

In Claude Code, the ambit plugin records each session's tool runs, failures and approval prompts (Connect it to your agent has the install). In OpenCode, copying plugins/ambit-telemetry.js into ~/.config/opencode/plugins/ records every tool execution and permission prompt. In Cursor, ambit connect cursor --ledger adds a hook that records each conversation's shell commands, MCP calls and failures (Cursor says exactly what it writes). Claude Code, Codex, OpenCode and Amp sessions also give their token counts with no plugin, read from the session logs those agents keep, so Time & cost has a token figure, and the current five-hour window beside it, from the first ambit command after you use one; tool runs and approvals still need a bridge, and other runtimes do not feed the session history yet. The deep dive covers it.

What is the difference between "reached" and "verified"?

Reached is structural: something in your config provides the capability, and its prerequisites are met. Verified is evidence: its declared check ran and passed. Allowed is a third fact: a capability can be reached and verified and still ask before it runs. The database calls the first two state and lifecycle, and authority answers the third. A capability no check has run on is reached and unverified, and still counts. One whose last check failed is broken while still reached, and every availability decision leaves it out until the check passes again. One pass brings it back as degraded, which reads as recovering. It is usable, and unverified until its last five runs pass. ambit verify runs the checks, and ambit incidents is the check of each device and service your infrastructure manifest names; ambit status reports verified, unverified, and failing counts, and ambit authority says what may run without asking. The README section Configured is not working is the longer argument.

Something else?

SUPPORT.md says where each kind of question goes.

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