codeaf

Overview ¶

The cache from the command line: what it holds, and the one destructive verb that empties it.

`codeaf cache` answers the question and changes nothing. `codeaf cache clean` deletes ~/.codeaf/cache — the shared toolchain caches every task worker fills (internal/cachedir says what lives there and what never does) — and because a deletion cannot be undone it is guarded the way destructive command lines are guarded everywhere a person has already learned: the blast radius is printed first, sizes and path included, and then the confirmation is a TYPED WORD rather than a y. `rebuild` asks y/N because the journal survives it; this one actually destroys bytes, so the answer that proceeds is a word written out, and any other line — including an empty one, including EOF on a pipe — keeps everything. --yes is the scripted door and skips the question, which is rebuild's own arrangement.

AND THE WORD IS THE SAME WORD THE CHAT WANTS. In the chat the deletion is `/cache clean now`, because the chat cannot pass a flag; here it used to be the word "clean", so the one prompt in the product that deletes gigabytes asked for a different word depending on which surface a person had learned first. One word, [cacheCleanWord], in both. `--yes` stays as the script's spelling and is not a word anybody types at a prompt.

The doc command: the billed document parse the belt's read_document tool runs, printed straight.

The tool exists because a scanned PDF is exactly what plain read cannot open; this command exists for the same reason `manual` does one door over — the belt has a hand a person scripting a fix had no way to reach. Both run the same road (internal/session's session.ReadDocument): the same guards, the same local rung for a PDF with a text layer, the same billed rungs on the profile's key, the same refusals. What this door adds is the shell grammar, --pages on the local rung, and a plain file printed as-is with no call and no bill.

The image command: the belt's generate_image hand, from a shell.

One prompt in, one picture written where the caller says, its path on stdout — and the spend recorded the way the tool records it, one row in the usage ledger, so a run's books see a picture a script paid for exactly as they see one a conversation paid for. The road itself is session's, shared with the tool: the same model ladder, the same references, the same refusals, the same accounting.

The model-call log from the command line.

`codeaf logs` is the reading end of internal/calllog: the file every model call in the process writes a line to, always, without a proxy in front of anything. The file is JSON Lines because a machine reads it too; this command exists because a person does not want to.

One line per call. A call that is still in flight shows as one — that is the whole reason the log writes a row on the way OUT as well as on the way back: a planning call four minutes into a 65,536-token ceiling used to be indistinguishable from a process doing nothing at all.

THE READER SHOWS EVERYTHING THE RECORD HOLDS. A field that is on the row and not on the line is a field a person has to leave the tool to read, and the half of the row that used to be invisible — the lane asked for, the lane that answered, what was done about a silence and what it cost — is exactly the half somebody opens this command to see. Anything the row does not carry is absent rather than zero.

Command codeaf is an agent you talk to, and hand work to when you walk away.

codeaf                       open the conversation this directory was having
codeaf do "<task>"           hand it one job and read the answer on stdout
codeaf plan new "<goal>"     write a plan to a file without running it

The static plan pipeline it opened life as is four subcommands of `plan` now, and it is one feature of many rather than the product.

The manual from the command line: every page this build carries, one page as it is written, or the sections that answer a question.

It exists because the manual had exactly one reader and it was not the person. Everything codeaf knows about itself was reachable only through the belt's `manual` tool — which is a model call, so it needs an API key, costs money on every lookup, and hands back a RETELLING that nobody can tell from an invented one. That is the exact failure internal/manual was written to prevent, and the questions people ask most are the ones they ask BEFORE any of that is set up: what is this, what does it cost, what can it do, who can see my files.

So this command needs no key, makes no model call, opens no store, spends nothing, and prints the pages VERBATIM. A person reading the manual here is reading the manual.

AND NOTHING HERE IS CUT SHORT. internal/manual's caps exist because a model pays for its context by the token; a terminal does not, and a page truncated on the one surface where the whole of it is free would be a budget wearing a reason it does not have. Paging is the terminal's job, not this command's.

The patch command: the edit hand's exact-match replacement, from a shell.

It exists for the same reason `manual` does, one tool along: the belt has an edit hand the model uses constantly, and a person scripting a fix had no way to reach the same one. `codeaf patch` is that hand, verbatim — one old text in, the file with its single occurrence replaced out, a refusal naming the match count when the text is not there exactly once.

THE MATCHER IS THE EDIT HAND'S LAW, and it lives in internal/patch rather than here so the belt could share it; what this door adds is the shell grammar: flags, the two --*-file escapes for text that is awkward to quote, and the exit code.

The Model Pool from the command line.

`codeaf pool` answers what the pool is on this machine: the mode and the addresses in force with the word saying where each came from, the index cached from the last good read, and — under status — what is waiting to be sent and whether the relay and the mirror answered. It spends nothing, and reaches the network only under `status` and `verify`, each of which fetches the index: `status` to say whether an address answers, `verify` to check a fresh one's signature. THE KEY STANDS IN FRONT OF THE FETCH: a signature nobody can check is a fetch nobody should make, so a build left with no key in hand refuses verify at the door rather than downloading bytes it cannot vouch for.

The Model Pool's index, kept fresh at start-up.

The index is a measurement document the pool publishes: how each model did in each seat across the installs that share their judged runs. A machine that fetches one keeps it under the profile's pool directory, where `codeaf pool` reads it. The one fetch this file makes runs in a goroutine started where the pool is wired, and it never blocks a run: it writes the puller's own cache and the change is read at the NEXT start.

Nothing here seats a crew. The crew is routed per task from an evidence table the build carries (internal/crewroute); reading the pool's cells into that router as measured evidence is follow-up work, not something this file half-does.

The install's own identity at the relay: one nonce, drawn once and kept.

Every batch the outbox sends to the relay rides the header X-Codeaf-Install with this word, so the relay can tell one install's measurements from another's without ever learning who the install is: the nonce is 32 random hex characters, held in a file only this install writes, and nothing else about the machine travels with it. The file is replaced, not repaired, when it stops being that word — a mangled file costs the install its old identity and nothing else.

The Model Pool's judge, wired to the chat door's landings.

When a task lands, a model outside the crew scores each seat the work ran on. The scores go into the install's own sheet under the pool directory — the one the crew picker already reads beside the index — and, when the pool's mode allows sending, into the outbox beside it. The pure halves live in internal/pool/judge and internal/pool/record; this file owns the two things they cannot: the seam in the engine's landing (session.Config's TaskLanded) and the one provider call the judge's questions ride, billed to the judge's own seat.

Quiet by design, for poolindex.go's reason: a landing that nobody could score is an ordinary state — a pool switched off, a catalog with nothing left to pick, a model that did not answer — and nothing the person is reading should move for it. Every error here is said only under the debug record's switch.

The two streams every door writes to, named once so that a door cannot choose the wrong one by accident.

THE RULE, AND IT IS THE WHOLE OF THE RULE: STDOUT IS THE ANSWER — the deliverable, the JSON, the rows, the table, the thing a script captures — and everything a person reads ABOUT the run goes to stderr: the preamble, the progress, the warning, the question, the path a record was kept at.

It matters because the most common thing anybody does with a headless verb is put a pipe after it. `codeaf plan new "x" --json | jq` breaks the moment a `goal:` line is in the stream, `codeaf logs | grep -c .` is off by one while a path header is the first line, and `codeaf cache clean | tee log` used to hand the person a blank terminal waiting for a word they could not see — because the question had gone into the file with the data.

`codeaf do` already kept this exactly (do.go) and it is the standard the rest of the binary is held to. [TestNoDoorPrintsItsCommentaryToStdout] reads the package with go/ast and names any door that stops keeping it.

The web command: the belt's two hands outside this machine, from a shell.

`codeaf web search QUERY` is web_search — a numbered list of results — and `codeaf web fetch URL` is web_fetch — one page, markup stripped, bounded. Both run the same road the tools run (session.WebSearch and session.WebFetch), so a shell and a model get the same answer shaped the same way, on whatever provider the person's settings name.