dzhng/duet-agent

Pattern-based (fast, regex) and semantic (LLM-evaluated) guardrails compose into a firewall. Every bash command and file write can be checked before execution.

const turnRunner = new TurnRunner({
  guardrails: [
    {
      kind: "pattern",
      rules: [
        { pattern: /production-db/i, action: "warn", reason: "Production database mentioned" },
      ],
    },
    {
      kind: "semantic",
      model: getModel("anthropic", "claude-haiku-4-5"),
      policy: "Never delete production data. Never expose secrets in output.",
    },
  ],
});

TurnRunner can attach to remote Model Context Protocol servers over the streamable-HTTP transport. Pass mcpServers on start and the runner connects, lists each server's tools, and exposes them to the parent and state agents alongside the built-in coding tools. Tool names are namespaced as {server}__{tool} so multiple servers can coexist without collisions.

await turnRunner.start({
  mcpServers: {
    docs: {
      type: "http",
      url: "https://mcp.example.com/docs",
      headers: { "x-api-key": process.env.DOCS_KEY! },
    },
  },
});

Only HTTP MCP is supported today; authentication is intentionally out of scope, so any credentials a server expects must travel in headers. Connection failures are logged and skipped so a single broken server cannot block session setup.

Interrupt behavior comes from the underlying pi agent runtime. A user can send a message while a pi session is running, and the runtime can handle it as an interruption or as a follow-up. duet-agent does not add a second interrupt bus on top.

Sub-agents use the default tools from @earendil-works/pi-coding-agent: read, bash, edit, and write. The turn runner supplies a working directory and can restrict which skills are injected into a state-machine agent state; it does not wrap those tools in a second sandbox abstraction.

npm install --global @duetso/agent
pnpm add --global @duetso/agent
yarn global add @duetso/agent

# Upgrade an existing global install
duet upgrade

The CLI runs on Bun because OpenTUI is Bun-native.

This repo uses Bun for package management, Husky for pre-commit checks, and Docker for functional tests.

bun install
bun run setup        # install/start Docker on macOS or Linux if needed
bun run check-types
bun run lint
bun run eval         # runs live evals inside Docker
bun run test         # runs the test suite inside Docker

Use bun run test and bun run eval, not raw bun test, as the source of truth. File-writing tests and evals run in Docker so focused host runs cannot create .duet, PGlite databases, or home-directory skill fixtures in the checkout.

Paid evaluation infrastructure and its separate verification commands live in the SWE-bench benchmark.

The pre-commit hook runs format, check-types, and lint.

Duet routes every model through one of three gateways — the Duet gateway (DUET_API_KEY), the Vercel AI Gateway (AI_GATEWAY_API_KEY), or OpenRouter (OPENROUTER_API_KEY). If you would rather manage keys yourself, use duet env (see CLI Env Setup below) or set one of those keys in the environment, <workdir>/.env, or ~/.duet/.env. Gateway inference (preferring those credentials in that order) decides which gateway serves each concrete model.

When --model is omitted, duet runs the routed frontier virtual model — see The model router + advisor for how routing and the advisor work. The flags and config:

• --model frontier|balanced|economy selects a routing tier explicitly; any concrete model name pins that model and bypasses routing.
• duet config export writes the routing table to .duet/models.json (routes, efforts, advisor policy, stepTriggers keywords, per-route visionFallbackModelName); /route inspects a live session.
• Override discovery mirrors skills: the nearest .duet/models.json walking up from the working directory wins, with ~/.duet/models.json as the global fallback. Each file is a complete replacement, never a merge.
• It stays out of the way: tiers whose routes all resolve to one identical model+effort never call the classifier.

Use --provider <name> to pin a gateway without picking a model:

duet --provider duet "build a todo app"        # Duet gateway
duet --provider vercel "summarize"             # Vercel AI Gateway
duet --provider openrouter "explain this repo" # OpenRouter

--provider is mutually exclusive with --model / --memory-model. Accepted shorthands: duet, vercel (alias ai-gateway), and openrouter.

export DUET_API_KEY=...

duet "build a REST API with Express"
duet                                                                  # interactive TUI
duet -m opus-4.8 --workdir ./my-project "refactor the auth module"
duet --memory-model sonnet-4.6 "summarize this repo"
duet --system-prompt "Prefer concise answers." "review this repo"
duet --system-prompt-file TEAM.md "review this repo"
duet --no-system-prompt-files "review this repo"
duet --resume session_abc123 --workdir ./my-project
duet skills                                                           # list installed skills
duet memory                                                           # browse durable memory

# Through Vercel AI Gateway
export AI_GATEWAY_API_KEY=...
duet -m opus-4.8 "review this repo"

Model names can be a virtual tier (frontier, balanced, economy — routed per prompt), a versionless family (opus, sonnet, haiku, sol, and others), full provider:modelId syntax, or a versioned shorthand such as opus-4.8 or gpt-5.6-sol. Family names resolve to the latest curated version, while concrete shorthands resolve to the first configured gateway; use full provider:modelId syntax — or --provider <name> — to pin a specific gateway.

In a TTY, duet opens an interactive TUI: live transcript on the left, a right-hand sidebar with four panels, and a textarea at the bottom.

• todos — the runner's current todo list.
• follow-ups — prompts queued behind the active turn (the working-status line also shows the count).
• relays — when a relay (state machine) is active, lists every state with ▶ marking the current one and the terminal status if reached.
• context — token-usage progress bar against the active model's window.

In the input box:

• @<query> opens a file picker; ↑/↓ navigate, Enter / Tab inserts a markdown link like [app.ts](./src/tui/app.ts) (basename label, repo-relative target). The model can then read the file via the read tool.
• /<query> opens a skill picker that inserts /skill-name so the model receives the full SKILL.md inline with its instructions for that turn.
• Enter sends; Shift+Enter queues the message as a follow-up while the agent is running, instead of steering the active turn.
• Esc cancels the current pickers; on its own it interrupts the active turn, or no-ops when idle.
• Ctrl+C is contextual rather than an instant quit: it interrupts the active turn while one is running, clears the composer when it has text, and on an idle empty composer asks for confirmation first ("Press Ctrl+C again or Enter to exit"). Confirming — or closing the terminal — drains through the SessionManager so the local memory database (PGlite) flushes cleanly.

Tool calls render with custom per-tool headers (e.g. $ <command>, read <path> (lines a–b), edit <path> (N edits), [question]). Resumed sessions render history through the same formatters so live and replay match.

Type / in the composer to open the command picker, or send any of these as a message:

• /model <name> — switch the model used for subsequent turns. Accepts virtual tiers and the same family, versioned shorthand, and provider:modelId forms as the --model flag (e.g. /model frontier, /model sonnet, /model duet:openai/gpt-5.6-sol). A concrete name pins the model and suspends routing; a tier resumes it. Unknown shorthands or missing provider credentials surface an error and leave the current model in place. The in-flight turn (if any) keeps the model it started with. /route inspects the live routing state.
• /thinking <level> — switch the thinking level for the next turn. One of minimal, low, medium, high, xhigh. The runner clamps to the active model's supported range at use-time. The in-flight turn (if any) keeps its level.
• /feedback <message> — send free-form feedback to the Duet team.
• /clear — dispose the current session and start a fresh one.
• /copy [last|all|<N>] — copy transcript text to the system clipboard (default: last agent reply).
• /paste, /image <path>, /clear-images — image-attachment helpers, covered in the next section.
• /diag — toggle key and selection event logging when triaging terminal-specific issues.

/model, /thinking, /clear, /paste, /clear-images, and /diag also work anywhere inside a longer prompt. hey can you review this /model sol swaps the model for the very turn that delivers the message; the slash form is stripped from what the agent sees, so the model receives hey can you review this. When the whole prompt is just slash commands, no agent turn runs at all. Commands that take rest-of-line arguments (/feedback, /copy, /image) only fire when they own the whole message.

The inline form also works for the non-TUI one-shot CLI: duet "hey can you review this /model sol" swaps the model and dispatches the stripped prompt to the agent; duet "/model sol" applies the swap and exits without dispatching a turn.

Slash commands are intercepted locally; they never reach the model unless the picker inserts a /skill-name skill reference, in which case the runner expands it into the matching skill's full SKILL.md inline for that turn.

The interactive TUI accepts image attachments (PNG, JPEG, GIF, WebP):

• Cmd+V / Ctrl+V — paste from the clipboard. Requires a kitty-keyboard-aware terminal; falls back to /paste on others.
• /paste — manual clipboard probe. Use this when your terminal swallows Cmd+V (Warp, macOS Terminal.app).
• /image <path> — attach an image from disk by absolute or relative path. Tilde (~/) and file:// URLs are accepted.

/clear-images removes all pending attachments. Attachments cache under ~/.duet/cache/paste/<session-id>/ and cap at 20 MB each. On macOS, clipboard reads use a small Swift program (via swift -e) so promise-backed pasteboards from Chromium apps deliver bytes — install Xcode Command Line Tools with xcode-select --install if you see "clipboard had no readable image."

The same ~/.duet/memory.db the runner reads is scriptable from the CLI. Bare duet memory opens the interactive TUI; adding --json or any filter turns the same invocation into a non-interactive query. Three subcommands cover the write and search paths:

# Filter/query mode — bare array of canonical memory objects
duet memory --json --type reflection --from 2026-06-26
duet memory --json --source user --session sess_abc123     # rows authored by one session

# Recall — hybrid semantic + keyword search, same pipeline as the recall_memory tool
duet memory recall wire byte budget cap                     # positional query
duet memory recall --query "how does the gateway race resolve" --expand
duet memory recall --scope global --session sess_abc123 --json qwiklabs

# Add — write a single user-authored note
duet memory add --priority high --tag billing "Enterprise discounts cap at 20%"
echo "note from a pipe" | duet memory add --source import --session sess_abc123 --json

All three share one canonical memory JSON object (--json), so a consumer parses one shape everywhere:

• Timestamps are ISO 8601 strings (e.g. 2026-07-06T00:00:00.000Z); date-only fields (observedDate, referencedDate) stay YYYY-MM-DD.
• source is a flat string — one of user | agent | system | api | import (system is the training-origin value).
• sessionId is the session that authored an observational row: writable on DB-backed add, filterable on memory/recall, and echoed on DB output (absent on legacy rows and file memories).
• Observational JSON names both ranking axes explicitly: packScore (recency × priority × kind bias) and relevanceScore (query relevance, present only in memory recall). File-store JSON reports its slug and store path instead because those records are inherited context, not ranked recall rows.

Command-specific notes:

• duet memory (query): --json emits a bare array ordered by pack score; --source and --session narrow the set alongside --type, --priority, --from, and --to.
• duet memory recall: query text comes from --query <q> or positional args. --scope session|global requires --session <id> to compare against; all (default) ignores it. --json emits a bare array ordered best-first, each row carrying both packScore and relevanceScore.
• duet memory add: added memories are always note kind. Flagless writes go to the nearest ancestor .agents/memories; pass --db to retain observational-row ranking, embedding, and session attribution. Content comes from positional args or stdin, and empty input is a usage error.

DB-backed memory commands accept --db <absolute-path> and --wait <seconds>. memory add also accepts a single --store; memory recall deliberately rejects stores because file memories are already loaded into agent context. Exit codes are stable for scripting: 0 success, 64 usage or validation error, 75 memory-DB lock-wait budget exhausted, and 1 for anything else.

duet train <folder> launches a sub-agent inside the folder, lets it read whatever is there with its native tools (markdown, CSVs, PDFs, spreadsheets, screenshots, source — anything the agent can open), and produces two artifacts:

• One inherited markdown memory in the nearest ancestor .agents/memories store. Explicit --store selects a different file store; explicit --db retains the legacy high-priority manual-row behavior.
• ~/.duet/train/<memory-id>/ — a hidden archive containing source copies and private provenance. Shareable memory frontmatter references the archive id but never embeds the absolute source folder.

duet train ./snowflake-notes              # writes to the nearest .agents/memories
duet train ./snowflake-notes --slug snow  # custom slug (default: folder basename)
duet train ./snowflake-notes --model opus-4.8
duet train ./snowflake-notes --db /tmp/scratch.db  # write to a throwaway DB instead

Re-running train on the same slug replaces the prior entry and its archive in the selected backend.

Three things to know:

• The current session won't watch the new memory file. It appears in a fresh duet session, or after a programmatic reloadSkills() refreshes disk-backed context.
• Synthesis needs an API key. DUET_API_KEY (recommended), or any of the provider keys covered above.
• The corpus folder's .env is loaded (so a project folder can supply its own provider credentials). Check folders you didn't author before training them.

The CLI also prints the observation content to stdout, so it's pipeable: duet train ./docs | tee notes.txt.

duet login is the recommended setup path. It opens a browser, where you choose the workspace during approval, then writes that workspace's DUET_API_KEY to ~/.duet/.env.

That single DUET_API_KEY is your access token to the Duet AI Gateway: frontier language models (Claude, GPT, Gemini), image generation (GPT Image 2), video generation (Seedance), and the Firecrawl-powered web scraping and search skills, all behind one key.

duet login
duet login --no-browser           # print the auth URL instead of opening a browser

duet env is the manual alternative for users who want direct control over which provider API keys land in the shared env file. Without an action it just prints help. Add an explicit action to create or update the shared env file at ~/.duet/.env:

duet env --import                                    # import .env from cwd
duet env --import ./path/to/.env                     # import a specific env file
duet env --keys                                      # paste provider API keys interactively
duet env --env-file ~/.config/duet/env --keys        # use a custom shared env file
duet --env-file ~/.config/duet/env "review this repo"

The CLI loads <workdir>/.env first, then the shared env file, so project-specific values override shared defaults. Supported keys are DUET_API_KEY, AI_GATEWAY_API_KEY, and OPENROUTER_API_KEY — one per model router.

For local development from a checkout:

bun run cli -- "build a REST API with Express"

start() prepares a session, but it does not run agent work. It prepares the initial TurnState and initializes independent resources concurrently, then initializes the parent pi agent and emits turn_started only when the first prompt can use the fully hydrated memory, skills, routing, and MCP tool set. After that, every turn() call accepts one command: prompt, answer, or wake.

flowchart TD
  Start["start(command)"] --> State["create or resume TurnState"]
  State --> Setup["hydrate concurrently:\nconnected tokens · durable memory\nskills + agent files · MCP servers\nrouting table"]
  Setup --> Parent["initialize parent pi agent"]
  Parent --> Started["emit turn_started"]

  Started --> Command["turn(prompt | answer | wake)"]
  Command --> Active{"active turn\nalready running?"}
  Active -- yes --> Fold["fold prompt/answer into parent agent\nor queue work behind active chain"]
  Fold --> ActiveTerminal["return activeTurnPromise"]

  Active -- no --> Chain["run turn chain"]
  Chain --> Dispatch{"command type"}
  Dispatch -- prompt/answer --> Mode{"state.mode"}
  Dispatch -- wake --> Wake["resume scheduled poll/timer state"]

  Mode -- agent --> ParentRun["run parent pi agent"]
  Mode -- auto or explicit state machine --> Router["parent agent selects next state"]
  Router --> StateRun["run agent, script, poll, timer,\nor terminal state"]
  StateRun --> StateResult{"state result"}
  StateResult -- completed --> Router
  StateResult -- ask --> Terminal
  StateResult -- sleep --> Terminal
  StateResult -- terminal/interrupted --> Terminal
  Wake --> StateRun

  ParentRun --> Observe["observe transcript suffix\nreflect large observation logs\nflush durable memory"]
  Router --> Observe
  Observe --> Queue{"queued commands?"}
  Queue -- yes --> Dispatch
  Queue -- no --> Terminal["emit one terminal event\ncomplete | ask | sleep | interrupted"]
  Terminal --> Snapshot["store latest TurnState in runner"]
  Snapshot --> Next["caller persists snapshot\nand may call turn() again later"]

TurnRunner.turn() is the concurrency boundary. Callers may invoke it repeatedly while work is active; the runner folds active prompt and answer commands back into the active pi agent as steer or follow_up, queues wakes and work it cannot absorb immediately, and emits one terminal event when the whole active work chain is done.

The parent runner transcript stays linear across the lifecycle. State-machine continuations, script results, poll results, and user follow-ups all rejoin the parent agent instead of creating separate conversation branches. Terminal events carry the next TurnState; callers that need process-level durability persist that snapshot and pass it back to a later start({ state }).

TurnRunner owns memory at runtime. It holds a MemoryStore in process, hydrates durable observations from PGlite before the first turn, and subscribes to memory-store events to write future observation changes. After each pi-agent run, the runner observes the latest unobserved transcript suffix, reflects oversized observation logs, emits memory events with generated observation payloads, and waits for durable writes before continuing. Raw conversation messages stay in TurnState.agent.messages; memory persistence stores only derived observations/reflections.

The rendered memory section above the message tail is a frozen pack with two independent sources. Curated memory files discovered from the working directory's project ancestry are pinned first and refreshed only at session start or explicit skills reload. Database-backed memory follows as ranked cross-session observations and the current session's chronological compaction summary; those layers rebuild only at compaction events so ordinary observer writes do not invalidate the prompt cache. File memory never enters database ranking, reflection, usage-bump, or recall paths. The model can still pull non-pinned database facts on demand through the default recall_memory tool, which runs hybrid vector + keyword search with optional query expansion.

import { TurnRunner } from "@duetso/agent";

const turnRunner = new TurnRunner({
  model: "opus-4.8",
  memoryDbPath: false, // Disables observational memory and compaction.
});

By default, both duet (TUI/run) and duet --rpc store durable observations in ~/.duet/memory.db. Override the path with --db <path> (the flag is accepted in both modes and is ignored when --incognito is also set), or run with --incognito (or -i) to disable both observational database memory and curated file memory for that session. duet --rpc bypasses SessionManager, so it has no session of its own; pass duet --rpc --session <id> to attribute every observation written during the RPC process to a caller-owned session (one RPC process is one logical session). Omit it to leave those writes unattributed. Programmatic callers can control the two sources independently with memoryDbPath and memoryStores. The CLI's SessionManager is a convenience layer that stores session snapshots under ~/.duet/sessions, but the runner owns memory hydration, pi-turn observation/reflection, compaction, and observation persistence.

[!WARNING] We strongly recommend running with a memoryDbPath (the default). Compaction is implemented as part of the observational memory pipeline: raw transcript content is replaced by observations/reflections that the observer and reflector write to the durable store. Without a database, the runner skips that pipeline entirely — there is no compaction, the transcript grows unbounded against the raw model context window, and long sessions will eventually hit a provider context-length error. memoryDbPath: false is appropriate for short-lived scripts, tests, and incognito runs that stay well under the model window.

Resume directly from saved state:

await turnRunner.start({ state: savedState });

const terminal = await turnRunner.turn({
  type: "prompt",
  message: "Continue the previous goal",
  behavior: "follow_up",
});

Resume continues turn runner session state, not an in-flight model/tool call. Any in_progress todo is retried from pending.

Observational memory thresholds (tuned for modern 200k-token windows):

• Raw messages are observed after each pi-agent run; 100_000 tokens controls when old raw transcript context is replaced.
• Observation logs are reflected around 60_000 tokens, targeting about 40_000 tokens after reflection.
• Raw-tail retention keeps about 30_000 exact message tokens after context replacement activates.
• Observation context is injected as reminder messages; replacing raw context with observations/reflections is the compaction path.

As a final safety net for on-disk state, TurnRunner also caps the size of every TurnState that leaves the runner via snapshotState — every emitted event, terminal payload, and getState() return is trimmed before persistence sees it. Eviction drops the oldest agent messages first while keeping tool-call/result pairs intact, so state.json cannot grow unbounded even if memory compaction has already run many times. This is on by default at a 100 MB ceiling; override or disable via autoStateCompaction on TurnRunnerConfig (true → default ceiling, { maxBytes } → custom, false → off).