AmbitGet startedFAQReferenceGlossaryAll docsGitHubLive demo

Ambit reference

This is the long-form reference for how Ambit models capability. The README covers getting started and the three surfaces; this covers the model underneath, every command and tool, and the map in full. The argument for building it is why-ambit.md; the theory under that is the affordance frontier.

Contents

The model

The core idea · What a node is · Reaching further · People in the graph · Runtimes are nodes, not owners · Infrastructure belongs in the graph · Capability and authority are different things · The frontier ledger

What gets recorded, and what it buys

The session history · The economic loop · Previewing a change · Delegation records

The surfaces

The full CLI surface · The full MCP surface · The map, and what it is allowed to do


The model

The core idea

Configuration tells you what is declared. Ambit tries to tell you what those declarations amount to: what the setup can do, composed from its pieces, verified by checks, and kept apart from what it is allowed to do. The ideas behind Ambit is that claim in one page, with what is new in it.

A capability in a tool registry looks like "GitHub access: yes." The useful form is closer to:

Can diagnose a failing service, modify its repository, deploy a fix, verify recovery, and report the intervention, because the system currently has repository write access, shell execution, deployment credentials, monitoring visibility, network reachability, persistent execution, and the required human authorization.

That second description is effective capability, and it is the object Ambit is built around. Getting there means keeping apart three things that ordinary registries collapse into one:

installed ≠ working ≠ authorized

Your ambit is everything reached. Verified is the part of it there is evidence for, and permission is a separate layer over both. Ambit records the first two per capability, as state and lifecycle, and resolves the third from grants each time it is asked.

The roadmap argues for finer distinctions along the same chain: callable apart from installed, appropriate apart from authorized, delegated when another party supplies a step, persistent when it can act beyond one session. They are directions, not states the product records; what it records is state and lifecycle. Two pieces exist already: lifecycle tells reliable, which is five passing runs in a row, apart from verified, and a step a person supplies is modelled as a Joint capability (People in the graph).

Not every capability declares a check. Those that do are verified by it, and an action can declare one too: ambit verify act:version-control/commit_changes proves the action and not the capability that confers it. A device or service the infrastructure manifest names is checked by ambit incidents asking the URL the manifest gives it (Infrastructure belongs in the graph). Nothing applies without a signed approval artifact and a per-step canExecute pass, and how the reached set changes over time is recorded in the frontier ledger.

ambit verify            # run the declared checks, record what happened
  checked: 8 · verified: 8 · failed: 0
  Local Runtime   verified   23ms   reliability 4/4

ambit authority         # reached is not the same as permitted
  autonomous      File Editing · Parallel Execution
  needs approval  Shell Execution · Version Control · Continuous Delivery
  forbidden       Secret Management

ambit authority version-control    # and permission is finer than a capability
  exercisable     read_repository · commit_changes
  needs approval  push_branch · merge_to_default

ambit goal offline-capable
  goal: Offline Capable · steps: 2 · estimated setup: 25m
  1. Embeddings   2. Local Embeddings

What a node is

Every node says what kind of thing it is, and every edge says what the relation means:

capability   an action the system can bring about: the curated model's nodes
action       one concrete thing a capability confers, or that a person supplies
provider     what supplies a capability: an MCP server, a skill, a tool
resource     what a provider needs: a model, an inference endpoint, a machine
actor        a person: authority, money, judgment, physical access
runtime      an agent runtime, which contributes providers and does not own them
credential   what a provider authenticates with: the identity of one, never the secret

provides · contributes · requires · optional · authorizes · runs_on · uses

The graph holds every entry your configs declare and every capability as a node. The map draws the curated part of it, the tree, with your position on it, and My Setup lists the entries (the map).

Actions. A capability can declare a contract.can, the actions it confers, and each becomes a node with its own authority. That is what lets the model say may read the repository, may not merge to its default branch, which the coarse node cannot. ambit authority <cap> reports them; the map leaves them out of its era columns on purpose, because legibility is the point of that view.

Lifecycle. Alongside state, each capability carries a lifecycle derived from its providers and its recorded evidence. The argument for keeping the two apart is in the README, under Configured is not working; what follows here is where the lifecycle values come from.

Lifecycle When it holds
unknown nothing supplies it
detected something supplies it, but it is not reachable yet
configured reachable, with no check run against it
verified its check passed, and has not been run often
reliable five runs or more, and the last five all passed
recovering the last run passed after a recent failure
degraded the older name for recovering, on graphs seeded before the rename
broken the last run failed

verified and reliable are verified by their checks, as strong as the checks are. configured is reached and unverified, and counts. broken is failing: still reached in state, and left out of everything that decides availability. The latest check decides, so a recovering capability is usable: counted with the unverified because its record is mixed, and named wherever a summary would otherwise read as fixed, with how its recent runs went ("2 of the last 5 passed"). On the map its ring slips off its fill, further the more of those runs failed. Nothing writes the column directly. It is recomputed from the evidence on seed and after verification, which are the two moments the inputs can change. A failing capability comes back the same way it left, on a check: ambit verify <id> re-runs one, and ambit verify --failing re-runs every check that is failing or recovering now, which is the command to type after fixing a shared token or a server. One pass brings a capability back into every plan, permission and ranking. It reads as verified once its last five runs pass, and a grant waiting on a threshold still widens only on a window with no failure in it. Nothing re-runs a check on its own, since a check is a command.

Credentials. A credential is declared, never read. A credentials block names one and the providers that present it:

{ "credentials": {
    "github/user-token": { "name": "GitHub user token",
                           "used_by": ["mcp:github", "tool:bash"] } } }

No secret is read or stored. Only the name, the holders and a note are consulted, so there is no field a value could arrive in and no column it could be written to. Sharing is declared, never inferred: guessing it from environment variable names would produce a redundancy claim nobody made, and a wrong one is worse than none. What the declaration changes is under Reaching further, in what the reach rests on.

Reaching further

Your ambit widens one capability at a time, and the graph says which one to reach next and what would come with it.

The curated tree is authored content, the same for everyone: each node names the capabilities it requires, and a machine differs only in where it stands on the tree. Every curated node is a combo, a capability the tree defines as composed from others, which is why every curated id is in the combo: namespace (combo:shell-execution). A combos block in your own config defines more, for compositions specific to your work. Ambit never infers one from a config, since a combo is a judgment about what composes. The tree's nodes sit in eras, and later eras depend on earlier ones. Eras describe ordering, not importance.

ambit next names a few capabilities worth reaching, each with why and a price. It ranks by what has actually blocked work first, from the deficits the ledger holds, then by how much each opens per hour of setup, and it says which basis it used. ambit council takes the first of those and reads it five ways, one seat per question the engine answers: Reach reads the frontier (what it opens), What could break reads fragility (what it would rest on), Cost reads the ledger (what stepping in for it has cost, and whether it pays back), Permission reads authority (what it would be allowed to do once reached) and Checks reads the checks (whether its foundation works). The JSON names the same seats science, defence, treasury, justice and interior. Each seat is one sentence, the command behind it and a stance, and the answer says when the seats are split; a seat with nothing recorded to read is silent. The frontier's recommendation and the fragility report used to be two reports read at different times, so a step could be taken on the first and found, from the second, to have put a fourth dependant on one credential. ambit graph combos lists the combos not yet reached whose required prerequisites all are. Those are compositions you already hold every piece of. ambit goal <cap> routes the longer way to one capability, step by step, and --simulate shows what reaching it would bring with it (Previewing a change).

A spec asks the same question once per task. ambit goal --spec specs/001-team-billing reads a Spec Kit feature (its tasks.md, and the tools its plan.md names under Technical Context) or an OpenSpec change, and answers before an agent starts on it. Each task line goes through the words ambit goal "<sentence>" matches and counts toward the capability those words recommend; the plan's Primary Dependencies, Storage and Testing go through the patterns a seed matches config entries with, so Stripe reaches Payments. The answer lists what is reached, what is failing its check, and the steps left in the order one plan would close them, a prerequisite several needs share listed once, ahead of them all. A task no words cover is listed as routed nowhere, never guessed; --judge puts those to a judgment model on this machine, or an embedding model there when no judge answers. The spec is read as data: no command in it runs, no link is followed, a fenced block is skipped, and only markdown is opened. ambit_goal takes the same path as spec.

What the reach rests on. A wider reach is worth what holds it up. Fragility is the guardrail on widening, not its purpose: it says which reach is safe to lean on. ambit impact <id> follows dependencies all the way down and names what would stop if one piece went, and what survives on another provider. ambit status lists the single points of failure, which are reached capabilities with one provider, and the map's outage simulation draws the same cascade.

Redundancy is counted by what fails together. A capability with three providers survives losing one, unless all three present the same token. Counting providers assumes they fail independently, and providers sharing a credential do not: one revocation takes all of them at once, while the capability reads as robust and, having several providers, stays off the single-point-of-failure report. Once a credentials block declares the sharing, ambit status lists the capability among its spofs, ambit impact calls what survives nominal and not redundant, and ambit credentials answers the question you have before rotating a token: what stops working. Only a credential every provider presents counts: given providers holding {A}, {A,B} and {B}, losing either leaves one standing, and calling that fragile would be the same overstatement inverted.

People in the graph

Humans supply what machines cannot (legal authority, money, physical access, judgment), so they are nodes, not users of the graph. An actors block declares them:

{ "actors": { "kanav": {
    "provides": ["physical-access", "approve-purchases"],
    "authorizes": ["combo:continuous-delivery"] } } }

provides becomes a capability only that person supplies. authorizes becomes a required (hard) prerequisite, so a plan says whose step it is:

ambit goal continuous-delivery
  goal: Continuous Delivery
  requires person: Kanav
  steps: 1 · estimated setup: 30m

A plan that hides the human step reads as autonomous when it is not. A capability chain can therefore run:

diagnose hardware failure → request replacement → human approves expenditure
→ vendor ships component → human installs it → agent configures it
→ monitoring verifies recovery

A capability a person approves or supplies is a Joint capability, which the agent cannot supply alone, and so is one that runs on your machines. It belongs to the human-machine system, not to either half, which lets partial, structured autonomy be described as it actually is instead of forced into "fully autonomous" or "human controlled". The map marks a joint capability with a person or a device, and the detail panel names who.

Every intervention is recorded. ambit attention counts the human acts in a window (approvals, applications, permission blocks, failed checks) and names the reducible ones: an approval given three times for the same capability is a candidate for a bounded grant, reviewed before it widens, not another reminder.

ambit attention 30
  interventions: 12
  3× approval: deploy to production
  2× permission block: restart svc:ollama
  2× failed: local embeddings
  reducible: deploy to production — grant bounded authority rather than approving each time

ambit notify <topic> pushes that digest to ntfy, and only when a topic is given. Nothing leaves the machine otherwise; the push is a single HTTP POST of the digest text, no graph data.

Runtimes are nodes, not owners

Ambit represents agent runtimes instead of being one. A runtime becomes a node, and everything it contributes hangs off it, so two runtimes configuring the same MCP server produce one capability with two providers, not two capabilities.

ambit seed finds the runtimes on this machine by itself: OpenCode, Claude Code, and the MCP config of every other client it has a reader for, Cursor and Windsurf among them. Where each AI agent keeps its MCP config lists the files it reads. From Claude Code it takes more than servers: ~/.claude.json and ~/.claude/ give MCP servers global and per project, skills, subagents and a pinned model, plus the authority the runtime states outright, its permission mode and how many allow, deny and ask rules are in force. It counts the rules and never copies them: an allow rule can name a path, and that is not Ambit's to put in a graph you may export.

The models on this machine come from the folders their servers keep them in, not from asking a running server, so discovery opens no socket. Ollama's manifests (~/.ollama/models/manifests, or under $OLLAMA_MODELS) give each model its name as ollama list prints it, and LM Studio's <publisher>/<model> folders (~/.lmstudio/models, or ~/.cache/lm-studio/models; AMBIT_LMSTUDIO_MODELS for a moved one) give each a name when a weight file is inside. They seed as model:local-ollama/qwen3-coder:30b under provider:local-ollama, and the same for local-lmstudio. The local prefix is the one the tree already reads a local provider by: Local Runtime, Local Tool Calling and Local Embeddings recognise them, Hosted Inference does not, and the spend meter never prices one as hosted. A model deleted from disk is retired by the next seed.

ambit impact runtime:<name> then answers what would be lost if that runtime went away. Where another runtime configures the same servers, the answer is smaller than the runtime's capability count, because what they share survives.

From a checkout. scripts/adapters/hermes.ts reads Hermes, which ambit seed does not. It prints what the runtime provides before anything is written, and adds it with --seed:

node --experimental-strip-types scripts/adapters/hermes.ts          # what Hermes provides
node --experimental-strip-types scripts/adapters/hermes.ts --seed   # add it to the graph

On one machine running both, that yields:

runtime:opencode — contributes 127 capabilities
runtime:hermes   — contributes 32 capabilities
shared by both   — mcp:fetch · mcp:filesystem · mcp:git · mcp:sequential-thinking

and ambit impact runtime:hermes leaves the shared four standing. The Hermes adapter also passes through what the runtime states about itself, such as approvals: manual and cron_mode: deny, and whether it has scheduled jobs, which is the difference between a capability that persists and one that lasts a session. Hermes has no machine-readable config export today, so the adapter reads its documented paths. That is a stopgap: the durable contract is for runtimes to publish their capability surface (ambit graph surface is that vocabulary) and for Ambit to consume it.

What each runtime carries. A runtime loads every tool server's tool list into the model's context at the start of each session, called or not. The list holds each tool's name, description and input schema. ambit weigh measures that by starting each local server the configs declare, asking for its tools over MCP and stopping it. It reads the configs the seed reads, never a project's committed .mcp.json, and does not contact a server with a url. The figure is an estimate at four characters a token of the list as the server sends it; a runtime that defers tool definitions until they are searched for carries less. Each runtime carries its own servers, so the total is per runtime and a server two runtimes declare counts in both. A server that would not start keeps the figure it last had, and one never weighed shows none. Once the session history has recorded calls, the report also names the servers carried into every session and never called in thirty days. My Setup prints each server's figure and each runtime's total from the same sum.

Infrastructure belongs in the graph

Agent capabilities do not stop at the model boundary. A local GPU, NAS, browser worker, Proxmox host, database, or cloud account can all contribute to what the system can accomplish.

Ambit scans infrastructure from an explicit local manifest (INFRA_MANIFEST, default ~/.config/opencode/infrastructure.json) and from the local Docker socket when one exists (DOCKER_HOST=unix://…, /var/run/docker.sock, or the per-user socket Docker Desktop, OrbStack, Colima and Rancher Desktop leave). The socket is read with one GET /containers/json: every container, running or not, becomes a service on a device:docker node, with its image, state, published ports and compose project. A TCP DOCKER_HOST is never probed, and nothing here can start or stop a container. With no manifest and no socket it returns an empty scan, not an error: no host addresses are baked in.

The Infra part of My Setup's Environment section draws that scan as a table: a status, a name, how old the reading is, and for each machine what an agent may do there. The modes are the gate's answer with the machine as the target (device:nuc), for the actions the tree gives Shell Execution, so they differ between machines only where a grant is scoped to one. They come from this machine's own grants, and a forbidden grant wins at any scope, as it does for apply. The gate does not apply a capability's grants to the actions it confers, so the tab also asks about Shell Execution itself and shows the stricter answer wherever that one speaks to the machine. Two times sit on a row and are never the same one. Probed is the age of the scan in front of you, and a row the scan had nothing to probe says so. Last seen is when ambit incidents last got an answer from it, read from the graph, so a machine that has gone quiet reads as days old and never as just now; a row with no answer recorded shows a dash. The scan itself records nothing.

The manifest is not specific to servers. A device is anything that can act (a Pi, a GPU host, a robot arm, a sensor, a decoder), and they seed as first-class nodes in a physical domain. Devices and services seed into the engine graph itself: a device is a resource with a runs_on edge to every service hosted on it, so ambit impact device:nuc answers what actually breaks when the machine disappears, and a plan can point at capacity the graph counts. Whether that generalization is the right one is argued in the affordance frontier; what is implemented is that the model does not assume software.

{
  "devices":  [{ "id": "nuc", "name": "NUC", "statusUrl": "http://nuc:9000/health", "tags": ["gpu", "always-on"] }],
  "services": [{ "key": "ollama", "label": "Ollama", "host": "nuc", "url": "http://nuc:11434/api/tags", "tags": ["inference"] }]
}

A device or service may carry tags, the person's own labels for it. They seed onto its node, are written again on every seed so a tag taken out of the manifest leaves the graph too, and show under its name on the Infra part of the Environment section and in the ambit incidents report.

Reachability is evidence. ambit incidents probes each device's statusUrl and each service's url, only when typed or when an agent calls ambit_incidents, and records every probe as a check run on that node, which is the same row ambit verify writes. A 2xx passes; no answer, or any other status, fails. So a service that stops answering reads broken and is left out of every plan, permission and ranking, and its probes passing again bring it back by the rule every check follows. An answer of any status also stamps when the node was last seen, and the machine a service runs on with it, since the reply came from there; a probe with no answer leaves both times as they were. What rests on a failing device or service is not taken away. A capability it provides (a service named for a local runtime provides Local Runtime, and any device provides Self-Hosted Stack) stays reached and keeps its own lifecycle, while a grant that would run it unattended asks a person until the probe passes, which is what any failing hard prerequisite already does to a grant, and the narrowing is written to the delegation records ambit delegation reads. A service on a device whose status URL stops answering is narrowed the same way. ambit verify has no command to run for these, so ambit status and ambit verify --failing name ambit incidents for them. ambit sync export leaves out two things: when each one was last seen, since that is a reading of this machine's network, and its tags, since each machine seeds them from its own manifest; the check runs travel as every check run does.

The goal is not another homelab inventory. It is to treat infrastructure as capability-bearing:

GPU node
  ├─ local inference
  ├─ embeddings
  ├─ batch evaluation
  └─ private processing

A machine matters because of the actions it makes reachable.

Capability and authority are different things

Being technically capable of an action should not imply permission to perform it. Each action has a grant in one of three modes, and an action no grant covers is refused:

autonomous   runs without asking
confirm      runs once a person says yes; for apply, a signed approval
forbidden    refused, and no narrower scope reaches it
no grant     refused until someone grants one

This lets technical capability accumulate without silently broadening authority. It is not a restriction on the capability model; it is what makes a larger capability surface governable. Proposing more capability and granting more authority stay separate acts: approving a proposal mints an artifact that ambit apply spends, and never writes a grant.

Authority is recorded per action, and from two sources. The curated model says what an action is like in general; the runtime that would execute it says what it permits here: Claude Code's permissions.defaultMode, which ambit seed reads, and Hermes's approvals.mode and approvals.cron_mode, which its adapter passes through. Where the two disagree the narrower wins, and ambit authority names which source narrowed it. A runtime's setting is stored once against the runtime and reaches every capability it contributes and every action those confer; ambit authority and the gate behind ambit can, apply and the control plane resolve it through the same reach, so the report can never be stricter than what is enforced.

How grants resolve. A forbidden grant wins outright, at any scope: a narrower scope is never a way to reach something refused. It covers what it names, though, and at the gate a forbidden grant on a capability does not by itself cover the actions that capability confers. After ambit authority grant shell-execution forbidden --scope=device:nuc, the gate still answers act:shell-execution/read_output on that device from the action's own grants; the interface specs keep this on their Open list. Among the grants left, the most specific scope that covers the target decides, ties going to the narrower mode, so "autonomous on staging" can beat a standing "confirm everywhere" on staging and nowhere else. A question that names no target is inside no scope, so a scoped grant may narrow it and never widen it.

Where it is enforced. ambit can <cap> [--target=X] [--spend=N] is the decision API, with the spend in dollars as a budget is set in them: it returns ALLOW, CONFIRM or DENY with the governing grant, the scope, and the remaining budget. Three places act on that answer:

No other runtime is interposed yet: one that never calls ambit can is unaffected by any grant here.

Whether an action may run comes from a grant a person set in advance, and nothing an agent reads can widen it. A calibrated classifier's probability is read from state an agent fetched, and whoever wrote that state can steer it, so a classifier may help decide what to try and never stands in for a grant. Ambit and Jev says where a typed judgment model fits.

The frontier ledger

capabilities holds the present state and is overwritten on every seed, so on its own the graph can only say what the system can do now. Every seed also records the whole frontier, which lets it answer what was reachable at a past date:

ambit history since
  moved:     reached 13 to 19, 3 emergent
  frontier then: 13
  frontier now:  19
  gained:    Embeddings · Local Embeddings · nomic-embed-text
  emergent:  Model Routing · Offline Capable · Subagents

One embedding model was added. Six capabilities moved. The three under emergent became reachable although nothing providing them was added: their prerequisites were satisfied by something else entirely. Offline Capable was already provided by an agent that did not change.

That is the entry a per-component changelog structurally cannot produce, because no single change explains it. Accumulated capacity to act is a graph property, and this is where it shows up.

A fourth class, vocabulary, exists to keep gained, emergent and lost honest. When Ambit starts modeling a part of your system it did not model before, such as a new action on a contract or a capability added to the curated tree that your existing tools already provide, the node is new and nothing about the machine changed. Those are described and not counted, so frontier_now stays comparable with frontier_then:

ambit history since
  moved:     reached 21
  frontier then: 21
  frontier now:  21
  vocabulary: 12   act:shell-execution/run_command · act:file-editing/write_file · …

Without it, upgrading Ambit would read as a dozen capabilities acquired on a machine where nothing happened, which is exactly what the ledger exists not to say.

The map reads the same ledger as a timeline under it, opened from its History button or by a link that names a moment. GET /api/frontier serves one tick per second in which a snapshot was taken; two snapshots inside one second are one tick showing the later, because a second is all a timestamp can name. Each tick carries what the snapshot holds, which is state, kind and lifecycle per capability. It also carries the step since the tick before in the words ambit history since <then> <now> prints for the same two observations, since the terminal, MCP and the page share one comparison. Scrubbing redraws the map from the snapshot's states over today's names, eras and edges, which no snapshot stores. Grants, providers and attention are not stored either, so while the playhead is in the past the lenses that read them and the simulations stay off, never drawn from today. The playhead travels in the link as at, which is a timestamp and not a snapshot id, and a second the ledger does not hold opens on now.


What gets recorded, and what it buys

The session history

The session history that attention reads is written by observation, not by hand. Three bridges write it once installed:

Token counts also come from the session logs Claude Code, Codex, OpenCode and Amp keep, with nothing installed: Claude Code's JSONL transcripts, projects/<project>/<session-id>.jsonl in ~/.claude and ~/.config/claude (or only CLAUDE_CONFIG_DIR when set) with the subagent transcripts in each session's own folder, Codex's JSONL rollouts in ~/.codex (or CODEX_HOME), OpenCode's SQLite database in ~/.local/share/opencode (or OPENCODE_DATA_DIR), opened read-only, and Amp's thread files in ~/.local/share/amp (or AMP_DATA_DIR). These are the same records ccusage reports from. Each session is a run whose source names its runtime (codex-log, opencode-log, amp-log, and claude-code-log for a Claude Code session its hooks have not begun already), holding its tokens per model as fresh input with cache writes, cache reads, output, and reasoning where OpenCode counts it apart, priced at the declared output price as OpenCode prices it. A Claude Code reply written on several lines is counted once, at its largest, and a subagent transcript's replay of the session's own replies is skipped, as ccusage skips them. Codex writes a cumulative total beside each turn's own count; a turn is counted once, from its own count or the difference of the totals, and a forked session's replayed history is skipped. OpenCode's tokens are summed over each model call, since a message holds only its last call's, and a fork's copied messages are left out. Tokens are kept per hour of use: a row's recorded_at is the start of the hour, one row per run, model, part and hour, grown in place as the hour fills. A session's log is read again as it grows, and only what its run does not hold yet for each hour is recorded, so the same tokens are never counted twice. Rows recorded before hours were kept have no written_at; they stay as they were, their time their session's, and cover that many of the session's earliest tokens when it is read again. A cursor per file makes a read that finds nothing new cost a stat per log, and it stays out of ambit sync, which carries the runs and their tokens. AMBIT_NO_LEDGER=1 stops the reading, and ambit usage --refresh reads every log again from the top. The price rule is the one the Claude Code read uses; a session older than a budget's period is priced and spends nothing against it, so a first read of last year's sessions cannot exhaust this month's ceiling.

The Claude Code and OpenCode bridges time a call from the hook before it to the hook after it, pairing the two by the runtime's id for the call, and the use starts where the call did. A call whose start was not seen has no length. Neither does a call a person was asked to approve while it ran, since the runtime asks after that first hook and the span holds the person's wait; when the ask does not name its call, every call open in that session at the time goes untimed. Cursor states each shell command's and MCP call's length itself, with the wait for approval left out, so its bridge pairs nothing and dates the use that long before the hook ran. ambit work and ambit usage sum the lengths that exist and say how many uses that sum covers. The control plane still writes a fixed length for the execution it gates.

Anything else can post to the visualizer API's loopback POST /api/telemetry, which speaks the ledger's own verbs (run, end, event, use, intervention, resource, outcome, failure), so a runtime adapter records actual work without knowing the schema. A use may name the tool that ran in place of a capability, and the engine records it against whatever that tool exercises, as the gate would find it. From a checkout, scripts/adapters/telemetry.ts is the ingestion client: it reads one JSON object per line from stdin and posts each there.

echo '{"run":{"goal":"recover production service","runType":"incident"}}' \
    | node --experimental-strip-types scripts/adapters/telemetry.ts

The endpoint is loopback-only and origin-allowlisted like every other route, and it needs the API token, because work recorded there counts toward promotion. The server writes the token to ~/.config/opencode/ambit-api.token when it starts, and the adapter and the OpenCode plugin read it from there or from AMBIT_API_TOKEN. A telemetry payload is structured data, never a command.

Failures land in the ledger too, classified from what a runtime states outright: a shell's own message for a missing binary, an MCP error kind, a permission refusal. Nothing reads what the failure was about. So deficits and opportunities stop saying "nothing observed" within a day of real work, without anyone remembering to record anything, and ambit signals is the raw view, including the failures no capability could be attributed to. Those are a gap in the model, not in the environment.

ambit work reads the ledger back: each run with its elapsed time, events, capabilities exercised, interventions, resources, and outcome. ambit usage <days> aggregates where effort went per capability, which is the raw material the opportunity engine ranks.

ambit usage --windows [days] reads the hourly token rows as the five-hour windows Claude Code's and Codex's plans reset in, counted as ccusage's blocks report counts them (identify_session_blocks in its blocks.rs): a window starts at the first use after the last one ended, floored to the hour, and lasts five hours, so a use five or more hours after the start opens the next. Each runtime's windows are counted apart, since each plan resets on its own clock. Every window gives its start and end, tokens per model and part, and its cost where prices are declared (otherwise unpriced); the current one adds the time left, and the last 7 days are totalled per runtime. The last 24 hours unless days are given, and --json gives times in UTC. Ambit knows no plan's limit, so no window shows a share of one or a count of tokens remaining. Time & cost draws the current window beside the month's tokens, and nothing when no window is under way.

The economic loop

The graph half answers what can this system do. The loop that pays for it answers where is the scarce resource going, and which durable fix is worth the next dollar or hour:

flowchart TD
    WORK["1. Real Work Happens\n(Claude Code / OpenCode Sessions)"] --> TELEM["2. Work Ledger Observes\n(Plugin Hooks / Telemetry Bridge)"]
    TELEM --> ATTN["3. Attention Accounting\n(Prices Human Interruptions @ $/hr)"]
    ATTN --> OPP["4. Opportunities Engine\n(Ranks High-Payback Tool Investments)"]
    OPP --> PROP["5. Proposal Drafted\n(Steps, Inverses, Costs, Forecast)"]
    PROP --> APP["6. A Person Approves\n(Mints a Signed, Expiring Artifact)"]
    APP --> APPLY["7. Apply Spends the Artifact\n(canExecute per Step, Then the Check)"]
    APPLY --> ROI["8. Realized ROI Written Back\n(Forecast vs Recorded Time)"]
    ROI -.->|"Evidence for the Next Forecast"| ATTN

The graph half is useful the moment you seed. status, briefing, next, plan, verify and authority need no telemetry at all.

Previewing a change

ambit goal <cap> --simulate computes the frontier as it would be, without touching anything. What makes it worth reading is the unblocked line:

ambit goal vector-store --simulate
  frontier before: 21
  frontier after:  23
  acquired:  Vector Store
  unblocked: Retrieval          # already provided, waiting on the prerequisite

ambit propose turns that into a reviewable draft (ordered steps, the alternative chosen, and what it costs beyond time):

ambit propose retrieval
  Retrieval · 25m
    Embeddings     nomic-embed via local runtime      none / local
    Vector Store   pgvector on existing Postgres      none / local
  simulated:
    frontier before: 21
    frontier after:  24
  applicable: false

Choosing the hosted alternatives (ambit propose retrieval 1) takes it to 13 minutes, at a per-token bill and a data boundary.

Where an acquisition genuinely is a config change, the step carries a declarative patch and Ambit derives its undo, removing what it adds or restoring what it overwrites. Anything needing an installer gets no inverse, and a proposal is applicable only when every step has one.

ambit approve prop-msrrv9c2 --by=kanav
  proposal: prop-msrrv9c2 · goal: Web Research
  approved by: Kanav · applicable: true
  apply: ambit apply prop-msrrv9c2

Approval mints a signed artifact: proposal hash, actor, budget, scope, expiry, timestamp, HMAC-signed with a machine-local key (AMBIT_APPROVAL_KEY, default ~/.config/opencode/ambit-approval.key). It is also minted by the browser broker, POST /api/proposals/:id/approve (loopback, origin-allowlisted), which approves and signs but never applies. The visualizer's AG-UI stream surfaces the approval as a toast telling you exactly which terminal commands to run.

ambit apply prop-msrsqzij
  applied: true · keys: mcp.fetch
  backup: opencode.json.ambit-prop-msrsqzij.bak

ambit rollback prop-msrsqzij
  removed: mcp.fetch          # git survives — the inverse reverses only this

apply checks the artifact and each step's canExecute, writes the patch, and runs the goal's check when it declares one; a check that fails there reverses the change.

Which runtime it writes. --to names the runtime by the word ambit connect takes (claude-code, cursor, opencode, vscode and the rest). Without it, apply writes OpenCode when OPENCODE_CONFIG names its file, and otherwise the one runtime whose config is on the machine:

ambit apply prop-msrsqzij --to=claude-code
  applied: true · runtime: Claude Code · keys: claude-code/mcpServers.fetch
  backup: ~/.claude.json.ambit-prop-msrsqzij.bak

Several runtimes and none named is a question, never a guess. It writes nothing, prints --to for each, and says how to make the change by hand in each: the runtime's own command where it ships one (claude mcp add --scope user …, codex mcp add …, code --add-mcp …), otherwise its file and the entry for it. --print asks for that answer on purpose. Codex keeps TOML, which Ambit does not write, so it gets the command alone; a patch only OpenCode reads, such as a model provider, is refused anywhere else. The rollback undoes the file the apply wrote, from an inverse worked out against that file and stored before the write.

A patch is written only when it is the one the shipped tree gives that alternative. A plan reads its alternatives from the tree with any project overlay merged in, and an overlay arrives with a cloned repository: its patch would put its own command into a runtime's config, to start with every session. Approval and apply stay off the MCP surface: an agent may draft, preview, and ask, but never approve or apply. Proposing more capability and granting more authority are different acts, and the artifact is what keeps them apart.

Delegation records

A grant that stopped running unattended because what it rests on started failing leaves a record: which capability failed, which grant rested on it, and what the grant became. ambit delegation writes those records, lets a person contest one, and reads the same kind of record from other systems as evidence. The format is STD-07 Revisable Delegation Records: an append-only, hash-chained stream that another system can read as evidence and never as an instruction, without sharing Ambit's database.

The standard describes the loop an institution runs when it delegates consequential work to machines: believe, know what can be done, decide what authority is justified, act, detect mismatch, revise. Five systems each hold a step of it. Ambit holds two, capability and authorization. The siblings are Whether (act), Refract (discrepancy), NextConsensus (belief), and Ethotechnics (the record shape).

The grant holds only while what it rests on does. A capability whose hard prerequisite has started failing no longer runs unattended: ambit can <capability> returns CONFIRM instead of ALLOW and names what took it down. The declared grant is not rewritten, since what a person wrote down stays written down; the narrowing is a property of the decision, so it lifts by itself when the check passes again. A declared sandbox is exempt, because consequences are contained there.

The export. ambit delegation --export writes newline-delimited records. Four kinds are written automatically for every grant currently narrowed: the capability that broke, the authorization that rested on it with depends_on and invalidated_by populated, the discrepancy, and the revision superseding the authorization. The stream is append-only and hash-chained; ambit delegation verify recomputes it. Conformance level 2, declared in server.json and measurable with the record conformance checker.

A record can be argued with. Every record names who may contest it: an exercise of authority names the people it binds, and an observation names anyone who can re-run the check. ambit delegation object <record> --by --basis writes the challenge as an objection; ambit delegation answer <objection> --by --because [--refuse] writes the answer it is owed; ambit delegation objections lists the unanswered. Neither widens authority: an objection that reopened an unattended grant would make the gate negotiable, so widening still costs what it costs, which is fixing the capability or re-declaring the grant. A stream containing an objection and its answer measures at level 3.

Reading another system's records. ambit delegation ingest <file> takes an STD-07 stream and records its discrepancy records about capabilities this graph knows, as evidence attributed to the sender. Three limits, each deliberate. It never moves a lifecycle, so no remote system can narrow a grant here by sending a file. Only discrepancy records are read, because a foreign authorization is that system's account of its own grants, and importing it would import authority, not evidence. A subject this graph has never heard of is reported as unmatched, not dropped, since a sender and receiver disagreeing about what exists is the most useful thing a first integration can tell you.

Sources are read without being asked. ambit delegation source add <id> --system --instance --from --by declares where a system's records arrive, and a full ambit verify reads every enabled source from then on. A local path, deliberately: an outbound read on the verification path would put a remote host between this graph and its own evidence. A source that cannot be read records why and verification continues. ambit delegation sources shows when each was last read and what happened. server.json names no peer: its upstream points at these declarations, and there are none until you add one.

The source that works is another Ambit. A peer runs the same tech tree, so it names capabilities identically, which is the whole reason its discrepancies are legible here; nothing else in the loop shares the vocabulary. A source must say which environment it is (--instance), because two graphs on the same tree produce identical record ids, and declaring this environment as a source is refused. When the laptop reports combo:shell-execution broken, the server records that as evidence attributed to std07:ambit/laptop and its own grant on act:shell-execution/read_output still returns ALLOW; on the laptop, where the check actually failed, the same grant returns CONFIRM. A peer can tell this graph something. It cannot revoke anything in it.

What is not there yet. action and outcome records: the environment adapter is simulated by default, and the opt-in Docker one runs a step in a container on this machine that nothing else depends on, so an action record from either would attest to no change in a system anyone relies on. Only Claude Code can be made to consult the gate, through the ambit gate hook; any other runtime that never calls ambit can is unaffected by any of this. And no sibling yet consumes what Ambit emits; the reading edge runs one way.


The surfaces

The full CLI surface

Run ambit with no arguments and it shows where the environment stands. ambit help is a first session, ambit help <group> one group's index, ambit help <command> one command with its options, and ambit help --all the surface. The commands group under five nouns, and the grouping is presentation only: every verb also works flat, so ambit impact x and ambit graph impact x are the same command:

           seed · briefing [--json|--peek] · status · next [n] · help [term]
graph      impact <id> · catalog <cap> · where · skills · objects [target]
           share [--redact] [--out=path] · sync export|import <path>
           graph [surface|combos|affordances|unmapped|capacity]
plan       goal <cap-or-sentence> [--paths|--simulate|--prefs|--judge[=url]] · next [n]
           goal --spec <dir|tasks.md> [--judge[=url]]
           reversible
           opportunities [id] [--rank=…] [--budget=N]
           propose <cap> [option] [--for="…"] [--by=<who>] · roi [proposal-id]
           portfolio [--budget=N]
           judge goal|next|tools|failures|attention|media|evaluate|history|review|plan
check      verify [cap] [--history] [--target=<object>] · verify --failing
           authority [cap] [scope <target>]
           authority promote [<cap> <action> --after=N --window=30d --scope=X --by=<person>]
           authority grant <cap> <mode> [--ttl=30m] [--scope=X] [--by=<person>]
           authority sandbox [<target> --by=<person>] · budget [set|clear]
           can <cap> [--target=X] [--spend=N] · gate (the Claude Code hook) · credentials
           incidents [resolve <svc> <outcome>]
           doctor · connect [runtime] [--ledger] [--statusline] [--dry-run]
           init-rules [target] [--dry-run]
           receipt [hours] · ci [--strict] [--markdown]
govern     people [add <id> ["Name"]]
           proposals [id] [--pending] · approve <id> [<id>…] [--by=<person>]
           reject <id> [--by=<person>] ["why"]
           apply <id> [--to=<runtime>] [--print] · rollback <id> · dispatch <id> [--to=<url>]
           history [since <when> [<until>]]
           audit [run-…|prop-…|human:name|days]
           delegation [verify] [--record] [--export] · delegation ingest <file>
           delegation object|answer|objections · delegation source add|sources|pull
report     work [limit] · usage [days] [--windows] · economics [price <model>] · attention [days]
           notify <topic> [--approvals]
           record <cap> [class] [note] · record skill:<name> --provides= --verify=
           signals [days] · preferences [--observed] · federation export|import
           statusline [--json] (the Claude Code status line)

Two more sit outside the groups because they start a process instead of answering a question: ambit web opens the visualizer (Vite in a checkout, and the built page with the loopback API server in an installed copy) and ambit mcp runs the MCP server. ambit --version prints the installed version and starts nothing.

Command The question it answers
first session — the commands listed above the groups
ambit briefing What an agent should know before its first tool call — reached and verified, configured but failing, waiting on a person, blocked recently, worth reaching next and what each step would reach, and what changed since the last briefing. Prose, capped near 1,200 tokens, also served as the MCP resource ambit://briefing
ambit status How are we doing — reached, verified, failing, recovering, SPOFs, recurring deficits, pending approvals, all in one report that ends on the one command to type next. --json carries that as next, a command and the reason for it
ambit next [n] What to reach next and why — ranked by what has actually blocked work once the ledger has observations, and by leverage per hour of setup before then. The answer says which basis it used
ambit council The first of those, read five ways: what it opens, what it would rest on, what it has cost, what it may do once reached, whether its foundation works. One sentence and one command per seat, a stance each, and whether they are split
graph — the structure, and what it would cost to lose a piece
ambit impact <id> What becomes unavailable if this disappears — and what survives on another provider?
ambit catalog <cap> The ways to acquire a capability — build, buy, subscribe, delegate, hire — compared by setup, one-time and recurring cost, privacy, verification and rollback
ambit objects [target] What may be done to a particular thing, and what has been proved about doing it there. Evidence about one repository is not a claim about another
ambit sync export|import <path> The graph and the ledger as one file, so a container rebuilt from nothing gets its history back. No authority grants, no skill check commands, no credentials — a command in a data file is a command that runs on import
ambit graph The whole graph as JSON through a pipe, with --json, or as ambit graph export anywhere (bare graph on a terminal is the group's index); graph surface is the runtime-owned vocabulary a runtime would publish, graph combos the ones whose required prerequisites are all in place, graph affordances the structural domains, graph unmapped what the agents used that no node on the map accounts for (presence, never frequency) and the overlay that would add it, graph capacity the machines on your tailnet and this machine's memory, naming the online ones no manifest declares
plan — what to acquire next, and whether it paid
ambit goal <sentence> Route a free-form goal — "deploy without me" — to the capabilities whose words cover it, each with its plan delta
ambit goal --spec <dir|tasks.md> What a spec's tasks need before an agent starts on them: each task routed as a sentence would be, each capability reached, a next step, blocked or failing, the steps in order with their setup time, and the tasks nothing routed. Spec Kit and OpenSpec, read as data
ambit goal <cap> --paths The alternative ways to reach a capability, compared by setup time, risk and lock-in
ambit goal --prefs [who] Who prefers what, and where a plan's default choice would fight them
ambit reversible Which unreached capabilities could be acquired without a person, and which need hands. The same list, read backwards, is what an agent can never do for itself
ambit opportunities Ranked structural changes worth making — observed middleware burden priced by attention value, acquisition cost, expected effect, payback, confidence. --by=attention|cash|roi|reliability|frontier; --budget=N allocates the best combination within $N
ambit roi [proposal] One proposal's before/after verdict, or — with no argument — the cumulative headline: recorded hours and dollars per year and forecast accuracy
ambit portfolio [--budget=N] Across imported environments: the same human burden recurring in several places, person-specific SPOFs, and where capex would produce the most
ambit judge goal|next|tools|failures|attention What a judgment model makes of what the graph's own words do not settle: which capability a sentence means once the vocabulary has had its turn, which next step serves a goal, what a list of tools, a reported failure or a recorded intervention is about. Each answer is a suggestion with a probability and writes nothing; --record keeps it as a receipt, a person reviews a receipt once (judge review <id> accepted), and only an accepted goal or spec receipt becomes plans, read from the graph as it stands. judge evaluate scores routing against cases with expected answers. A model on this machine answers by default (AMBIT_JUDGE_URL, or loopback port 8009), and --provider=cloudflare sends the request to Workers AI under your own account
check — what is verified, what is permitted, what is currently broken
ambit authority <cap> Which concrete actions does this confer, and which of them may run unattended?
ambit authority scope <target> What a scope actually covers and what it does not — a grant scoped elsewhere is named as excluded
ambit authority promote <cap> <action> --after=N --by=<person> The threshold that widens a grant once its evidence supports it. A person sets it once; a single failing check afterwards puts the grant back, with nobody asked
ambit authority grant <cap> <mode> --ttl=30m Autonomy for a window and no longer. Once expired the grant decides nothing and whatever stood before it decides again; the row is never rewritten, so it stays as the record of what was granted
ambit authority sandbox <target> --by=<person> Somewhere acting does not matter. Confirmation is relaxed inside it; a refusal never is, because rehearsing a forbidden action would be a way round it
ambit budget set <cap> --amount=20 --by=<person> A ceiling on what can be spent in a period. A spend past it is refused until the period turns over. It bounds a grant and does not widen one: within the ceiling the grant's own mode still decides. One meter feeds it: a session's tokens on a model with a price declared by ambit economics price, read from the Claude Code, Codex, OpenCode and Amp logs as they grow, are recorded as a spend against the unscoped budget on Hosted Inference, for each hour inside the budget's period. The limits: only a declared price, only a budget that exists, and only as far as the last ambit command read, so a spent ceiling stops no session under way and refuses only a caller that states its spend. apply and the control plane state none
ambit incidents Probe the infrastructure manifest, record each answer as a check run and when each device and service was last seen; open an incident run for every offline service with the authority decision for its recovery. incident resolve <svc> <outcome> closes it with MTTR
ambit weigh [server] What each local tool server's tool list costs in context, every session. It starts the server as its runtime would, asks for its tools over MCP, records the list and stops it, so it runs only when typed. The report is per runtime, heaviest first, with each server's heaviest tools; once the ledger has recorded calls, it also names the servers carried and never called in thirty days. A remote server is not contacted. --recorded reads the last weighing and starts nothing
ambit doctor A graded summary of the setup: what is reached, verified and failing, the single points of failure, which runtimes it read, and what to run next. ambit check with no argument is the same report
ambit connect [runtime] Register Ambit's MCP server in each runtime it reads except Copilot CLI, Amp and Goose, or the one named, in the shape that runtime's file uses, keeping a .bak of each file it changes. --dry-run says what it would write. cursor --ledger also adds the hook that records each Cursor conversation into the session history, beside any hooks already in ~/.cursor/hooks.json. claude-code --statusline sets ambit statusline as the status line in ~/.claude/settings.json where none is set, and never replaces one
ambit init-rules [target] Write the one line an agent should follow before a tool it has not used (ask ambit_can) into CLAUDE.md, AGENTS.md or .cursorrules, for a client that does not pass a server's instructions to its model. rules is the same command
ambit receipt [hours] What the ledger recorded in the last few hours: capabilities used, calls stopped before running, failures reported. It counts what was recorded and prices none of it
ambit ci [--strict] A check for a pipeline: it fails on any capability whose declared check is failing, and with --strict also on anything reached and unverified or resting on a single provider, which are otherwise warnings. --markdown prints the result as Markdown, and under GitHub Actions it is also written to the step summary
govern — the reviewable path from proposal to applied change
ambit people add <id> ["Name"] Declare a person budgets and approvals can name. It grants nothing; it gives the trail a name to carry, and the engine refuses a decision from someone it does not know
ambit proposals --pending The drafts waiting on a decision, each with cost, bill and what it unlocks, so approving is one sitting and not one interruption per proposal
ambit apply <id> [--to=<runtime>] Write an approved change into the config of the runtime you use, Claude Code, Cursor or OpenCode among them, backed up first and checked after. Where it cannot write, it gives each runtime's own command instead (which runtime it writes)
ambit reject <id> --by=<person> ["why"] A refusal, recorded with its reason, so the next draft and ambit preferences --observed can learn the shape of a no. An approval the draft held can no longer be applied
ambit history since <when> [<until>] What became reachable since a past date, and what emerged with nothing added? Up to now, or up to a later observation, with the step in the sentence the map's timeline prints
ambit audit <run-…|prop-…|human:name|days> The trail: who approved what, what ran, against what target, under which grant, and whether it held
ambit dispatch <id> [--to=<url>] Push a proposal to Slack, Discord, Telegram, ntfy or a JSON endpoint: the decision for a draft, the signed artifact once approved. One-way; the reply is ambit approve on a machine that holds the key
report — what the system cost to operate
ambit attention [days] How much of the work still runs through the human, and which interventions are likely reducible
ambit economics price <model> --input= --cache-read= --output= What a model's tokens cost, in dollars per million, so a session's tokens on it become a spend against Hosted Inference's budget as they are recorded. Sessions recorded before the price are not priced again, and a model with none is reported undeclared, never $0
ambit usage --windows [days] How much each five-hour window used, per runtime, model and part, and how long the current one has left, with the last 7 days beside them. No plan's limit is known, so none is shown
ambit notify <topic> Push the attention digest to ntfy — nothing is sent without a topic
ambit record skill:<name> --provides=<cap> --verify="<cmd>" Put a skill the agent wrote in the graph, as a provider of a capability, with the read-only check that proves it. The check is required and runs immediately
ambit signals [days] Failures observed without anyone recording them, by class and by tool — including the ones no capability could be attributed to
ambit preferences [--observed] What someone declared they prefer, or what they have actually approved and refused
ambit federation export|import The signed summary a portfolio layer reads — aggregates only, no credentials, no raw sessions
ambit statusline What is worth a glance after every message in Claude Code: the capabilities failing their check, the proposals waiting on a decision, and the verified count, in one line of at most 60 characters with each empty part left out. It opens the graph read-only and runs no migration, seed or spool read, and from an installed copy it answers in about a twentieth of a second. --json is the same reading, for a script that draws its own line

Every command prints for a person by default and takes --json for scripts.

What a plan looks like when a capability is one dependency away:

ambit goal local-embeddings

  Local Embeddings
    steps: 2 · estimated setup: 25m
    order: Embeddings → Local Embeddings

More useful is where composition fails. Capabilities you have already half-built carry the reason:

Retrieval          configured, but Vector Store is not in place yet
Offline Capable    configured, but Local Embeddings is not in place yet
Self-Hosted Stack  configured, but Observability is not in place yet

Nothing declared those. They fall out of the dependency structure, and they are invisible in every file you own.

From a script, or an agent's shell. Output is plain when nothing is reading it as a terminal: color is drawn only when stdout is one and NO_COLOR is unset, so a pipe, a file and a CI log read what was written. --json prints any answer as data, and ambit status --json carries its closing suggestion as next. The exit code says whether the command worked: 0 for an answer, 1 for a command that reported an error (a usage error, an id the graph does not hold), and 2 for a word that is not a command. ambit check --ci keeps its own codes. --exit-code on can maps ALLOW, CONFIRM and DENY to 0, 1 and 2, and with --record, the flag for an agent asking from a shell, a DENY files the deficit as it does over MCP; on verify it exits 1 unless every check that ran passed, and also for a capability with no check to run, since nothing was proved. A flag with a value is written --target=svc:ollama; the two-word form is not read.

The full MCP surface

The tools, by group:

Group Tools Purpose
Graph ambit_stats, ambit_context, ambit_cap, ambit_combos, ambit_diff, ambit_health, ambit_decay, ambit_near, ambit_bottlenecks, ambit_spof, ambit_impact, ambit_credentials Query structure, single points of failure, keystones (ambit_bottlenecks), combo prerequisites, and blast radius.
Lifecycle ambit_verify, ambit_evidence, ambit_authority, ambit_actions, ambit_plan, ambit_goal, ambit_paths, ambit_preferences, ambit_scope, ambit_affordances, ambit_since, ambit_ledger Is this real, may I act, what is missing: inspect health, run verification contracts, resolve authority scope, compute prerequisite paths.
Operate ambit_work, ambit_usage (with unmapped, what was used and is on no node, and windows, tokens per five-hour window), ambit_run_begin, ambit_run_end, ambit_work_event, ambit_digest, ambit_economics, ambit_goal_value, ambit_opportunities, ambit_opportunity, ambit_catalog, ambit_roi, ambit_roi_summary, ambit_audit, ambit_incidents, ambit_incident_resolve, ambit_portfolio, ambit_can The economic loop read and written by an agent: record telemetry, price attention, rank opportunities, and check permission before acting.
Propose ambit_blocked, ambit_deficits, ambit_simulate, ambit_propose, ambit_proposals, ambit_proposal Record deficits, simulate future frontier states, and draft reviewable patches.
Session ambit_briefing, ambit_next, ambit_council, ambit_record_failure, ambit_signals, ambit_register_skill, ambit_skills, ambit_promotions Know the environment before touching it, see what is worth reaching next, report a failure the runtime already noticed, and register a skill you wrote with the check that proves it.
Expand ambit_objects, ambit_budgets, ambit_reversible, ambit_preferences_observed, ambit_pending What may be done to a particular target and what is proved there, what ceilings bound a spend, what would have to be written for an acquisition to need no person, what this person actually approves, and what is waiting on one right now. All read-only.

Widening authority is a person's act throughout. An agent can ask; it can never approve or apply, and an agent that could grant itself more would make the distinction meaningless.

One resource sits beside the tools: ambit://briefing, which a client reads on connect. A tool has to be thought of; a resource arrives unasked, which is the only way it reaches the agent that does not know Ambit is there. That agent is the one that most needs to be told what is already broken.

How a call is answered

An agent that connects is told what Ambit is: the server's instructions carry the one habit, which is to ask ambit_can before a tool you have not used, so a client that passes them to the model shows it unasked. The protocol version is the one the client asked for when the server speaks it (2024-11-05 and 2025-06-18), and ping is answered.

Every tool says, before it is called, whether it changes anything. Most are annotated read-only, and a test holds that claim against the database: each is called against a copy of a seeded graph and no table may differ afterwards. ambit_can, ambit_briefing and ambit_context are listed as writes, because can files a refusal as a deficit and the other two move the mark that says what changed since you were last told. ambit_verify and ambit_register_skill run a command that was declared in the graph, and claim no safety.

Every call is checked against the schema the tool advertised before it reaches the engine. One that cannot work comes back as a failed call the model can read, isError: true with the error and what the tool takes. The check is lenient where the meaning is not in doubt (null for an omitted argument, "14" for 14, capability_id for capId) and refuses the rest, including an argument the tool does not take: a misspelt argument is an error, never silently dropped. On both surfaces a call has failed when its answer holds a top-level string error, which is also what makes the CLI exit 1. An error inside a report, such as one failing check among many, is part of a real answer and does not count. An unknown tool is a protocol error (-32602) that names the one probably meant.

A capability is named by its id, its id without the kind (shell-execution) or its name (Shell Execution), and one resolver, resolveCapability, decides what that means for every tool that takes one. It normalizes and never guesses. A word that fits no node, or fits two, comes back as did_you_mean with the candidates, because an id picked on an agent's behalf can be a different capability under a different grant. ambit_can treats a close misspelling as a slip: it answers with the candidates and files no deficit, since a "no" to shell-exection reads as "you may not run a shell". It also takes a tool by the name the runtime gives it (Bash, mcp__github__create_issue, Bash(git push origin main)) and asks about the call as the gate does: each capability the call exercises is listed under asked_as, with the narrowest answer given, the Claude Code permission rule that names the call beside it as runtime_rule, and the failures recorded against those capabilities in the last week as failed_recently. A sentence such as "run the test suite" comes back with the capabilities its words cover as candidates. Several calls go in one question, one to a line, and each is answered as it would be alone with nothing filed. ambit_briefing takes a task and answers only for what that sentence touches: whether each capability is reached, what its last check said, whether acting on it is allowed, and which providers to use.

Answers are kept small. The text half of a result is compact JSON, since a client may send both halves to a model. ambit_authority returns who may act alone, who must ask and what is forbidden, which comes to about 0.7KB. It returns the row for every grant only for detail: true, and that adds about 10KB on a seeded machine.

ambit mcp --profile=agent, or AMBIT_MCP_PROFILE=agent, lists only the tools an agent that asks before it acts uses (ambit_briefing, ambit_can, ambit_next, ambit_impact, ambit_plan, ambit_goal, ambit_verify, ambit_record_failure, ambit_propose, ambit_register_skill), and a test holds that listing under 5,000 bytes where the full one is held under 20,000. It changes the listing and nothing else: every tool still answers by name, and what may be done is decided by the graph's grants and never by which tools an agent was shown. Most clients let a model call only the tools they listed, so the instructions under this profile name no unlisted tool; they say the rest is the ambit command in a shell, which ambit help --all lists, and that the server started without the flag lists it all as tools. A name it does not know stops the server from starting, because falling back to the full listing would answer a typo with the thing the flag was typed to avoid.

The map, and what it is allowed to do

ambit web opens the map on localhost, and ./bootstrap.sh web seeds a graph and opens it from a checkout. It reads the same graph the CLI reads, over /api/events, and writes to your configuration in one place only: the My Setup switch, which edits an entry the config already holds and cannot create one. A proposal approved on the page mints an artifact, and only ambit apply spends it.

Views over one graph. The graph holds every entry and capability as a node, and each view draws part of it, each named by its own word in the address bar and reached with [ and ]. The map draws the curated tree with your position on it. My Setup lists the entries your configs declare, one row each, with what the engine has proved about each and the nodes on the map it provides; its sections are part of the address (?view=setup&tab=briefing), so a link can open on any of them. The Briefing section is the prose an agent is given at connect, so what the agent believes about the machine is inspectable. The Environment section draws the repository scan and the infrastructure scan together. The entries close with what the agents used in the last 30 days that no node on the map accounts for, with an overlay to paste into .ambit/techtree.json that would put it there. Time & cost is the ledger and the governance half: what may act without asking, which grants have earned enough to stop asking once a person sets the bar, what to reach next and why, and how the frontier moved this week. It opens on the council, where five seats read the first step to reach from the figures below it, and the seats that are for it and against it are named. The node panel draws the second tree under the authority line: five rungs a grant climbs (no grant, asks, threshold, unattended, ceiling), the one it is on lit, and the one command that moves it up, which names a person; the threshold rung has no command, since evidence is what moves it, and a refusal is on no rung. The timeline under the map marks an observation that reached something emergent with a diamond over its tick, and the tick's tooltip names what emerged. A rebuild that reached one node quotes the tree's own line for it in the toast. It lays one run out in time, and each time you were asked in it is an exchange: the recorded request, and your answer with how long it took, or an empty reply where nothing recorded one. The request is the capability and action the ledger holds, never words written in the agent's voice. Audit is the trail, one line per event and newest first: proposals drafted, approved, applied and turned down, check runs, work runs, and the delegation records that say when a grant narrowed, each with what came of it where that was recorded, and a query bar that takes actor:, action: and target:. Proposals is the decision queue itself, one card per change an agent has drafted, with the plan, what it would unlock, the forecast and the precedent: several drafts are a queue decided together, and approving signs while applying stays a command you run. A change of view is a navigation, so Back and Forward step between them, while a lens, a focus and a scrub of the timeline leave history alone.

Who acted. A mark before each line says who: a circle for a person, a rounded square for an agent, a hexagon for a machine and a diamond for Ambit, drawn only where the actor's id says which. A signature carries a seal.

Search. / finds anything by name and opens it where it lives, and lists actions beside what it finds: simulate an outage or an unlock, copy the command that checks a node, switch lens, go to any view. It copies a check and never runs one, and a proposal is still decided by the buttons in its view.

What the map found. Over the map, one line says what the map found before you read a node, and the node it names is marked with corner brackets. On your own machine a capability that is configured and failing its check is that line on its own, with a button that shows it, because there it is news to act on. With nothing failing, the line is the next step that reaches the most, with a button that previews it, and a second line gives the range: how many capabilities are verified, how that moved this week, and the one piece of the setup whose loss would stop the most, with a button that simulates it. The hosted demo reverses the first two: the next step leads, and the failing check is the smaller line under it, since on a sample it is the guardrail and not the point.

Marks. A reached node is filled, a next step is a ring with its setup time beside it, and a blocked node is faded; a strip under the map keys those three, and Failing when something is, and pressing one highlights its nodes. A keystone, something three or more capabilities depend on, carries a small amber wedge at its upper left. A next step that work has been recorded blocked on fills from the inside with a wedge from twelve o'clock that is full at three asks, where the engine calls the deficit structural; the key names it Asked for, and the panel says the count. A failing node is striped, as is a forbidden grant under the Authority lens: stripes mean something refuses, and nothing else on the page is striped. Edges that cross more than two eras are drawn faint until a node they touch is in focus. A small person mark on a node means it needs someone: a person approves or supplies it; a device mark means it runs on one of your machines. The detail panel says who, under Joint capability. The Key button beside zoom opens what each mark means, and pressing a key there highlights its nodes; switching to the Attention or Authority lens opens it, since a lens paints with its own scale. Image beside it saves what the map shows as a card sized for posting. It also saves the whole map, with every era, node and edge whatever the zoom, scroll or focus, as an SVG with its fonts inside or a PNG at twice its size, drawn at rest in the standard lens with any running simulation: the other two lenses paint who stepped in and what may act without asking, which the ambit share snapshot leaves out too. The Docs button defines every term on the canvas. On the hosted demo the header also carries a Sample tag, which plays the tour again, and Map yours, which asks which agent you use, takes its config pasted or the servers it runs ticked, and gives the install command; neither appears on a machine of your own. There, the first visit opens on the map with the readout instead: what the seed read, how much of the tree it reaches, the next steps as ambit ranks them, and the command that plans the first.

Selecting a node. Its edges are drawn apart: what it needs in violet, what it enables in blue, one hop each way. The panel states the answer before the simulation that draws it: what would stop and what would only lose a provider if the node went down, or what stands between it and being reached and how long that would take.

Counts. The header counts the map's nodes in three figures: the reached ones with a passing check (verified), any whose check is failing, and the next steps. Its tooltip gives the rest, what is reached and unverified and what is blocked. Each figure highlights its nodes, the way the strip's keys do. Each era's header counts what is reached and working, and it is a control: click it and the era opens in the panel as a ladder, with a bar for how far up it you are and one rung per node, each either reached, a next step with its setup time, or blocked with what it waits for. A reached node whose check failed is a failing rung of its own, and is left out of the reached count.

A map bigger than the window. It gets a minimap at its bottom right: the whole tree as a thumbnail, a dot for each node with the failing ones red, and the part on screen outlined. Drag the outline, or focus it and use the arrow keys. It is not drawn when the whole map fits, and the line over the map says which way a failing node lies (off-screen left) when it is out of sight.

Focus. On a map too crowded to read, select a node and press Focus in its panel: only what it needs and what it enables within a few hops stays on the map. Choose which way (needs, both, enables) and how far (one to three hops), and a pill says how many nodes are hidden and brings them back. The columns keep their places, the header still counts the whole map, and a simulation still counts its whole cascade and says how much of it the focus hides. Esc ends it. It is off unless asked for, and a link carries it as collapse=1, with depth and dir when they are not two hops both ways.

Lenses. The switch sits over the map, top right, and 1, 2 or 3 changes it from the keyboard.

Lens What it renders Use it for
Standard Era columns with reached, next-step and blocked nodes. Reading overall progression and what is nearby.
Attention Nodes shaded by how often a person had to step in, offered once the ledger has recorded any. Finding which tools keep interrupting you.
Authority Each reached node by what it may do: act without asking, ask first, forbidden, or no grant yet, which the gate refuses until someone grants one. Seeing where being able to do something is not the same as being allowed to.

Simulating. Select a node to open the inspector, then simulate against it. Neither mode writes anything.

The map through time. Once the ledger holds two observations, the History button beside zoom opens a timeline under the map, one tick for each second a snapshot was taken. It stays closed until asked for, or until a link names a moment. Drag the playhead, or step it with the arrow keys, and the map redraws as that snapshot left it: states and checks from then, names, eras and edges from now, because a snapshot stores none of those. One sentence says what moved at each tick, such as "Sep 26: reached 43 to 45, 1 emergent, 1 went failing", in the words ambit history since <then> <now> prints for the same two observations. Play, at the timeline's left, steps through the observations on its own, slowly enough to read each sentence, from the playhead or from the first observation when the playhead is on now, and stops at now; with the playhead focused, Space plays and pauses. Dragging or stepping the playhead, closing the timeline, starting a simulation or selecting a node pauses it. The header's counts and the detail panel follow the playhead and say "as of". A snapshot keeps no grants, providers or attention either, so while the playhead is in the past the Attention and Authority lenses and the simulations wait for now. The playhead is a timestamp in the link, so a link to last week's map opens on it wherever the same ledger is. With fewer than two observations there is no History button, since there is nothing to scrub.

Approving proposals. When an agent proposes an environment change over MCP, the Proposals panel reads it as a plan before you sign: how many steps, which of them nothing can undo, whether ambit apply can run it at all, the hours a month it is forecast to take before and after, what it costs, what it unlocks, and how you have decided on things like it before. Each proposal is drawn as a request beside the mark of whoever drafted it, which is the agent's runtime over MCP or whoever ambit propose --by= names. Your decision is drawn as the answer under it: a signed approval is a receipt with a seal and your mark, and a no is recorded with the reason, which is what the next draft learns from. When several drafts are waiting, tick the ones to decide and approve or turn them down together: each is still signed on its own, against the version you were shown, so one that changed since is refused while the rest go ahead, and nothing is applied. A draft your record leans against starts unticked. The same things happen from the terminal with ambit approve <id> --by=<who> and ambit reject <id> --by=<who> "why". When you are away from the machine, ambit dispatch <id> pushes the draft to a Slack, Discord or Telegram webhook, or an ntfy topic, with the commands that decide it; the decision itself still happens here, on a machine that holds the approval key.

Simulation is arithmetic on the graph, not on the host. An outage walks the transitive downstream closure of the chosen node and counts what stops working; an unlock takes a locked node whose other hard prerequisites are already met and lights what becomes reachable. Neither reads a config file or writes one.

Governance has its own loopback endpoints. GET /api/proposals lists drafts and their history, each with the hash an approval artifact binds. POST /api/proposals/:id/approve mints the same HMAC-signed approval artifact the terminal does and never applies, and POST /api/proposals/:id/reject records a no with its reason. POST /api/proposals/approve and POST /api/proposals/reject are the queue: an explicit list of drafts, each sent with the hash the page showed and decided on its own as the person at the browser, so one that changed since is refused while the rest go ahead. They decide drafts only, answer per id, and ask anything with no browser behind it for the local API token, since one request there decides up to fifty. GET /api/attention aggregates interventions per capability from the ledger. GET /api/audit is the trail the Audit view draws: acts, proposals, runs and delegation records merged newest first and cut once at a limit, with what a check printed left out. All of them bind loopback and reject a non-local origin before routing, like every route.

One run is drawn in time from what the ledger recorded, and no more. GET /api/run lays a run out: the capabilities it used for as long as each was measured to last, its events as points, and every time a person was asked, with permission asks in amber. An ask with both its times is a span, one with seconds and no end is a filled point that carries its figure, and one with neither is a marked point that says it was not timed. The OpenCode plugin logs a permission prompt and cannot see the reply, so most asks have no end, and an unmeasured wait is never drawn as zero. The total of a person's time in the run counts only the asks something timed, and says so. It is read only, and it is the same projection the Time & cost page draws.

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