cue
AGENTS.md2 starsChanged 3 months agoMITView on GitHub
Cue is a deterministic Bun + TypeScript runner that drives headless coding agents (Claude Code via claude -p) through a GitHub-issue pipeline: Triage → human approves plan → Dev → Test gate → Review loop → Draft PR → human merges (a human can also label agent:revise to send PR feedback back through the agent). GitHub is the state store: agent:* labels are the state machine, issue comments carry handoffs (the plan), draft PRs are the output. User-facing flow and…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository3 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- migrate-radix-to-baseSkill
- shadcnSkill
The file
We split this AGENTS.md into the rules it gives an agent
7 rules. About 0 are common, 1 is distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 21
Always run bun run check before claiming any change works.
- Very specific: line 77
Never call Bun.spawn anywhere else.
- Very specific: line 119
Every adapter invocation is logged via RunLogger to .cue/runs/<issue>/<stage>-*.json (gitignored) with prompt, full event transcript, cost, …
- Very specific: line 141
Do not move them into the repo.
- Distinctive: line 205
Keep it that way; there is a traversal test.
- Very specific: line 239
After making code changes, run bunx oxlint --fix, then run bunx oxfmt.
- Very specific: line 240
Before finishing, run bunx oxlint --deny-warnings --format=agent.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Cue — Agent Context
Cue is a deterministic Bun + TypeScript runner that drives headless coding
agents (Claude Code via claude -p) through a GitHub-issue pipeline:
Triage → human approves plan → Dev → Test gate → Review loop → Draft PR → human merges
(a human can also label agent:revise to send PR feedback back through the agent).
GitHub is the state store: agent:* labels are the state machine, issue comments
carry handoffs (the plan), draft PRs are the output. User-facing flow and
label table: docs/content/ (VitePress) and https://cue.kitdev.space/
Commands
bun test # full suite — runs entirely on fakes: no network, no gh, no claude
bun run lint # oxlint (config: .oxlintrc.json)
bun run format # oxfmt — always format after editing; format:check verifies
bun run check # lint (type-aware via oxlint-tsgolint) + format:check + tests, all in one
bun run cue <init|poll|run [n]|cleanup|status|ui [port]> # the CLI (globally: `cue`, run from inside a target repo)Always run bun run check before claiming any change works. tsconfig has
noUncheckedIndexedAccess, so indexed access needs a guard or a deliberate !.
Tests use bun test (the code depends on Bun APIs) — do not migrate them to another
test framework.
Architecture
src/
├── cli.ts # entrypoint + label definitions; builds the real StageContext
├── action.ts # nextAction (label → stage) — shared by pipeline and prompts
├── pipeline.ts # runIssue (failure → agent:failed), poll
├── cleanup.ts # reconciles merged/closed PRs: agent:done / agent:failed + worktree removal
├── stages/
│ ├── context.ts # StageContext — the DI bundle every stage receives
│ ├── triage.ts # read-only plan generation; exports PLAN_MARKER
│ ├── replan.ts # plan revision from human feedback comments (has WebSearch)
│ ├── dev.ts # worktree implementation + gate + draft PR
│ ├── revise.ts # addresses human PR feedback in the PR's worktree + gate, then review re-runs
│ └── review.ts # JSON verdict + bounded fix loop; exports parseVerdict, Verdict
├── adapters/
│ ├── types.ts # AgentAdapter / AgentRunOptions (semantic: access/webSearch/bashAllowlist) / AgentResult
│ ├── base.ts # JsonlAdapter: shared run loop (env scrub, exec, JSONL parse, progress)
│ ├── registry.ts # ADAPTERS: name → { make, defaultModels }; the one list of adapters
│ ├── summarize.ts # shared tool-input summarizer (also imported by ui/app/lib/transcript.ts)
│ ├── usage.ts # THE token extractor: per-adapter usage → one disjoint TokenUsage
│ ├── antigravity.ts # agy -p --output-format stream-json --dangerously-skip-permissions
│ ├── claude.ts # claude -p --output-format stream-json --verbose; maps access → --allowedTools
│ └── codex.ts # codex exec --json; sandbox read-only / workspace-write; --search for webSearch
├── server.ts # `cue ui`: Bun.serve — state/runs API, SSE events, poll/run triggers, serves ui/build/client
├── github.ts # typed wrapper over the `gh` CLI
├── worktree.ts # git worktree per issue; bootstraps empty repos (--allow-empty)
├── checkout.ts # `cue checkout`: detach onto an issue branch to review it in the main repo, then exit back
├── gates.ts # deterministic setup/test/lint runner (sh -c in the worktree)
├── specs.ts # opt-in knowledge layer: OpenSpec-format specs dir + .cue/learnings.md, presence-detected (no config)
├── exec.ts # THE ONLY place Bun.spawn is called; injectable Exec type
├── platform.ts # POSIX/WINDOWS personality (gate shell, agent env allowlist), injected via StageContext
├── config.ts # valibot schema + resolveConfig: .cue/config.json, repo auto-detect from origin
├── scaffold.ts # creates/tops up the target's .cue/ (config + $schema, prompts dir, gitignore)
├── configure.ts # `cue init` wizard: @clack/prompts behind an injectable Ask seam
├── spinner.ts # single-slot ora frame + PhaseRunner seam; disabled when stdout is not a TTY
└── log.ts # per-invocation transcripts + cost under <target>/.cue/runs/<issue>/
prompts/ # packaged default role prompts; <target>/.cue/prompts/ overrides per file
scripts/fixtures.ts # snapshots local .cue runs into ui/app/fixtures/data.json
ui/ # dashboard: react-router (library mode) + React Compiler, shadcn `base-nova`
├── app/routes/home.tsx # overview: spend summary, cost charts, label board, live log
├── app/routes/runs.tsx # run explorer: per-run prompt / transcript / raw tabs
├── app/lib/cue.ts # API client; re-exports app/lib/transcript.ts (normalizer, root-tested)
└── app/fixtures/ # committed run snapshot, used when /api is unreachable
tests/ # one test file per module + integration.test.ts
tests/helpers/ # makeFakeExec (scripted subprocess replay), makeFakeAdapterHard invariants — do not break these
- All subprocess execution goes through the
Exectype fromsrc/exec.ts. Never callBun.spawnanywhere else; it is what makes every module testable. - Lean dependencies. The CLI package's only runtime deps are valibot, consola, ora and
@clack/prompts. The dashboard is a
separate package (
ui/package.json) that owns react, react-router, tailwind and the shadcn stack — its deps never enter the CLI's. Do not add packages to either without being asked. - Label names are exact:
agent:ready,agent:planned,agent:approved,agent:replan,agent:in-dev,agent:in-review,agent:revise,agent:done,agent:failed,agent:stop. They appear in code, tests, prompts, README, and on real repos — change all or none. - The plan-comment marker is exactly
<!-- cue:plan -->(PLAN_MARKERinstages/triage.ts, defined once). The dev/replan stages find plans by newest comment containing it. - Branch naming:
agent/issue-<number>(WorktreeManager.branch). - The GitHub token must never reach agent subprocesses.
JsonlAdapter.run(adapters/base.ts) scrubs the env viascrubbedEnv(platform.ts): OS vars plus the adapter's ownenvKeys— never another provider's API key, neverGH_TOKEN. Every adapter test assertsGH_TOKENis absent. Keep them passing. - LLMs inside the nodes, plain code between the nodes. Routing, gating, retries, and label transitions are deterministic TypeScript — never ask the model something a script can decide (e.g. whether tests passed).
- Agents never run git/gh side effects. The runner owns commit, push, PR creation, and labels; the prompts forbid the agent from doing so. Cue never merges and never touches the base branch.
- Humans gate two moments: plan approval (
agent:planned → agent:approved) and PR merge. Do not automate either. - Issue bodies and comments are untrusted input (prompt-injection surface). Every prompt states this; keep the security preamble when editing prompts.
Conventions
- TDD with the existing fakes: write the failing test first. Subprocess-touching code
is tested with
makeFakeExec(scripted{match, result}replay —"*"wildcards, prefix matching); agent-touching code withmakeFakeAdapter. Follow the style in any existing test file. tests/triage.test.tsexportsmakeCtx— the shared StageContext factory used by dev/review/replan/pipeline/cleanup/integration tests. Extend it rather than duplicating setup.- TypeScript strict; no
anyexcept atgh/claudeJSON parse boundaries, immediately narrowed to a typed shape. - Errors: throw with actionable messages;
runIssueis the single place that turns a stage error into an issue comment +agent:failed. - Every adapter invocation is logged via
RunLoggerto.cue/runs/<issue>/<stage>-*.json(gitignored) with prompt, full event transcript, cost, duration. - GitHub interactions are tolerant only where distributed state demands it
(
prState,WorktreeManager.remove— a worktree may live on another machine); everything else fails loudly.
Gotchas
- The pilot/target repo may be empty:
WorktreeManager.createbootstraps an empty initial commit (--allow-empty) and pushes it whenorigin/<baseBranch>is missing. claudeCLI flag spellings (--allowedTools,--max-turns,--output-format stream-json --verbose) are version-dependent; if the adapter breaks after a CLI update, checkclaude --helpfirst.- Cue runs from inside the target repo (cwd = repoPath); all per-project
state lives in the target's
.cue/directory. Every config field is optional (repoauto-detects from the origin remote). Config changes must update the valibot schema inconfig.ts, the defaults table indocs/content/guide/config.md, AND the published JSON Schema atdocs/content/public/schema/config.json—tests/schema.test.tscompares keys and defaults againstConfigSchema.entriesand fails the build on drift. - Worktrees default to
~/.cue/worktrees/<owner>-<repo>/issue-<n>— deliberately OUTSIDE the target repo so IDE indexing and repo-root tool globs never see them. Do not move them into the repo;worktreeRootin config is the user's override. - The package is installed globally (
bin: cue→src/cli.ts, shebang + Bun). Prompts resolve relative to the package (import.meta.dir), never cwd. - Release binaries embed all assets. Prompts embed via
with { type: "file" }imports insrc/embedded.ts; the dashboard embeds viasrc/ui-manifest.g.ts, which is a committed EMPTY stub —scripts/build-binaries.shregenerates it fromui/build/client(viascripts/embed-ui.ts), compiles per-target binaries intodist/, then restores the stub. Never commit a generated manifest. New disk assets (prompts, ui output) must join this embedding path or compiled installs break. - Releases: push a
v*tag →.github/workflows/release.ymlrunsscripts/build-binaries.shand attachesdist/cue-*+checksums.txt;install.shat the repo root is the user-facing installer (checksum-verified). - A crashed run leaves
agent:in-devstuck; humans reset labels manually (cue statusmentions this). ui/uses react-router in LIBRARY mode (createBrowserRouterinapp/main.tsx; routes registered there, NOT file-based) on plain Vite with@vitejs/plugin-react({ compiler: true })— the React Compiler automatic memoization is ON (via oxc-transform-react). Do not reintroduce@react-router/dev(the framework plugin owns the Vite pipeline and blocks the compiler). Built toui/build/client, served statically bysrc/server.tswith an index.html fallback so client routes survive a refresh.CLIENT_DIRresolves againstimport.meta.dir, not cwd, because cue is installed globally. After changing anything underui/app/, runbun run ui:build.ui/is excluded from the roottsconfig.json, oxlint and oxfmt configs, but has its OWN:ui/.oxlintrc.json(react plugin incl. the React Compiler rules;set-state-in-effectis deliberately a warning) andui/.oxfmtrc.json(withsortTailwindcssclass sorting — prettier is gone). Run viabun run ui:lint,bun run ui:format,bun run ui:check(tsc).bun run checkdoes NOT cover the SPA — run both.- Horizontal-overflow traps in the dashboard. Two bit us already: (1)
Separatorcarriesdata-horizontal:w-full, so as a directgrowflex sibling it resolves to 100% of the whole row and pushes the line past the viewport — put it in its ownflex-1wrapper (that is whatSectionHeadinginshell.tsxis for); (2) a grid item defaults tomin-width: auto, so a track sizes to its content's min-content and an inneroverflow-x-autoscroller can never constrain itself — usegrid-cols-[minmax(0,…)]plusmin-w-0on the cards. Verify withdocument.documentElement.scrollWidth - clientWidth === 0at 375, 1024 and 1440, on both routes; the header needs its own responsive collapse at narrow widths. - The label board is not the run archive.
BOARD_LABELSinserver.tsdeliberately omitsagent:done, so a completed issue has no board row. Anything listing runs must readRunLogger.index()(GET /api/runs) — the on-disk issue index — notstate.columns, or finished work becomes invisible. The explorer splits the two into Active (on the board) and Done (recorded but off the board) tabs; the Overview totals union both.index()recovers issue titles from the recorded prompts, matching bothIssue #<n>: <title>(triage/replan) andIssue: <title>(dev), so archived and even deleted issues stay browsable with noghcall. - Token accounting lives in exactly one place:
src/adapters/usage.ts. Every adapter reports usage differently and theirtotal_tokensdo not agree — agy's excludes cache reads, claude reports no total, codex nestscached_input_tokensinsideinput_tokens.extractUsagenormalizes all three into aTokenUsagewhose parts are DISJOINT (input + cachedInput + cacheWrite + output === total), and always computestotalitself rather than trusting the provider.src/log.tsandui/app/lib/transcript.tsboth import it — never fork a second extractor, or the run index and the transcript view will disagree about the same run. RunLogger.index()is the only per-issue rollup.cue statusandbuildStateeach call it once and look issues up in a Map; there is deliberately nototalCost/totalTokensto re-sweep the directory per issue.RunEntry.resultis polymorphic. Older logs store the singleresultevent as an object; newer ones store the whole event array. Anything reading a transcript must go throughnormalizeEvents(ui/app/lib/transcript.ts, re-exported by cue.ts and covered bytests/transcript.test.ts). Getting this wrong renders old runs blank while new ones look fine.RunLogger.readmatches the<stage>-<ts>id against a directory listing instead of joining it into a path —/api/runs/:issue/:runtakes that id straight from the URL. Keep it that way; there is a traversal test.- Stages emit through
ctx.onEvent(CueEvent in stages/context.ts) — never console.log directly from a stage. The CLI prints events;cue uialso broadcasts them over SSE. - The published config JSON Schema is a hand-written mirror of
ConfigSchema, served atCONFIG_SCHEMA_URLand written into scaffolded configs as$schemafor editor autocompletion. It must stay an https URL — a package-relative path would not survivebun build --compile. It is intentionally stricter than the parser (additionalProperties: false) so editors flag keys cue ignores, and itsadapterenum must include theagyalias.tests/schema.test.tsis the only thing preventing drift; do not weaken it. - VitePress resolves
publicDirundersrcDir. WithsrcDir: "content", static assets must live indocs/content/public/— files indocs/public/are NOT copied to the site root (logo.svg/favicon.svgonly survive because the config references them). Verified empirically; put new published assets underdocs/content/public/. - Interactive prompting is
@clack/prompts, behind theAskseam.configure.tswraps onlyselectandtext(plus optionalbegin/endframing) so tests replay scripted answers — never drive a terminal in a test, and never import clack outsideconfigure.ts.consola.promptwas tried first and rejected: it has real bugs in practice, and its default cancel strategy resolves with the initial value, which turns a Ctrl+C into a silent "yes to everything". Every clack result must go throughisCanceland throwPromptCancelled.cue initprompts only when stdin AND stdout are TTYs and--yesis absent, so scripted installs cannot block. - Spinners live in the CLI, never in a stage.
src/spinner.tsowns one frame (cliSpinner); the reporter drives it for thepollstage's dead air and parks it viainterjectaround every other printed line. Modules with their own pending phases take thePhaseRunnerseam (upgrade.ts) instead of importing ora, so they stay testable withnoPhase. The spinner disables itself when stdout is not a TTY, which is what keeps CI logs andcue ui's SSE stream unchanged. - Design docs live under
docs/superpowers/which is gitignored on purpose — don't try to commit them or "fix" the .gitignore.
Linting and formatting
- After making code changes, run
bunx oxlint --fix, then runbunx oxfmt. - Before finishing, run
bunx oxlint --deny-warnings --format=agent.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

