Open-source AI coding agent · built on pi

It reads what you write down.

Terminev is a coding agent that runs in your terminal and remembers. Every session ends by handing a background engine a note. Overnight that engine turns notes into project memory, and refuses to keep any of it until a fresh sandbox has proven it twice.

install · latest stable release
curl -fsSL https://terminev.xyz/install.sh | sh

refuses root, verified download, no git or bun · sandbox: Seatbelt

then: terminev setupterminev · CLI only

orhave your agent install it
paste this into the agent you already use

Install the open-source coding agent Terminev for me with the full stack: clone https://github.com/kanishka-namdeo/Terminev, run `bun run agent:install` inside the clone, then run `terminev setup` to connect a model and `bun run agent:start` to boot the engine. Finish by reporting what `terminev doctor` says.

sourceFull install — clone it, point it at a model, run it.
01git clone https://github.com/kanishka-namdeo/Terminev.git
02cd Terminev
03bun run agent:install # deps + pi build + .env
04terminev setup # connect any model
05bun run agent:start # engine :3030 + bridge :3031
06terminev # first session — notes queue for the engine

full stack the chip above installs the terminal agent only; this lane adds the engine, llm-bridge and learning stack. As one command: curl -fsSL https://terminev.xyz/install.sh | sh -s -- --source (macOS/Linux) or irm https://terminev.xyz/install.ps1 -OutFile install.ps1; .\install.ps1 -Source (Windows).

Full install: bun ≥ 1.2 · an endpoint (any OpenAI-compatible base URL + key; background learning can also run on a local llama.cpp or Ollama lane, keyless and offline) · Windows, macOS or Linux — same commands. OS sandbox: bubblewrap (Linux), Seatbelt (macOS); native Windows runs the in-process jail.

clithe whole command surface
  • terminevinteractive session in the current project
  • terminev "fix the failing tests"start with a prompt
  • terminev -p "explain the build error"one-shot headless, pipes to less
  • terminev --plan "add auth"read-only plan mode, approve before executing
  • terminev --goal "make the build green"durable goal — completion needs cited evidence
  • terminev routines create --every '1d at 09:00' --title 'brief'recurring runs — cron, every, after; read-only by default
  • terminev setupprovider wizard, or --provider/--api-key/--model
  • terminev modelsconfigured models plus what the bridge serves
  • terminev doctorendpoint, keys, upstream and memory, end to end
  • terminev memoryprint the effective four-tier stack
  • terminev initscaffold this project's .terminev/memory files
  • terminev mcp add playwright npx @playwright/mcp@latestconnect any MCP server — its tools join every session
  • terminev note "flaky auth spec"hand AutoDream a note directly
  • terminev updateself-update to the newest release — check, pin, roll back

Every session also ships session tools — todo, note, task, web_search + webfetch, fetch_url and lsp — and any MCP server you configure joins it. Each one is catalogued, with its capture and its receipts, in the capability dex below. Slash commands: /plan, /review, /goal, /undo, /receipts, /mcp — plus /todos, /note, /agents, /learning, /lsp.

the full usage reference
  • MIT licensed
  • no telemetry, no account
  • runs on your machine
  • any OpenAI-compatible model
  • OS-level sandbox
  • receipts in the repo
Terminev

Terminev

Self-improving coding agent

terminev — session
0.0s / 4.7s

Transcript of an terminev session:

  1. Command: terminev "why does checkout.spec flake in CI only?"
  2. ✓ preflight bridge :3031 · kimi-k2.5 · 412ms
  3. ✓ memory policy → project v6 → user → local
  4. hooks SessionStart · PostToolUse · Stop
  5. read tests/checkout.spec.ts
  6. read src/checkout.ts
  7. grep sharedCartFixture — 3 files
  8. ▸ the fixture is module-level state, so beforeEach inherits
  9. the previous test's cart. Build it inside the hook.
  10. hook PreToolUse deny refusing rm on filesystem root
  11. edit src/checkout.spec.ts (+3 −1)
  12. verify 14/14 passing · 2.1s
  13. Divider
  14. note queued → engine :3030
  15. "Terminal session in ~/code/checkout (3 min): 1 prompt(s),
  16. 14 tool call(s). The cart fixture was module-level state and
  17. leaked between tests — build it inside beforeEach."
  18. outbox ~/.terminev/notes/outbox/1757…-checkout.md

The session ends by queueing a note in ~/.terminev/notes/outbox for the engine's AutoDream job to consolidate.

a real session: the memory banner, hook log line and note template are the formats Terminev actually writes

The learning loop

Most agents forget. This one has to prove it remembered.

Three steps, run continuously by the engine while you work — each tab shows the file that step actually writes.

The session ends by writing something down.

Every terminal session is captured on the way out as a note in a fixed template, delivered to the engine. If the engine is down the note waits in an outbox and syncs when it comes back — so the learning loop never depends on the loop being up.

~/.terminev/notes/outbox/1757...-checkout.md
Terminal session outcome in ~/code/checkout:
Final outcome: all 14 checkout specs green.

Session metadata (counts and duration only — data, not knowledge): 1 prompt(s),
14 tool call(s) (read, grep, edit, bash), 3 min.

The literal note template — outcome first (that is the knowledge), counts and duration demoted to a labeled data-only metadata line (a phrasing the injection guard can never trip on). A subagent session gets a [subagent] tag in the same header, so the engine can tell where a note came from.

The terminal agent

pi's TUI in your real project directory, with the memory stack already loaded. Alone: a good coding agent that forgets everything at midnight.

  • terminev
  • terminev --plan
  • terminev doctor

The engine behind it

Sandboxed harness cycles and AutoDream consolidation, on a clock instead of in your session. It never touches your editor.

  • harness-cycle 10m
  • auto-dream 10m
  • note-sync 5m
  • task-mint 30m
  • sandbox-gc 15m
  • db-retention 1440m
  • watch-scan 2m
  • on improvement:shipped
  • on run:finished
the odd powernotes → memory → a better next session

The capability dex

Every capability, catalogued and filmed.

The session tools, the engine mechanisms and the filmed surfaces — one numbered spine. Walk the list, type to filter, play a cry, watch the capture. 9 of 20 carry a capture — 9 movies, 1 still set, 11 pending. Nothing here was filmed by hand.

20/20

↑ ↓ walk the list · type to filter · esc clears · filmed pending · captures come only from the harness in scripts/tui-capture/, never by hand

№ 003 · the splitting form

Task

sessionjoins every session
terminev — Task
reel

One coil, many errands: it balances the glowing job on its tail until a fresh mind comes to take it — and it can split one loose in the background, steer it mid-run, take its questions and wake it again by name. What walks back is typed, and it cleaned up its worktree on the way.

in practice

Subagents with a fresh context — typed replies via output_schema, per-child git worktree isolation, a completion guard that fails the silent no-op, and a BLOCKED lane for honest refusals.

The async fleet: background spawns whose results steer back as new turns, mid-run steering and ask_question through task_control, resume-by-name from a persisted registry, and a live fleet widget — no terminal multiplexer, native on every OS.

weakness
one context juggling ten jobs
entry 3 of 20

№ 003 — Task · reel 1/2 · subagent · playing

The 9 movies and the 1 still set were captured 2026-10-20 by the harness from real terminev sessions at 128 × 36 and audited still by still; each poster is that scenario's first audited still. 11 entries have no capture, and the page says so instead of making media up.

/splitthe display commands (11) — the split-view mode's keyboard surface
  • /splittoggle all panels; off restores pi's bare layout
  • /split-thinkingtoggle the thinking panel
  • /split-toolstoggle the tools panel
  • /filestoggle the files panel (dock or overlay)
  • /split-difftoggle the dock's edit-diff subpanel
  • /split-tools-viewtool panel: compact or full detail
  • /split-heighttop band height in rows (6-40)
  • /split-tools-widthtools panel width, % of the band (20-60)
  • /split-dividerdivider between answers: rule or space
  • /split-trim-responsetranscript: full or responses only
  • /split-savesave this layout as the startup defaults

Toggles last the session. /split-save writes the layout to ~/.terminev/agent/ui-panels.json and new windows start from it. The response-only mode keeps the thinking and tool traffic in the band and dock and prints just the conversation in the transcript. The band and dock compose in fullscreen mode, the default for new installs; in regular mode /files falls back to an overlay.

Mission control

What the running engine looks like.

terminev dashboard — overview
terminev dashboard — the Overview screen with pass rate, shipped improvements, dream count and the live activity rail
The Overview screen: KPI band, task table and the live activity rail.
terminev dashboard — memory
terminev dashboard — the Memory screen with the four engine tiers, per-project memories, injection budget and version history
The Memory screen: tiers, budget meter, provenance.
terminev — session + /dashboard
The embedded /dashboard mount inside a live terminev session — the same screens, Esc-Esc returns to the editor
Embedded: /dashboard inside a live session.

Stills from real terminev dashboard sessions against a running engine — runs, dreams, notes and hook decisions, streamed over SSE from :3030. Every screen works read-only until you spend tokens on a button ( bun run agent:start, then terminev dashboard).

Twelve surfaces · each drives something real

  • Overviewpass rate, dreams, memory version
  • Memoryfour tiers, one-key rollback
  • DreamsAutoDream sessions
  • Notesthe raw learning material
  • Skillswhat the agent shipped itself
  • Learning Labharness cycles, transcripts
  • Hooksevery allow, deny, augment
  • Routerthe background jobs
  • Gatewaytokens, latency, per-model
  • Routinesscheduled recurring runs — cron, every, after
  • Web Cachethe persistent web results store
  • Embedded/dashboard inside a live session
Install it and run terminev dashboard
Three TUI addons · every setting is user configOne file holds every setting, ~/.terminev/agent/addons.json: 21 user-tunable keys across the three — /addons is the live configurator.

The knobs range from the todo panel's line budget and the advisor's review cadence to the tool descriptions the model reads. Native TypeScript over pi-tui with no native modules, so the same dialogs run on Windows, macOS and Linux.

receipts:addons/config.tsaddons/index.ts

  • ask_user_question

    Up to four structured questions in one tabbed dialog, a free-text row on every question, a submit-review tab before anything is sent. The session blocks until you answer.

    ask-user-question.ts
  • todo

    A four-state task machine (pending, in_progress, completed, deleted) with blockedBy dependencies that reject cycles, a live panel above the editor, and a /todos command.

    todo.ts
  • advisor

    A second model watches the session and sends terse advice mid-run: nits queue as asides, concerns and blockers steer immediately. Read-only verification tools, an emission guard against noise, off by default.

    advisor.ts

Proof

Receipts, not promises.

Every number is generated from the receipts and re-checked in CI — including the ones where memory made things worse.

52%

LiveCodeBench v6 pass@1

post-cutoff problems, kimi-k2.5

98.1%

edit accuracy

106-fixture oh-my-pi benchmark

−35%

warm wall time

repeat tasks, kimi-k2.5

0/50

attacker rules shipped

MPBench-adapted corpus, 0 planted

LiveCodeBench v6 — the contamination-aware headline

50-problem stratified subset of LiveCodeBench's release_v6 increment · contests 2025-01-04 → 2025-04-06 · after every model's cutoff · official LCB prompt + grader · greedy pass@1 · four models: the Dashscope trio (2026-10-17) + agnes-3.0-flash on the Agnes AI upstream (2026-10-21) · receipts under benchmarks/livecodebench/results/

kimi-k2.552.0
qwen3.7-plus38.0
qwen3.6-plus36.0
agnes-3.0-flash28.0

Every problem was published after these models' training cutoffs. Easy sweeps for three of four (13/13, 12/13, 12/13); hard is where it ends (4/23, 1/23, 1/23, 0/23). no_code is the honest failure mode: reasoning past the pinned 4096-token budget gets cut off before the code fence closes — 15/26/27/35 of 50, reported as measured, not filtered.

benchmarks/livecodebench/results/

Edit accuracy

oh-my-pi typescript-edit-benchmark · 106 fixtures · byte-exact scoring · full Terminev agent in the loop · Dashscope trio: 2026-10-17 fresh-checkout rerun · agnes-3.0-flash: 2026-10-21 Agnes AI upstream rerun (97.2% at n=1, inside the trio's band)

kimi-k2.598.1
qwen3.7-plus96.2
qwen3.6-plus94.3
agnes-3.0-flash97.2

head-to-head against the oh-my-pi agent itself, same 106 fixtures, 3 runs per task: identical best-of-3 scores on every model — and 2.4–5.4× fewer input tokens per task.

Memory lift, cold vs warm

n=10 · single run per phasebenchmarks/selfimprove/results/

Each model solved the same 10-task Python Exercism set cold (fresh project, fresh memory), then warm: a brand-new workspace carrying only the dreamed memory from its cold pass. Bars are input tokens, normalized per model; the scale runs to 300% — recomputed from these receipts, so the models that spent more widen the axis and are never cropped.

coldwarm · fewer input tokenswarm · more input tokens
qwen3.6-plus−23.7% in25s → 23s −8.0%pass 10/10 → 10/10
cold
401,445
warm
306,218
kimi-k2.5+21.8% in37s → 24s −35.1%pass 10/10 → 10/10
cold
34,553
warm
42,075
qwen3.7-plus+23.2% in24s → 25s +4.2%pass 10/10 → 10/10
cold
64,853
warm
79,886
agnes-3.0-flash+197.1% in106s → 79s −25.5%pass 9/10 → 9/10
cold
107,583
warm
319,659

Pass-rate lift is 0pp across all four models: three of four spent more input tokens with memory in the loop — agnes-3.0-flash most of all (+197%, the dreamed user-tier memory injected into every warm session) while still finishing 26% faster — and kimi-k2.5 finished 35% faster; qwen3.6-plus took both wins. On tasks the model can already solve, memory buys efficiency, not correctness.

Negative controls, published as-is

v1 (thin session notes only): −25.6% input, 64s → 34s warm, with an unchanged memory file — that saving is upstream prompt caching, not memory, and v1 is kept as the control arm that isolates the confound. v3 (six sequential sessions, one evolving repo, real dreams): 6/6 with memory, 6/6 without, 6/6 with wrong-domain memory — learned memory cost +36% billed input tokens, irrelevant memory +30% and bought nothing. The memory system itself now has a live suite — injection proven by a unique marker in the captured upstream request, real dream + canary + rollback roundtrips, and a ten-variant poisoning corpus: every adversarial note flagged at the input layer, 0/10 attacker rules planted into dreamed memory, 0 shipped — receipts in benchmarks/memory-eval/results/.

HumanEval+

official evalplus CLI · 164 problems · greedy pass@1 · 2026-10-21 rerun (per-model runs)

kimi-k2.593.9
qwen3.6-plus93.3
qwen3.7-plus92.7
agnes-3.0-flash89.0

predates these models, so it cannot separate ability from memorization — LiveCodeBench above is the headline for exactly that reason.

Aider polyglot subset

50 exercises · 6 languages · Aider's 2-attempt protocol · pass@2

qwen3.6-plus96 @96
qwen3.7-plus96 @96
kimi-k2.594 @94
agnes-3.0-flash96 @90

first published polyglot numbers for the Dashscope trio (2026-10-17 rerun reproduces the committed run exactly) · agnes-3.0-flash row from the 2026-10-21 Agnes AI campaign: 90% @1 / 96% @2

Long-horizon refactor

one hard multi-file contract change, 11-module TypeScript app · n=1 · scored on the file diff

kimi-k2.543.5k in
qwen3.7-plus62.6k in
qwen3.6-plus1205k in
agnes-3.0-flash62.0k in

all four solved it — agnes-3.0-flash left the greenest as-is suite (42/0) — and the separation is cost: qwen3.6-plus spent 1.2M input tokens with zero cache reads (28× kimi), while agnes-3.0-flash rode 1.07M of cache reads, the strongest prompt-reuse profile measured on this track. receipts

The regression layer below the loop

three suites · every push

A self-improving agent regresses its own harness first: a bad memory ship looks exactly like a better model. The loop sits on a locked suite that must stay green while everything above it evolves — anti-tamper scoring (tests restored to pristine state before scoring), pinned datasets and harness versions, official harnesses only, per-task JSONL receipts under benchmarks/.

dashboard

src/**/__tests__/*.test.tsx

bun run test:unit

llm-bridge

mini-services/llm-bridge/pure.test.ts

bun test pure.test.ts

engine

pi-repo/packages/self-learning/test

bun test test/

not measured here — SWE-bench Verified and Terminal-Bench 2.0 are quoted from vendor reports, never our own runs. The one eval that scores zero (our extension-authoring eval, 0.0 for every model) sits beside the gates in Integrity.

The alphabet

The name is a pun you have to read twice.

unown — the Symbol Pokémon: a flat black letter with one eye, alive since 1999, found stuck to walls in ruins. Twenty-six letter forms to start, with ! and ? arriving in 2004; the 28 below are ours, drawn from scratch as inline SVG — no font file, no image sprite — and each one decodes twice: the lore it borrows, and the real mechanism it stands for here.

As of Legends: Z-A there is no Pokédex entry for it at all.

Availability — one of twenty-eight; the rest are in the wall

hover or focus to decode · click to pin it and rain the letter · psst, try ↑↑↓↓←→←→ba

form 21 / 28 · U

U

form 21 / 28

Its name is the word “unknown” with the spelling knocked about. Its Japanese name is simply Terminev.
PokémonDB · Bulbapedia

in terminev

Unknown. Point Terminev at any endpoint you are allowed to use.

10 provider tiles on the model band

Every line under in terminev describes something that actually runs in this repository. Short quotations of game text appear for commentary, with the source named on each one; no sprite, card, logo or audio from any Pokémon release is bundled, linked or reproduced. An independent open-source project — not affiliated with, endorsed by or sponsored by Nintendo, Game Freak, Creatures Inc. or The Pokémon Company. Pokémon and Terminev are trademarks of their respective owners.

FAQ

The skeptic's questions.

Including the one that decides installs: will it rewrite my tests to make them pass.

Changelog

What has been added, and when.

231 entries so far, read out of CHANGELOG.md, the same file terminev changelog prints in your terminal. Dates come from release headings, titles from the bullets under them, so nothing on this rail was written for the page.
  1. UNCUT

    no tag yet

    1 change · 3 fixes · 1 alter agent behavior

    • the built-in agents' model fields were Dashscope relics — two no-op overrides dropped…

    CHANGELOG.md

  2. v0.0.4

    latest

    19 additions · 5 changes · 1 removal · 24 fixes · 8 alter agent behavior

    • landing: a section menu below lg — the phone visitor gets the seven anchors back
    • Routines v5 — reliability: failed-run retries, chained routines, engine hygiene (env hot-reload, log rotation)
    • Standing orders + /promote — durable authority for unattended runs (OpenClaw's convention, adapted)
    • Repo map — the graph-ranked symbol map (aider's repomap, ported to Bun on web-tree-sitter)
    • Routines v4 — monitoring + delivery policies: active-hours, idle-only, result webhooks, slot jitter

    v0.0.4 release+22 more

  3. v0.0.3

    8 additions · 7 fixes · 13 alter agent behavior

    • onboarding 2.0 — the Hermes-patterned first run and setup wizard (masked keys, existing-key states…
    • clearProviderKey — remove every local trace of a provider key
    • benchmarks/transfer-bench — the cross-task memory-transfer benchmark (induce-on-A/test-on-B)
    • a running engine job is visible from the terminal
    • the Learning Lab shows live counters for an in-flight run

    v0.0.3 release+16 more

  4. v0.0.2

    5 additions · 3 changes · 10 fixes

    • a verified standalone binary install lane — --binary on POSIX, -Binary on Windows
    • the update path now checks a per-OS release manifest and nudges without nagging
    • terminev update and terminev uninstall are mode-aware
    • releases now carry self-describing archives and a verifiable 13-asset payload
    • the 2026-10-21 agnes-3.0-flash benchmark campaign — every track re-run on a new upstream, all receipts committed

    v0.0.2 release

  5. v0.0.1

    54 additions · 7 changes · 2 removals · 53 fixes · 8 alter agent behavior

    • a cloned repo can no longer masquerade as AutoDream: provenance honesty, an injection-time scan…
    • the engine reports its build, the agent compares, and every surface says the same fix: terminev engine restart
    • bounded data growth: the db-retention job prunes operational telemetry past its window; precious data is…
    • the engine API is authenticated now: a per-boot bearer token, Host validation…
    • the files dock graduates by tier (R5)

    v0.0.1 release+56 more

Newest on the left; the trail of cut releases recedes to the right. Scroll it sideways, or use ◀ ▶.

Where to start

One afternoon, and then it starts remembering.

Clone it, run one session, and come back tomorrow with memory that already knows what you told it. Nothing to sign up for. If it is not useful, you have lost an afternoon and gained a very opinionated terminal agent.
7/9

UNKNOWN

If a letter is missing from your keyboard, ! and ? always work.