This is the master feature catalog: one entry per capability, each with where it lives, how it's used, and the tip-worthy phrasing. It exists to be mined — a trivial LLM call over this document (plus the user's usage profile from the notebook/journal) can generate the one contextual hint worth showing while work runs: surface features they haven't touched, deepen ones they use shallowly. Keep entries self-contained; a tip generator should be able to lift any single entry without context.
Format per entry — What · Where · How · Tip seed (a one-line hint a user would actually thank you for).
What: There are no mode commands. Plain language becomes an answer, a reflex, a task, a project, or an automation based on the shape of the ask — scale is read from structure, duration from temporal language. Where: the chat input, always. How: "open that file" → instant reflex; "fix the flaky test" → task; "every morning at 9, check the open PRs" → an automation's card. Tip seed: You never need to tell codeaf how big a job is — say what you want; it decides ceremony, and misreads are corrected by just saying so.
What: Four ceremony rungs: answer (no work), reflex (one journaled micro-leaf, no planner, 1/8 budget), task (compiled), project (subtree). Reversibility, not size, licenses a reflex; overruns promote upward, never silently down. Where: automatic in chat. Tip seed: Small asks ("rename this", "open that") don't build task ceremony — they run as reflexes and still leave a journal trail.
What: Cancel, amend, pause, or redirect running/planned nodes conversationally; the head resolves which node you mean, asks back with options only when ambiguous, and gates consequential surgery behind a confirm question. Where: chat, any time work is on the graph. How: "cancel the audio job", "stop that test run", "make it check only the api package". Tip seed: You can redirect running work by talking about it — no need to find an id or a kill switch.
What: When codeaf needs you, it asks with structured components:
choose (vertical ▸ 1 … rows with dim hints), confirm (▸ 1 yes · ▸ 2 no, enter accepts the marked default), text (a dim answering: <prompt>
line above the input). Number keys, arrows+enter, click, or free text all
answer; typing your own words always wins.
Where: in the thread and on job cards.
Tip seed: Press the option's number — or ignore the options entirely
and type what you actually want; free text always beats the menu.
What: A job waiting >2 minutes on an answer promotes its card to the
dock's top slot with a violet ?, and the header tasks button carries a
violet dot while anything anywhere is waiting.
Where: dock strip + header, even with the rail closed.
Tip seed: A violet dot on ⟨tasks⟩ means something is waiting on you —
click it to jump straight to the question.
What: Mic in the input bar (alt+v or click). While you talk: breathing glyph, live 8-bar waveform, elapsed time, and your words appearing as faint provisional text — cut at natural pauses, transcribed while you keep speaking. Stop → one full-clip pass replaces it with final, editable text, cursor at the end. Where: right edge of the input bar; alt+v toggles, esc discards. How: whatever you had typed stays — voice appends to your draft, in every path including cancel and failure. Tip seed: alt+v talks; your typed draft is never lost — voice adds to it, and esc discards only the voice.
What: Drag an image or a .pdf/.docx/.pptx into the terminal — the
path becomes a dim ⌾ name.png ⟨×⟩ (or ▤) chip above the input. Sending
copies the file into codeaf's own store, so the durable thread holds a copy
rather than a pointer at yours: a retry next week and a follow-up tomorrow
read exactly what you attached even after you have moved or deleted it.
Images ride to the talk model when it has vision, and are staged into the
job's workspace either way, so a worker can look with the vision model — and
when nothing can see, the answer says so.
Where: input bar; ⟨×⟩ or backspace-on-empty removes.
Tip seed: Drag a screenshot straight into the chat — attaching copies it,
so tidying your Downloads folder never breaks a job.
What: A deliverable's path prints in full and renders as a link your
terminal opens. y copies the focused answer, Y copies the file it
produced, /open hands that file to your machine's opener. The copy rides
the terminal's own clipboard, so it works over ssh.
Where: thread; the focused answer, or the last one.
Tip seed: y copies the answer, Y copies its file — even over ssh.
What: generate_image, speak (TTS), generate_music,
generate_video, and view_image are graph tools available to every
leaf — chat reflexes and headless runs alike. Artifacts land in the task
workspace under media/ with readable names and render as one clickable
line (⌾ image, ♪ audio, ▶ video) that opens in your OS viewer.
Where: any task; just ask ("make a diagram of this", "generate an
intro jingle").
Tip seed: Ask any task for a diagram, a voiceover, a jingle, or a
clip — media generation is a tool every job already has.
What: Standing slots: talk, work, plan, voice (transcription), image,
speech, music, video, boost. Defaults resolve against a live catalog
(krea-2-medium-turbo images, fish-audio/s1 speech, qwen3-asr-flash
transcription, lyria-3-pro-preview music, seedance-2.0-mini video) and degrade
gracefully if a slug disappears. Each slot's picker only lists models
that can actually do that job.
Where: click any ⌄ model name in the header → type-to-search
dropdown; env overrides (CODEAF_IMAGE_MODEL, …) for headless.
Tip seed: Click a model name in the header to change it — the list is
pre-filtered to models capable of that slot's job, so you can't pick wrong.
What: Two roles inside every task: the plan model structures (task
graph, replans after a landed result, per-leaf contracts, ruler
recalibration, the delivery gate) and the work model executes the
leaves. The plan slot is empty by default and follows the work model
live — one model does both until you split them. A change lands on the
very next planning call; the sizing ruler stays keyed to the work model,
because it measures the executor.
Where: chat: plan row in the model palette / settings sheet
(pick "follow work" to rejoin). Headless: CODEAF_PLAN_MODEL, or per
run codeaf plan|revise|run --model <work> --plan-model <plan>.
Tip seed: Put a frontier model on plan and a flash-tier model on
work — the graph, the replans, and the gate get the judgment while the
leaves stay cheap.
What: A reminder ("remind me at 6 to leave"), scheduled work ("every
Monday at 9, draft the weekly update") or a watch ("tell me when CI on main
goes red") is recognized from what the sentence is, and comes back as a
card: the schedule in words and exactly, what a watch looks at and the
condition it is held to, the line or the brief, where work runs, and what
one run may spend. Nothing is saved until you answer 1.
Where: chat; or typed exactly with /automations add ….
Tip seed: "Remind me Friday at 3" just works — the card shows exactly
when, and nothing is saved until you say yes.
What: Automations run while a codeaf window is open, in one clock
process every window shares. Anything that fell due while it was closed
runs once when it opens, marked late. A run's result is one dim line in
the conversation that made it — the model is not woken — and a desktop
notification.
Where: automatic; /automations lists them.
Tip seed: A watch on CI tells you when it goes red and then stays
quiet while it stays red.
What: /automations shows each automation's kind, schedule, next run
and last result; enter opens its history — every run, how late, what it
came to and what it cost — and enter on a run opens its transcript. →
shows the row's keys: run now, pause, edit, delete, open where it was asked.
Where: /automations.
Tip seed: Wondering what a watch has been doing? Its history is one
key deep, costs included.
What: "Always run the tests before a commit" has no moment and nothing
to run: it is a memory marked always, in front of every conversation and
task from then on. /always <text> keeps one; /always lists them.
Where: chat, /always, the memory place.
Tip seed: A rule you keep repeating can be said once with /always.
What: The only budget is dollars — $20/day default. No token caps, no
turn caps that kill work: a task stops for done, or for your word. At
the ceiling, work pauses and asks; a raise is a journaled event.
Where: /budget shows today (spent $3.40 of $20 · resets midnight); /budget 50 raises today; /budget default 35 persists;
/budget unlimited today uncaps the day. Header shows the running cost.
Headless: CODEAF_DAILY_BUDGET, --yes-spend to preauthorize.
Tip seed: Nothing ever dies from a token limit — if the daily
dollars run out, work pauses and asks; /budget 50 resumes it.
What: Image/speech/music/video generation and transcription all draw admission from the same daily rail and record real cost from the provider's usage data. Tip seed: One number governs everything codeaf spends today — check it any time with /budget.
What: Preferences, quirks, lessons, and facts are captured from every
stage of work, consolidated with evidence links, superseded on
contradiction, aged, and quarantined when poisoned (with injection
attribution). Wrong beliefs are correctable: "that's wrong, retract it."
Where: automatic; codeaf notebook inspects; retract works in chat.
Tip seed: If codeaf keeps repeating a wrong assumption, tell it to
retract that — beliefs are journaled and die on command.
What: When work reveals a repeatable procedure, it becomes a candidate skill; promotion requires the skill's check script to actually pass (execution-gated), then it's delivered to future leaves via PATH + retrieval. Nothing is hard-coded — capability emerges from use. Tip seed: Scripts codeaf writes twice tend to become tools it owns — your recurring workflows are being quietly compiled into capability.
What: When two approaches compete and evidence is thin, the disagreement is stored as an unsettled pair; future work runs trials against it and settles it mechanically, with provenance. Tip seed: codeaf doesn't argue with itself twice — unresolved approach debates become experiments the next relevant job runs.
What: Each work scope accumulates a delta-updated playbook (never wholesale rewritten) of what works there, composed into contracts for future jobs in that scope. Tip seed: The tenth job in a repo starts smarter than the first — scopes carry earned playbooks.
What: Model capability is measured per work-shape (Rasch ratings) from verified outcomes only; planning cascades cheap→capable; leaf execution pins openers by measured fit. Mispredictions feed a surprise ledger the retrospective attends to first. Tip seed: You don't pick models per task — measured history routes each job shape to the cheapest model that verifiably handles it.
What: Full-text recall over verbatim intents, summaries, and fold digests; executors can pull relevant history mid-task; the head answers "have we done this before?" from the journal. Tip seed: Ask "how did we solve this last time?" — the graph is permanent and searchable, including packed history.
What: A background reflection packs settled jobs into territories (folds of folds), audits beliefs, and updates per-model self-knowledge — attending first to whatever surprised it. Tip seed: Old jobs get packed into territories — the rail stays calm at any history size, and nothing is deleted, only folded.
What: Open chat after a real absence and the first thing in the thread is one collapsed card: "While you were away — N things done, a question, $X." Enter unfolds slim rows (done, failed, facts learned, spend), each anchored to durable provenance. Short breaks stay silent; nothing happened means nothing appears. Where: automatic on session open, after an absence of 4h or more. Tip seed: You don't owe the scrollback anything — the arrival fold is the complete account of what happened while you were gone.
What: Non-blocking questions accumulate instead of interrupting: a
dock row with a ? glyph, count-collapsed, surfaced at most one per
natural moment (arrival, after a delivery). Answering happens inline in
chat; questions whose originating job settled another way expire with a
journaled reason.
Where: the dock; answers route through normal chat.
Tip seed: codeaf is probably holding questions for you — the ? row
in the dock is its saved-up 1:1 list, never a popup.
What: Every dollar spent on itself (retrospectives, folds) produces a
journaled receipt: what it tried, what it cost, what was learned (facts,
skills, surprise delta) — or explicitly "nothing." Two consecutive
nothing-receipts on an inquiry line auto-retire it, with the reason
journaled as self-origin evidence.
Where: codeaf why self prints today's receipts; surfaces read
SelfSpendToday as one number.
Tip seed: Ask codeaf why self — every cent it spent on itself comes
with a receipt saying what it learned, and freeloading inquiries fire
themselves.
What: From the surprise ledger, failure rates, installed skills, and
territories, every scope is classified strong / frontier (the 25–75%
learnable band) / weak / stale. The head answers "what are you good at?"
from this evidence.
Where: codeaf competence for the calm rows; in chat, just ask.
Tip seed: "What are you actually good at now?" gets a measured answer
— strong scopes, the learning frontier, and where it still struggles.
What: The header's left side is the whole map — thread (the conversation,
home), board (live jobs and the graph — the old tasks rail promoted), self
(the employee's file: today's receipts, the competence map and newest
beliefs). Attention dots light per place from that place's own sources; esc
always walks home to thread.
Where: click the words, or alt+1 / alt+2 / alt+3 (alt+g and ⟨tasks⟩ still
open the board); /self.
Tip seed: Wondering what it's learned or earned lately? alt+3 opens its
file — receipts, competence and beliefs, one calm column.
What: One dim line in the rail (and dock hint) while the resident works on itself: "practicing: goreleaser edge cases · $0.31 on myself today", with a brief "learned: …" clause when a round pays off. Silence when idle. Self-work never masquerades as your job cards, and the header spend meter carries a "· N¢ self" suffix whenever it spent on itself today. Where: automatic; the rail and the header meter. Tip seed: The dim line under the rail is the sound of it studying — and every cent it spends on itself shows up labelled "self" in the meter.
What: Work lives as cards with four states (compiling, working, question, settled); active cards dock above the input, settle at their birth position in the thread, and expand through a disclosure ladder into the rail's flight recorder. Tip seed: A settled card sits where you asked for it — scroll back to where the conversation was, not to a log.
What: Every affordance is explicit (no hover exists): ▸/▾ expand,
⋯ more, ⟨×⟩ dismiss, ⌄ opens a picker. Focus zones cycle
input→dock→thread→rail; arrows+enter act; esc backs out one rung; alt+g
or header ⟨tasks ▸⟩ toggles the rail; slash commands complete inline.
Tip seed: If you see ▸ ▾ ⋯ ⟨×⟩ ⌄ — it's clickable, and the keyboard
path always exists (arrows, enter, esc, alt+g, alt+v).
What: Replies stream token-by-token; running work shimmers
left-to-right; plans stream while forming; file paths are clickable
(OSC8); tool calls render with kind glyph + accent name, failures rose
✗, outputs guttered.
Tip seed: The shimmer isn't decoration — something breathing means
something is actually running; click ⟨tasks⟩ to see exactly what.
What: Close the terminal mid-run and nothing haunts: on reopen, orphaned claims release, recovered work resumes with a one-line notice, and the head's snapshot always shows live work first. Tip seed: Killing the terminal never strands a task — reopen and it resumes where it left off, saying so once.
The full contract — every flag, the exit codes, the
--jsonschema, the stream discipline, and the rules for measuring codeaf — is HEADLESS.md. This section is the catalog entry; that file is what a harness is written against.
What: The task, done, with nobody watching. Not the static pipeline: this
is the resident's own brain with the conversation removed, so the contract for
the work, the delivery gate, the repair a cited gap earns, and the replan when
a leaf runs out of room are all still there. It works in the directory you're
standing in and edits it in place.
Where: codeaf do "<task>" [-w dir] [-db path] [--json] [--yes-spend]
How: The exit code is the verdict — 0 worked, 1 didn't, 2 hit the
wall with partial work. --json prints one object with the deliverable, the
artifacts, real spend, node count, and blocked_on when a question stopped it.
Share one -db across runs and the second run knows what the first learned;
omit it and the store is private and deleted on the way out.
Tip seed: codeaf do runs a whole job from one command — and its exit code
is honest enough to put in a script.
What: The benchmarked, byte-stable CLI path: compile a goal to a plan, run it with the atomic linear harness. Learning surfaces (anchors, playbooks, router) feed it without changing its contract. Tip seed: CI and scripts use codeaf plan/run — same tools, same rails, no chat needed.
What: A few calm rows and nothing else: whether a key is set and where it came from, the store and its size, who is resident right now, today's spend against the rail, and where the model-call log is. Tip seed: codeaf doctor answers "can it reach a model, and what has it cost me today?" in a handful of lines.
What: The self-knowledge pair from the CLI: measured per-scope competence (strong / frontier / weak / stale), and today's self-spend receipts with what each attempt learned. Tip seed: Two commands answer "is it actually getting better?" — codeaf competence for the map, codeaf why self for the receipts.
What: Inspect, search, and retract beliefs from the CLI. Tip seed: codeaf notebook shows what it believes — and what evidence each belief stands on.
What: CODEAF_DAILY_BUDGET, CODEAF_PREAUTHORIZE_SPEND/--yes-spend,
CODEAF_VOICE_MODEL, CODEAF_IMAGE_MODEL,
CODEAF_SPEECH_MODEL, CODEAF_MUSIC_MODEL, CODEAF_VIDEO_MODEL,
profile dir config at ~/.codeaf/config.json.
This catalog is a design document: it is on disk, it is written to
persuade, and it goes stale the moment a build lands. What codeaf
actually says about itself at runtime comes from internal/manual — a
small set of user-voice markdown pages embedded in the binary, searched
by the manual tool on the head's tool belt and injected into the
router's grounding context when a self-question is recognized. Those
pages are the authority: where they and this file disagree, they win. The
retrieval probes in internal/manual, the slash-command and alias gate in
internal/tui3/manual_test.go, and the tool-belt gate in
internal/session/manual_test.go fail the build when the runtime corpus cannot
answer for what the live chat exposes. Add a feature, add its paragraph there;
update this entry afterwards if you like, but never instead.
The intended pipeline: (this file + user's recent usage signals) → one cheap LLM call → one hint. Selection guidance for that call:
- Prefer entries whose surface the user has never touched (journal shows no alt+v? offer the voice tip).
- Prefer deepenings of shallow use (uses /budget to check but never set
a default? offer
/budget default). - Never more than one hint at a time; render it as one dim line in the help position, dismissible, never modal — the same Apple-calm rules as everything else.
- Tip seeds are starting points; regenerate phrasing in the system's voice, don't quote verbatim.