Skip to main content

Crate kamchatka

Crate kamchatka 

Source
Expand description

A terminal agent for Linux, built on nachalnik: the context, the budget and every decision on screen, and a shell the kernel confines.

Four tabs, each of which gets the whole window, because each of them is a whole view. chat is the conversation, and every other agent in the terminal has one. context is the reason this exists: the context, item by item, with what each one costs, whether it is going into the next request, and - for the ones that are not - why not, in the projector’s own words. Space moves an item from active to elided to excluded and back; p pins it so that compaction cannot have it; enter shows what it actually says. trace is every event the runtime emits, as it happens, under the same names the session log is made of. permissions is every answer somebody has given the policy, what each one covers, and a count of what is still a question - changeable where it is read rather than one prompt at a time.

Nothing is inferred and nothing is hidden: the context tab is a list of ordinary values the runtime hands out, and ctrl+p prints the exact request they add up to.

/attach PATH [TEXT] puts a file in the context and asks about it in one go, and -f is the same act at startup. Source and markdown go in as text; a PDF, an image or a recording goes in as nachalnik::Content::Blob, which nothing here can price - so the row, the chat line and /budget all say a piece of the figure is missing rather than putting a 0 where a number should be. It sends pictures and draws none: a terminal cell is not a pixel.

Four of the tools are about the session itself, and they are offered like the rest of them.

  • introspect::Context is the context. It lists what is being carried and what each item costs, reports the budget against what the last request really cost, shows the request about to go out, and finds text anywhere in it - what is excluded included, which nothing else can read without paying to carry it again. It also elides, excludes, pins, restores and rewrites what is being carried, writes down something compaction cannot take, and walks its own changes back.
  • introspect::Fork stands up a throwaway copy of the session and asks it something, so an answer can be read before it is given, and a piece of context can be taken away to see what it was doing.
  • introspect::Log reads the record kept beside the context: what was added, replaced, elided or compacted, and what was asked permission for and answered. It leads with what there is and what taking it would cost, so a short answer is never mistaken for a quiet session.
  • introspect::Setup reads what the session is running with: which model, which tools and what each declares, what the policy will refuse before it is asked, what the compactor and the projector will do unasked, and whether this conversation was resumed from somebody else’s.

None of them is allowed to touch what a person pinned. Nothing in the runtime knows about any of this - it is what a tool can already do with a context that is a list of public values and a request that can be built without being sent. /tools toggle ID stops offering one of them, or any other tool, and offers it again; the tools key in a settings file says which of them a session starts with.

--api gemini swaps the wire format for Google’s own, in which an assistant turn is an ordered list of parts rather than a content slot beside a list of calls. What that buys is the order itself: thinking, a sentence, a tool call, more thinking - recorded as it happened, counted, elided and excluded like any other turn, and sent back the same way. --api anthropic does the same with Anthropic’s Messages API, whose thinking is signed and has to go back as it came, and --api responses with OpenAI’s Responses API, whose thinking is sealed and goes back the same way. Every dialect answers one trait (nachalnik_providers::Endpoint), so nothing above them knows which one it got.

Everything in here is code above the runtime: the tools, the policy, the compactor, the confinement and the rendering, and the providers next door in nachalnik_providers. The kernel supplies the state machine, the context and the paper trail.

It is a library because the screen has to be testable, and because the screen is not the program. ui::draw against a TestBackend is how the tests check that an excluded item really does leave the next request. app::App holds the session, and the keys are one caller of it: submit takes the same line a person types, a command or a message, and on_event takes what the kernel says back. The program is the kamchatka binary.

The tui feature, on by default, is the drawing and the keys: ui, the prompt, and the bindings. Without it the library is the same program with nothing rendering it, and without the dependencies only the drawing wants - which is what a session driven by something other than a person at a terminal needs.

--serve puts a socket in front of the session and --connect attaches to one. The session belongs to the program running it rather than to whoever is looking at it: a turn carries on with nobody attached, a question waits for somebody to come back and answer it, and a client picking it up an hour later picks up the same session. See remote for why the records are the half that cannot be lost and the fragments are the half that can, and for why there is no authentication in the protocol and none is planned.

The way in is wiring::Setup, which assembles a kernel, a policy, the tools, the sandbox and an app::App around them in the order they have to go in, and hands back the two receivers a loop needs. headless::Headless is one such loop, remote::Server is the second and the program’s own is the third. A host with an event loop of its own wants none of them, and app::App::submit is where it hands in a line. config::Settings is the JSON the program’s --config-file takes, for a host that would rather read its defaults out of a file than hard-code them.

What a session may spend is wiring::Setup::spend, and it is enforced on the App rather than in either loop: the accounting is in on_event and the refusal in start_turn. That is how a host with a loop of its own gets the same ceiling as the program does.

Modules§

app
Everything the terminal knows: what is on the screen, what the keys do, and what to make of the events the kernel broadcasts.
args
Command-line arguments, and the session assembled from them.
attach
Putting a file in the context: text as text, everything else as bytes.
check
--check: reads a session’s record and reports what does not add up.
clipboard
Handing a piece of the session to the terminal’s own clipboard.
config
Settings read from a file, for the ones somebody would otherwise type every time.
endpoint
Where this program’s requests go, which key pays for them, and what it says about itself.
headless
Driving a session with nothing drawing it.
help
The reference text shown to a person, kept where screen and commands can both reach it.
introspect
Tools an agent uses to inspect and manage its session: one for its context, one for the record beside it, one for what the session runs with, and one for asking a copy of itself.
mcp
MCP servers, spawned and offered as tools like any other.
qr
A QR code of a short text, drawn with the terminal’s own characters.
reconcile
kamchatka reconcile: several hard forks of one session folded into one session to carry on from.
remote
Driving a session from somewhere that is not this process.
sandbox
A confinement for the shell tool, so that the permission stances are enforced rather than reported.
stopping
ctrl+c, subscribed once rather than once per turn round a loop.
tools
The two tools, the permission policy and the compactor are ordinary user code.
ui
Drawing. Nothing here decides anything - it reads App and the kernel and puts what it finds on the screen.
web
The web page for a session (--web).
wiring
Putting one together: a kernel, a policy, the tools, the sandbox and an App around them.