How Adage plugs into Claude Code.

A transcript becomes a prompt followed by a flat list of steps. Tool calls that share one message id form one turn; results join their calls by id, wherever they appear. A compound shell command splits into one step per sub-action, and a failure is blamed on its last part only, unless the command used ||.

Each step gets a template key, with specifics replaced (a ticket becomes {id}), and an effect. Effects are ranked, and the rank caps how strongly a step may ever be directed (shown above).

Observe and verify steps may fire. A regenerate step fires only after its edit. An install primes at most and starts nascent until a person reviews it. Edits and publishing are never directed. Only the hook's own output counts as a directive: what a directive named is exposed from the moment it arrived, and is no evidence for a reflex that directs it, so a reflex never learns from its own advice. Sub-agent transcripts are read too.

In the code: crates/adage-learn/src/{lib,import,codex,opencode,cache}.rs · crates/adage-core/src/types.rs

The graph engine is Adage's only learner, and it has no list of reflex kinds to look for: a reflex is whatever reliably precedes a step, and how it is delivered follows from its shape. Events are embedded and clustered into prototype labels, so each trace becomes a string, and repeated subgraphs become repeated substrings. Mining starts from a step worth delivering and grows closed patterns around it. A pattern is read as a prediction, after this context, this follows, with s supporting traces out of n opportunities. Its confidence is shrunk toward its parent pattern's confidence m (shown above).

Counts are discounted with a 60-day half-life, and a candidate is judged by the posterior's 5% quantile, q_0.05. Calibration then compares posterior means with held-out outcomes on 3 task-grouped folds, using isotonic regression over 200 bins.

Frequent is not the same as useful, so selection is by minimum description length: a reflex earns its place by describing the traces in fewer bits.

A pattern in the code table costs its items' codes, plus 4 bits per item and log₂ 6 bits for its length. Tables fill best gain first, re-checking each gain before accepting it. Candidates that would deliver different directives never compete: each delivery shape gets its own table, and dead ends one per failing runner. Winners compile to delivery shapes (run, avoid, read-batch, obligation, sequence, advise), and every compiled reflex is then counted again on the traces as its own trigger and step read them (Evidence, below); until then it is provisional, prime at most. An interlock drops any reflex that would direct a runner a dead end says fails. Survivors go to one track per repository, <repo>/learned, with a .why.json beside it for people. On the offline bench's core suite, a deterministic replay whose committed baseline cargo test reproduces exactly, the learner scores J 0.6307. The synthetic sessions carry that score; the recorded demo sessions score below zero. It is a regression check, not a measure of savings.

In the code: crates/adage-graph · crates/adage-learn/src/{bridge,engine}.rs · design: docs/tracks/track-g-graph-engine.md

Every advisory reflex the learner compiles is judged again on the traces, exactly as its own trigger and step read them. Evidence is counted in distinct traces, and a trace a directive already steered toward the step is left out. Out of n traces where a reflex had its chance, k took its path. A rate from few traces is uncertain, so strength is judged by the lower end of the 95% Wilson score interval, not by the rate (shown above).

Predictive execution has a separate test: by default, at least five unsteered sessions across more than one task, with a compatible successful continuation supporting at least 90% of matching edit or sequence contexts. Intervening observations are allowed within a bounded window; later mutations and task changes end it. Every matching opportunity counts, including those without a supporting outcome. This evidence creates a candidate for human execution approval; it grants no permission and proves no savings by itself.

Fire

LB ≥ 0.80 and k ≥ 5, within the effect's ceiling

Prime

a new reflex primes at a rate of 0.50; an existing one keeps its place down to 0.30

Finish line

the command must belong to the edit: $P(c\mid e)-P(c\mid \neg e)\ge 0.30$

Dead end

the runner fails in ≥ 9 of 10 traces that ran it, a different check that works follows it, and the pair appears in ≥ 5 traces; a dead end inhibits

Distinct tasks

the traces supporting a step after an edit or a command must span at least 2 tasks

Outcome lift

a step too few traces took can still prime, never fire, when the traces that took it succeeded more often than those that did not: the 95% lower bound on the difference ≥ 0.20

In the code: crates/adage-tracks/src/model.rs (wilson_lower, ceiling) · crates/adage-learn/src/{engine,evidence}.rs · crates/adage-tracks/src/params.rs

A step agents always take on their own is not worth saying. For each reflex Adage estimates two rates: p_follow, how often agents take the step when told, and p_self, how often they take it unaided. Each is a Beta posterior that starts from a prior for its kind of directive and is updated by this repository's evidence: unexposed traces in the same situation and the control arm's would-have judgements for p_self, treated judgements for p_follow.

Quiet

a reflex with u < 0.10, once at least 3 situations of the repository's own evidence say so, is kept nascent, listed in adage review as quiet, until a person approves it; a prior alone never silences one

Priors

p_self from randomised control data: 0.29 for a dead end, 0.32 for a run after an edit, 0.88 for a finish line or a sequence, 0.93 for reading listed files, 0.95 at the prompt; p_follow 0.88–0.99 by kind

Not gated

procedure cards, reflexes a person wrote, and the demo thresholds, where uplift is still estimated and shown

In the code: crates/adage-learn/src/value.rs (uplift, assess) · crates/adage-tracks/src/params.rs (UPLIFT_MIN)

Prompts are cut to their first 128 words, with tickets, paths, URLs, SHAs, versions and code replaced by placeholders. A static model bundled in the adage binary (potion-base-8M, int8, 7.7 MB, SHA-256 pinned; nothing to download) embeds each one as the mean of its WordPiece token rows, scaled to unit length, so similarity is a dot product (shown above).

Each prompt links to its 10 nearest neighbours (found exactly, ties broken by index), and links below cosine 0.60 are cut. Louvain then groups the graph by modularity, visiting nodes in a fixed order so the result never varies:

A community becomes a family when at least 60% of its traces took the same first route (the first check or lookup before editing). Routes that appear in more than 80% of all traces say nothing about intent and are ignored. Each kept family gets its own threshold, chosen on this repository's prompts:

Here n_t counts prompts at cosine ≥ t from the family centre and k_t those whose trace ran the family's route. At the hook, a new prompt matches the most similar centre whose threshold it clears; it fires only if that family's LB reaches 0.80, and otherwise primes. With the explicit hashed fallback in place of a model there are no intent reflexes, and nothing fails.

In the code: crates/adage-graph/src/compile/intent.rs · crates/adage-intent

Most work in a repository is a variation of something done before. Two traces are one family when their first prompts are similar and the files they edited have the same shapes (directory, name tokens, extension, so flag_url.go and flag_port.go agree) (shown above).

A family with a passing trace gets a card: the files edited in at least half its traces, in order, with the lines the latest passing trace added; the commands most traces ran, kept when they mostly worked and listed to avoid when they mostly failed; and the check the passing traces finished with.

The delivered card leaves those added lines out. In their place it says where the card's files stand in the checkout when it is delivered: each file's line count, a Python source's last top-level definitions with their lines, a test file's last lines and a changelog's first headings. Adage reads them itself, read-only, and runs no command. This orientation has been measured only in one development study on a single task; the card benchmarks used the earlier form.

Forms

from at least 2 traces, one of them passing; at most 16 cards per repository, the best supported

Delivered

once per session, as prime, when a new prompt's best cosine to the family's prompts reaches 0.811 (learn.card_threshold); up to 0.10 below, at the first edit of one of the card's files

Bounded

at most 800 tokens, plus at most about 1,200 for the orientation; never quotes .env files, files git ignores, or anything that looks like a secret; never shared in a pack

Verified

adage train cards replays a card's commands on a clean checkout in a sandbox, and the next learn keeps only those that worked

In the code: crates/adage-learn/src/cards.rs · crates/adage-tracks/src/card.rs

adage train <SKILL.md> compiles a skill's procedure into one pack of reflexes by rules, with no model and no agent session: which command, after which edit, in which order. Every compiled command is replayed on a clean checkout of HEAD in adage-exec's sandbox, with the network off, your working tree untouched and the .venv lent read-only. A command that fails there is stale and dropped; one that could not be replayed is kept at prime at most; judgment stays text. Nothing is installed until adage train accept.

Skill-steered sessions are optional evidence, and they cost money. The skill's claims get generated tasks plus controls, your own agent runs each headlessly in a sealed clone with no remote, the traces go through the same learner, and reflexes are staged at prime, never activated. Held-out tasks then run in three arms: no skill, the skill in the prompt, and the staged reflexes through the hooks. A reflex is accepted when (shown above).

Here f is the share of sessions that followed the step and c the cost in turns or dollars. A claim the agents contradict, like a test command that fails where another works, comes back as a dead end, and the skill is told which of its claims are stale.

In the code: crates/adage-train/src/{compile,verify,report}.rs · docs/training.md

Every installed track compiles into one list. The same behaviour gets the same id wherever it was found, so duplicates collide, and precedence decides which copy stays: your own evidence, then a teammate's signed pack, then an instinct. The survivors are serialised in order and hashed, and the hook reads only that file (shown above).

Tracks are versioned: evidence moving bumps the patch number, an added reflex the minor, a changed or removed one the major. Imported reflexes start forming and never fire until your own traces confirm them. Instincts, 8 in the default set, deliver as prime at most and extinguish themselves if they keep misfiring. Tracks and the index are readable by their owner only.

In the code: crates/adage-tracks/src/{index,interlock}.rs · adage-instincts · adage-pack

Each hook event runs a pure function of the event and the index. Before anything is said, the session is assigned to an arm by a hash, so the assignment is stable and reproducible (shown above).

A control session runs the same decision, records what it would have said, and stays silent. Each record carries its propensity, the probability of the arm it got. The share is 0.10 unless runtime.control or ADAGE_CONTROL sets another.

On Claude Code the hook also runs before each shell command (PreToolUse), for the one change Adage makes by default: a Python test run or scratch repro under the system Python, in a repository whose .venv was verified to hold pytest and the project, runs with .venv/bin/python instead. The command is read as a shell reads it, and only the command word of a top-level simple command changes: never a heredoc, a quoted string or a -c payload. A command that activates an environment, cds outside the checkout or pins another Python version is left alone; one your permission rules would not allow once rewritten gets advice instead. You see each rewrite, a control session records it without rewriting, and adage delegate rewrites off (or runtime.rewrite = false) turns it off.

Slots

a value from the prompt binds only if it matches the contract learned from real values and is a plain token: at most 200 characters from A–Z a–z 0–9 _ . / : @ = + , -, with no leading dash

Followed

a directive stays pending for 3 tool batches; it is followed if a batch runs its canonical command (options may be added), ignored otherwise, and misfired when the agent followed it and the command failed

Wrapper

each directive reaches the agent as <adage-reflex track="…" route="…" strength="…" kind="…">, with a last line saying where it came from

Fails open

if the hook errors or runs out of time, the agent carries on as if Adage were not installed

Approved execution is a separate path. With adage-exec enabled and a local grant for the exact reflex, E1 prefetches a read-only result; E2 runs an action in a disposable stage and applies permitted outputs. The invocation is selected and run on the CPU without a model request. The next model request may still consume its result. Learning a command does not approve it, and a delivered procedure card does not demonstrate CPU execution or saved turns.

When a person has approved one learned verification, Adage owns it in treated sessions: at the session start the agent is told which command Adage runs and when; after a run it gets a short receipt naming the tests that ran, including the ones it added; and when it finishes, Adage runs the check again if it has not passed on the current files, asking the agent to continue once if it fails. A person is told in one line when an approval stops matching. On real repositories it has so far one development result, on a single task, and no held-out result. Savings are counted in model calls, tokens and API cost; GPU use and energy are not measured.

In the code: crates/adage-runtime/src/{lib,pretool,render}.rs (assign_arm) · crates/adage-hook

Runs of one task are not independent, so the task, not the run, is the unit. For each of J tasks, compare the arms' means, then average over tasks (shown above).

No distribution is assumed. Arm labels are shuffled within each task, never across tasks, 10,000 times, and the p-value counts how often chance does at least as well:

Whether the effect would hold for new tasks is a separate question. A sign-flip test over the task differences answers it exactly up to 16 tasks, where its smallest possible p is 2/2^J:

Turns, cost and pass rate are tested together, so Holm's step-down corrects for looking at several metrics. With the m p-values sorted ascending:

Interval

a 95% percentile bootstrap that resamples whole tasks 2,000 times

Per reflex

a share is stated only with at least 10 treated and 5 control traces

Offline bench

before any agent runs, a learner scores $J=\text{turns saved}-2.0\times \text{false directives}+1.0\times \text{route F1}$ per session

Your savings

adage savings estimates, per session, control minus treated: API-list-equivalent cost, model turns and turns to the first edit, each session weighted by its recorded propensity (Hajek), winsorised at the 95th percentile, with an expanded percentile interval from 2,000 bootstrap resamples stratified by arm. Dollars appear only with at least 10 control and 30 treated sessions; before that, counts. Beside it, always: how often each arm ended asking the person for help

In the code: crates/adage-cli/src/savings.rs · demo/report.py (cluster_perm_p, task_signflip_p, cluster_boot_ci, holm) · crates/adage-eval · evals/live