<div align="center">

Amber

Your agent figured the workflow out once. Stop paying for it every run.

An open implementation of FlashScript (USC & Microsoft, 2026), with the operating loop around it.

Record Claude Code doing a task a few times. Amber compiles the recordings into a readable Python program that does the same job on the next input: plain code for the mechanical steps, one small llm() call where judgment is needed, replay tests generated from the recordings, and guards that stop the run when the world changes. When it breaks, the agent takes over from the failed step and Amber recompiles.

<img src="https://raw.githubusercontent.com/enestanerr/Amber/main/docs/assets/demo.svg" alt="Amber demo: compile three recordings, run on a new week, the data drifts, the doctor hands the task back to the agent, Amber recompiles" width="860">

_{A real session on the weekly-report example, replayed with long waits shortened: compile three agent recordings, run on a week nobody recorded, rename a field in the shop API, watch the guard stop the run, the doctor recommend a fallback, the agent resume from the failed step, and the recompiled v2 verify 4/4.}

</div>

---

Contents

• Why Amber · Measured results
• Install · Try it in two minutes
• Use it with Claude: how Amber uses Claude · record headless runs · import an interactive session · Agent SDK · Claude Desktop and other MCP clients · the Claude Code plugin
• Compile your own workflow, step by step
• How it works · What comes out · Safety model
• Commands · Configuration · Troubleshooting
• Limitations · Roadmap · Related work · FAQ

Why Amber

• Agents re-derive everything, every time. Our weekly-report agent spends ~170k tokens per run rediscovering the same seven tool calls: list the orders, take two RFM snapshots, pick the top products, post a summary.
• Most of that work is mechanical. Only the summary needs judgment. Amber keeps the judgment as a small, schema-validated llm() call and turns the rest into code.
• It is a compiler, not a cache. Arguments are explained by provenance (an input, an earlier result, a template, a constant), so the program generalises to inputs nobody recorded. Holes the model fills are checked against the recordings before they are accepted.
• It knows when it is wrong. Every live call is guarded. When the world drifts, the doctor says what changed and the agent resumes from the failed step; its new run is folded into the next version.

The idea comes from FlashScript (arXiv 2610.33876), which compiled agent trajectories into neuro-symbolic programs with ~70× fewer input tokens and released no code. Amber is an open, harness-agnostic implementation with the operating loop around it.

Measured results

Live run on 2026-11-02 (bench/results.md): claude CLI 2.1.316 on a claude.ai subscription, agent claude-sonnet-5-5, compiled judgments claude-haiku-5-5, three recordings and three compiled runs per example, synthetic mock servers.

| example | agent tokens / run | compiled tokens / run | fewer tokens | agent $ | compiled $ | agent turns | tool-call fidelity | |---|---|---|---|---|---|---|---| | issue-triage | 153,944 | 11,892 | 12.9× | 0.087 | 0.003 | 0 | 100% core · 67% exact | | price-watch | 165,225 | 14,862 | 11.1× | 0.071 | 0.003 | 0 | 100% core · 100% exact | | weekly-report | 174,076 | 29,472 | 5.9× | 0.170 | 0.008 | 0 | 100% core · 0% exact |

Medians. $ is the API-equivalent cost the CLI reports; a subscription is not billed per call, and part of the cost gap is Haiku versus Sonnet. Core fidelity compares the program's tool calls with the recording minus the agent's exploratory reads, which the compiler prunes; exact compares everything. weekly-report's compiled run is not faster (its judgment thinks ~25 s while counting 240 RFM rows, correctly). FlashScript's 70× is the paper's number, not ours.

Install

uv tool install amber-compiler        # or: pipx install amber-compiler
amber --version                       # amber 0.1.2

Optional extras: [ui] for the local web panel and [sdk] for the Claude Agent SDK recorder:

uv tool install "amber-compiler[ui,sdk]"

You need Python 3.12+ (uv installs it for you) and one way to reach Claude: a logged-in Claude Code CLI (a Pro or Max subscription is enough, no API key) or ANTHROPIC_API_KEY. The price-watch example also needs Node 18+. To follow main instead of the latest release: uv tool install git+https://github.com/enestanerr/Amber.

Try it in two minutes

No Claude needed: the offline demo uses the synthetic recordings and recorded model answers.

git clone https://github.com/enestanerr/Amber && cd Amber
uv sync --all-extras
cd examples/weekly-report
make demo-offline          # seed recordings → compile → verify 3/3 → dry-run against mock servers

Then do it live with your own Claude login (inside the checkout, amber is uv run amber):

make record                                                   # 3 real claude -p runs on Sonnet
uv run amber align weekly-report --show                       # the skeleton the runs share
uv run amber compile weekly-report                            # program + replay tests, verified
uv run amber run weekly-report --input week=2026-W40 --allow-writes   # 0 agent turns, 1 llm() call
make drift && uv run amber run weekly-report --input week=2026-W41 --allow-writes   # guard stops it
uv run amber doctor weekly-report                             # degraded → recommendation: fallback
make heal                                                     # agent resumes → compile --refresh → verify

docs/user/quickstart.md shows the real output of every step. On Windows, run make from Git Bash or type the commands from each example's Makefile.

Use it with Claude

How Amber uses Claude

Amber talks to Claude in three places, and you choose the model for each:

| phase | what runs | default model | set it with | |---|---|---|---| | record | your agent doing the task, start to finish | whatever you pass | -- claude -p "..." --model claude-sonnet-5-5 | | compile | filling the typed holes: transform code, judgment prompts and schemas | claude-sonnet-5-5 | [models] synthesis in amber.toml | | run | only the judgment steps of the compiled program | claude-haiku-5-5 | [models] judgment |

[models] backend = "auto" uses the Anthropic API when ANTHROPIC_API_KEY is set and otherwise the logged-in claude CLI (claude -p --json-schema, stripped of tools and session files, at low effort for judgments). Both are first-class: everything in Measured results ran on a subscription with no API key.

There are five ways to bring Claude into Amber:

A. Record headless Claude Code runs

The recommended way. amber record wraps claude -p and turns its stream into a trace:

amber record weekly-report --input week=2026-W42 --mcp mcp.json \
  --allow 'mcp__shop__*' --allow 'mcp__slack__*' --permission-mode acceptEdits \
  -- claude -p "Pull the orders for week 2026-W42, ... post a summary to #eng." \
     --model claude-sonnet-5-5 --setting-sources user

| flag | why | |---|---| | --input k=v | declares what varies between runs; the compiler explains arguments in terms of it | | --mcp mcp.json | the MCP servers the agent may use; Amber adds --strict-mcp-config so your account-level connectors stay out, and reads the real tool schemas for drift detection | | --allow PATTERN | pre-approves tools: a recording runs unattended, and a permission prompt aborts it | | --model ... | always explicit, so recordings never run on your default (maybe most expensive) model; the fallback reuses it | | --setting-sources user | keeps the project's CLAUDE.md out of the recorded context | | --disallowedTools Read,Glob,Grep | optional: stops the agent reading files when it should use tools |

Record two or three runs with different inputs: identical runs give the compiler nothing to generalise from.

B. Import an interactive Claude Code session

Did the task by hand in Claude Code? Import the session afterwards from the same directory:

amber import weekly-report --latest --input week=2026-W42     # newest transcript for this directory
amber import weekly-report ~/.claude/projects/<dir>/<session>.jsonl --input week=2026-W43

C. The Claude Agent SDK

amber record weekly-report --sdk --input week=2026-W42 --mcp mcp.json -- claude -p "<task>"

Runs claude_agent_sdk.query in-process (install the [sdk] extra); the trace format is the same.

D. Claude Desktop or any MCP client

Put amber proxy in front of each server in the client's MCP config. It forwards everything unchanged and logs each call:

{
  "mcpServers": {
    "shop": {
      "command": "amber",
      "args": ["proxy", "--name", "shop", "--trace-dir", "/abs/path/my-project/.amber/proxy",
               "--", "uv", "run", "/abs/path/my-project/server_shop.py"]
    }
  }
}

Do the task in the client, then fold the logged calls into a trace:

amber import weekly-report --proxy .amber/proxy --input week=2026-W42 --since 2026-11-02T10:00:00

E. Let Claude Code drive Amber: the plugin

This repository is a Claude Code plugin marketplace. Install the Amber plugin once:

/plugin install amber --marketplace enestanerr/Amber

From a terminal it is claude plugin install amber --marketplace enestanerr/Amber. On Claude Code before 2.1.275, add the marketplace first (/plugin marketplace add enestanerr/Amber), then /plugin install amber@amber-compiler. It adds two skills:

| skill | what Claude Code does with it | |---|---| | /amber:compile [workflow] | sets up the project, writes the task prompt, records three runs (asking before each costs tokens), reads the skeleton with you, compiles, verifies, dry-runs, then runs with your consent and schedules it | | /amber:heal [workflow] | runs the doctor, explains the findings, picks recompile, fallback or re-record, and verifies the new version |

You can also just ask: "compile this weekly report workflow with Amber" or "the Amber run stopped, fix it". The skills load from their descriptions.

Run compiled programs anywhere

A compiled program is a CLI call, so Claude Code (through Bash), a script, cron or CI can run it:

amber run weekly-report --input week=2026-W40 --allow-writes

For inputs that never change, Amber's own scheduler is enough:

amber schedule add price-watch --cron "0 9 * * *" --input product=all && amber scheduler

Schedules store fixed inputs. For a date-relative input suc