amber-protocol
Advanced tools
Amber Protocol: repository-local governance kit for coding agents — install, audit, validate, and hand off agent-facing project state.
Governed Agent Harness for real engineering systems.
Amber Protocol is the governed execution boundary between AI agents and real systems. It governs what an agent may see, use, execute, and emit, with whose approval, and what evidence proves it — in files beside the code, not in chat history.
Amber Protocol 是 AI Agent 与真实系统之间的治理执行边界。
What is Amber · Who it is for · Journey · Install · Quick Start · Team Replication Charter · 简体中文
For repositories already using coding agents in real delivery work.
Plans, evidence, decisions, and handoffs stay inspectable beside the code.
Version: 2.0.1 · Status: Stable · Milestones & test status →
Amber Protocol is a repository-local governance layer for projects that already use coding agents in recurring, real delivery work. The hard part is no longer only producing code. It is preserving enough trustworthy state for the next person or agent to understand what happened, what was approved, what evidence exists, and what should happen next.
Amber makes that state explicit through plans, sessions, evidence, decisions, and handoffs stored beside the code. Its core outcome is Trusted Continuation: another person or agent can enter without the old chat, identify the current state, and take one correct next step.
Amber = the in-repo team replication layer: how a team safely uses AI on this codebase, written as handoff-ready file evidence.
It sits under your existing coding engine and adds governance plus evidence. It is not another agent runtime, and not an org-scale platform.
| Amber is | Amber is not |
|---|---|
| In-repo governance and evidence protocol | Org-scale Skill marketplace / plugin store |
| Reviewable plans / gates / approvals / handoffs | Cross-repo gateway or cross-machine control dashboard |
| Local conventions a team can replicate | Always-on scheduler / daemon that runs your project commands |
| Layer | Role |
|---|---|
| Engine | Edit code, call tools, run models and the agent loop (provided by your chosen coding host) |
| Governance (Amber) | Plans, gates, approvals, doctor/audit, handoff; evidence written as repo files |
| Upper Shell (optional) | Consumes Amber via MCP only; must not rewrite the .amber contract or push the agent loop into Amber core |
Engines do the work; Amber proves what was done, whether it is safe to keep, and how to hand it off.
These are product boundaries, not TODOs:
init / wiki only create missing files)Full boundaries: Team Replication Charter and SPEC.md.
The target environment is a Coding-Agent-Enabled Repository: maintainers already use one or more coding agents for ongoing delivery under human review. A one-off experiment or a repository that merely installed an agent tool does not qualify.
AI coding work becomes easier to trust when the workflow leaves inspectable evidence:
Fit -> Adopt -> First trusted continuation -> Deliver -> Recover -> Review / Accept
| Journey | User outcome | Default surface | Completion evidence |
|---|---|---|---|
| J0 · Fit | Decide whether Amber addresses a real continuity or review failure | amber audit | Read-only findings and an explicit adopt/defer decision |
| J1 · Adopt | Add the minimum repository-local surface without overwrites | amber init, amber doctor | A repeatable setup check |
| J2 · First continuation | Prove a fresh context can continue one real task correctly | amber next, amber plan, amber session, amber handoff | A new person or agent acts correctly without reading the old chat |
| J3 · Deliver | Frame, authorize, work, prove, review, and hand off/accept | Agent journey; CLI fallback | Plan, session, command evidence, and checkpoint agree |
| J4 · Recover | Resume after failure, pause, or context loss at the correct stage | amber session, amber next, amber handoff | Failure remains visible and the recovery action is bounded |
| J5 · Review / Accept | Make a go/no-go decision from repository evidence | Plans, gates, evidence, Web Viewer | Review and acceptance can be explained without the transcript |
Feature, bugfix, and refactor routes remain backend policy. Users keep one frontstage model:
Frame -> Authorize -> Work -> Prove -> Review -> Handoff / Accept
Context repair, continuous improvement, team expansion, and high-assurance operations are conditional paths. They do not block the first Trusted Continuation. See the feature matrix and complete journey definitions.
npm install -g amber-protocol
amber --version
git clone https://github.com/Bandersnatch0x/amber-protocol.git
cd amber-protocol
npm install
node scripts/amber.js --version
2.0.0 is a breaking release: three command families that shipped in 1.6.0 — and were already marked deprecated in its help text — are now removed. Nothing else changed shape: plans, sessions, gates, approvals, evidence, and handoffs keep their contracts.
| Removed in 2.0.0 | What to use instead |
|---|---|
amber agent dispatch|review|status | amber harness (the Contract → Run → Event spine); amber governance report |
amber team inspect|install|pin|update|rollback | amber maintenance (scaffold drift, artifact drift); amber doctor |
amber adoption report|list|index|validate|compare|gate|status|bundle|next-actions | amber governance report; the amber-diagnosis-adoption journey skill |
The disposition is recorded, not implied — the removed surfaces and their replacement routes stay readable from the tool itself:
amber harness legacy --target . # every removed surface with its replacement route
If you pin ^1.6.0, a npm update will not cross into 2.0.0 — that range deliberately stops
short of the break. Move to ^2.0.0 once you are off the removed commands.
Use one real task to test whether Amber creates Trusted Continuation. File generation alone is not activation.
# J0 — establish fit without changing the project
amber audit --target my-project
# J1 — install the minimum surface; existing files are skipped
amber init --target my-project
amber doctor --target my-project
# J2 — frame one real goal and follow the state-derived next step
amber next --objective "finish the current API change" --target my-project
# Generate a repository-local continuation bundle
amber handoff --target my-project
Now open a fresh agent session or ask another maintainer to inspect the repository without the old chat. Amber is activated only when that new context can explain the current state and take one correct next step.
init and wiki never overwrite existing files. Default help exposes seven fallback verbs: audit, init, doctor, next, plan, handoff, and session. amber --all keeps the expert and compatibility surface available. See the CLI reference.
Expert path (not the homepage main line): read-only continuous-improvement discovery via amber loop recommend — see the loop sections under "What It Won't Do" below.
Default amber --help projects seven primary verbs — the whole journey fits in them:
| Verb | What it does |
|---|---|
amber audit | Read-only readiness inspection of a repository |
amber init | Install the minimum repository-local surface (never overwrites) |
amber doctor | Validate the Amber setup |
amber next | Deterministic route advice for a stated objective |
amber plan | Scaffold a feature plan |
amber handoff | Produce the portable continuation bundle |
amber session | Inspect or manage the session lifecycle |
Everything else is governance and platform surface, deliberately one flag away in
amber --all:
wiki, context request|ingest|verify|refresh|stats, memory, knowledgeartifact, principal, evidence, approval, gate, policyprojection, adapter, maintain, retention, external, breakglass, eval runsync session, governance report, loop recommend, learnings, break-loop, harnessHiding a family from the default help changes discovery, never capability: every family is
documented in the CLI reference, and amber <family> --help is
authoritative for its flags.
The overlay ships as a native dsh-plugin bundle:
# Install once; dsh adds the Amber bundle layer to the profile
dsh plugin --profile web add dsh-amber-protocol
# Afterwards a normal start loads Amber (no repeated --patch)
dsh --profile web
On Windows the default port 3080 is often reserved; add --port 13080 if the listener fails.
Unpublished-checkout fallback: if you are developing Amber itself and the bundle is not
published yet, use an overlay patch instead. Edit dsh/amber-full.patch.yml, replace
/path/to/amber-protocol with this repository's path, and layer it at startup without touching
the profile:
dsh --profile web --patch /path/to/amber-protocol/dsh/amber-full.patch.yml
Full notes: dsh/README.md.
Amber organizes governance into seven control layers, weighted toward safety — the higher the priority, the more of Amber's surface that layer gets:
| Layer | Role in Amber | Priority |
|---|---|---|
Governance | Approval records, safe defaults, policy boundaries, and adoption controls constrain behavior. | Highest |
Verification | Doctor, audit, validation, review, and gate surfaces provide explicit checks. | High |
Observability | Timelines, manifests, ledgers, and reports make behavior inspectable. | High |
Lifecycle | Routes, sessions, checkpoints, and worktrees organize work locally. | Medium |
Context | Starter docs, wiki scaffolds, manifests, and handoff artifacts keep project context explicit. | Medium |
Tooling | CLI commands, schemas, validators, workflow packs, and profiles expose explicit interfaces. | Medium |
Execution | Gated and capability-bound — governed command execution exists behind four gates plus frozen per-attempt admission; there is no un-gated runtime, and no capability is registered in a vanilla install. | Low |
The through-line: strengthen Governance, Verification, and Observability; keep Lifecycle repository-local; avoid drifting into a full agent platform. The governance model maps each layer to concrete commands.
What gets installed — the minimum surface doctor checks for:
AGENTS.md and CLAUDE.md — agent-facing rulesfeature_list.json — tracked feature statePROGRESS.md, session-handoff.md, clean-state-checklist.md, evaluator-rubric.md.amber/continuous-improvement/state.jsondocs/wiki/ — project context, system map, runbook, verification, glossaryAll starter files are safe defaults. init and wiki skip existing files and report what would be created in dry-run mode.
These boundaries are part of the product, not TODOs:
session run stages fail closed until a capability is registered — and registering one is a reviewed code change, not a config editSince ADR-0003, Amber can run a loop contract's
declared governed.command — but only behind four gates: a declarative policy check
(.amber/governance/rules.json, deny-wins / default-deny), an explicit amber loop approve (one
approval authorizes one run), an isolated git worktree (your main checkout is never the cwd), and a
tamper-evident hash-chain ledger. Default loop run is still dry-run; execution needs --execute.
amber loop approve --file <pack> --contract <id> --reviewer <name>
amber loop run --file <pack> --contract <id> --execute
amber loop verify-ledger --contract <id>
amber governance standards --target . # honest OWASP-ASI coverage of what this does (and doesn't) cover
For the full boundary notes, see SPEC.md.
amber loop recommend — the safe continuous-improvement entryamber loop recommend is read-only: it scans the local workflow-packs' loop contracts, scores
them against a maintenance goal, and prints the dry-run command best suited to human review. It
never schedules work, executes workflow steps, dispatches agents, or writes an external system.
amber loop recommend --target . --goal "continuous improvement" --json
amber loop run --file workflow-packs/safe-amber-bootstrap.pack.json --contract daily-amber-triage --dry-run --json
Live scheduling stays outside the product boundary: loop run requires --dry-run.
Beyond the journey surface, Amber ships a contract-tested trust layer (four canonical contracts with product tests, all delivered):
session run attempt freezes its admission inputs (scope, policy, capability, request digest) before any effect; the gates re-verify against the frozen values, and authorization grants bind that frozen tuple with single-use consumption. Drift is refused at the gate, before execution.unavailable / observed / replayable / verified, and a replay bundle (amber handoff bundle --replay-scope) rebuilds the authorization chain offline.amber memory (request → ingest → human approve → book); MEMORY.md stays human-curated and hash-registered.amber eval run replays deterministic model-independent checks of the agent-facing surfaces.approvalRequired and are never executed by the MCP surface.These surfaces are the protocol's reference implementation: governed verb stages currently fail closed (no capability is registered — see "What It Won't Do") and the canonical specs are awaiting their coordinator re-review.
| Topic | Link |
|---|---|
| Full CLI reference | docs/CLI_REFERENCE.md |
| Getting started guide | docs/guides/user-getting-started.md |
| Architecture & governance model | docs/architecture/governance-model.md |
| Deployment & ops | docs/DEPLOYMENT.md |
| Monitoring / notifications / policy | MONITORING_SETUP.md · NOTIFICATION_SETUP.md · POLICY_CONFIGURATION.md |
| Troubleshooting | docs/TROUBLESHOOTING.md |
| Full docs index | docs/README.md |
| Spec & roadmap | SPEC.md · ROADMAP.md |
DeepSeek Harness (dsh) overlay | dsh/README.md |
| Contributing | CONTRIBUTING.md |
The public documentation site (apps/docs) provides reader-focused guides, concepts, and authoritative single-source CLI references with 100% offline local search:
npm run docs:build # Build the static documentation site
npm run docs:verify # Run the mechanical verification seam
npm run docs:gen # Generate CLI reference pages from command registry
npm run docs:gen:check # Verify zero drift between code and CLI reference docs
npm run docs:test # Run public documentation test suite
The optional Web Viewer (apps/web) is a journey-aware inspector. It shows the current J0–J5 stage, the next governed action, active sessions, pending gates, and repository-local evidence. It reflects Amber state; it does not create a second workflow or replace the Agent/CLI authority surface.
cd apps/web
npm install --legacy-peer-deps
npm run dev
# Visit http://localhost:3001
See CONTRIBUTING.md for development setup, CI, and the release process.
MIT License — see LICENSE for details.
Amber Protocol — the governed execution boundary between AI agents and real systems.
FAQs
Amber Protocol: repository-local governance kit for coding agents — install, audit, validate, and hand off agent-facing project state.
We found that amber-protocol demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Research
/Security News
Socket uncovered two malicious VS Code themes in a GlassWorm-linked cluster with thousands of installs across VS Code Marketplace and Open VSX.
Security News
/Company News
Capital One is partnering with Socket to proactively secure its open source supply chain.
Security News
Socket CTO Ahmad Nassri discusses how to keep AI agents from bypassing package blocks, limit credential access, and monitor their actions.