kamchatka
A terminal agent that shows you its context.
Built on nachalnik, and built to demonstrate it. Everything in here is
ordinary user code — two providers, the tools, the permission policy, the compactor, the drawing.
The runtime supplies the state machine, the context and the paper trail.
$ cargo install kamchatka
$ export KAMCHATKA_API_KEY=sk-or-...
$ kamchatka -m qwen/qwen3-coder -f src/lib.rs "what does this crate do?"
┌ chat │ context │ trace │ permissions ────────────────────────────────────────────────────────────────────────┐
│> what does the kernel do? │
│ │
│⟩ read({"path":"src/kernel.rs"}) │
│ │
││ pub struct Kernel(Arc<InnerKernel>); │
│ // ... 900 more lines │
│ │
│· read: 15 tokens │
│ │
│The kernel is a state machine with five states. `step` performs one transition and returns the state it │
│produced; `turn` repeats it until the model stops asking for tools. Nothing in it decides what the model is │
│told - that is the projector's job. │
│ │
└──────────────────────────────────────────────── alt+1 chat · alt+2 context · alt+3 trace · alt+4 permissions ┘
┌ you ─────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ ask for something, or /help │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
done · gpt-4o-mini @ openrouter.ai · ~1,168 tokens, 0.9% (128k) · 1,102 really · 15 held back · F1 for the keys
The permissions are enforced, and it is still a demonstration rather than a hardened agent. The
shelltool runs under Landlock:network: denyis refused by the kernel atconnect(),write: denymakes the working directory read-only, and nothing outside that directory is reachable either way. The three file tools are held to the same boundary by their own code. The permissions tab says which you have —shell: confined, orshell: a command can do any of thesewhere Landlock is not available.--sandbox-allow PATHopens up more and--no-sandboxturns it off. Within the boundary the file tools are finer than a capability:readis allowed, andread .envis a question, because a path rule can tighten what a capability allows. It is one LSM, not a container; see what it does and does not protect you from.
👉 four tabs, one window
ctrl+t for the next one, or alt+1 … alt+4 directly. The prompt and the status line are under all of them, so a message can be sent from anywhere and the budget is always in view.
asking ••• 42s · gemini-3.6-flash @ generativelanguage… · ~13,204 tokens, 10.3% (128k)
While the runtime is working, three dots move under the word for what it is doing, and after five
seconds they are joined by how long it has been. Which dot is lit comes from the clock rather than
from a frame counter, so it stops where it is if the screen stops being drawn — asking on its
own is the same word whether a request is in flight or the program is wedged, and the marker is
there to tell the two apart. It is absent while the runtime is resting, including when it is
waiting on you: nothing should suggest work is happening while a question sits unanswered.
chat is the conversation, and every terminal agent has one. context is why this exists:
┌ chat │ context │ trace │ permissions ────────────────────────────────────────────────────────────────────────┐
│ id label kind sending held what it says, or why it is not being sent │
│ 1 ▪ src/kernel.rs reference 1,045 pub struct Kernel; │
│ 2 · user user_message 6 what does the kernel do? │
│ 3 · assistant assistant_message 7 asked for read │
│ 4 - read tool_result 0 15 excluded: pruned at the terminal │
│ 5 · assistant assistant_message 7 asked for shell │
│ 6 … shell tool_result 11 9,004 compaction: compacted to make room │
│ 7 · assistant assistant_message 62 The kernel is a state machine with five states. … │
│ │
└────────────────────────────────────────────────────────────────────────────── 7 items, 2 not going, 1 elided ┘
That is not a summary and not a debug view. It is the list of items the runtime is holding, in order, with what each one costs, whether it is going into the next request — and the column that matters most, what the model will actually read of it.
sending is what an item puts into the next request; held is what it is keeping out of one.
For most rows the first is everything and the second is blank. The two that differ are the ones
worth finding: item 6 holds nine thousand tokens and spends eleven of them on the marker that
replaced it, and item 4 spends nothing at all. The sending column adds up to the figure on the
status line, and the held column to the held back beside it — which they did not, when the row
reported what an item held under a heading that said what it cost. Item 4 is marked - and says on its own
row why it is out, in the projector's words. Item 1 is ▪, pinned, so the compactor will be
refused if it comes for it. Nothing disappeared: things changed state, and the state is on screen.
Item 6 is …, elided, which is the third answer between in and out. It is still in the
request — as the one line the row shows, saying it was compacted away — so the call on row 5 still
has an answer, and the model reads a conversation in which it asked for something and can no
longer see what came back. That is the truth. Dropping the result outright would have forced the
projector to drop the call with it, since a call with no result is a request most providers
reject, and the model would then be reading a conversation in which it never asked at all. What
an elided item holds is counted as held back rather than spent, and space spends it
again.
tab moves the keys between the prompt and the table:
| key | what happens |
|---|---|
| space | cycle how much of it the model gets: all of it → a … marker → nothing → back |
| p | pin it, so that the compactor is refused if it tries |
| e | change what it says |
| enter | read the whole of it — see below |
| ← / → | move between its pages, while it is open |
| u / U | undo / redo the last change to the context |
| 23G | go to the item numbered 23 — the number /prune takes |
An oversized tool result is held as two items: the truncated copy the model was shown, and the
whole of it beside it, marked ▫ archived and not going. space or p on that
row is how you say send the whole thing — it is the only way to say it, and the token count in
the row is what it will cost you.
enter opens the item, and an item has more than one honest answer to what is this? The box is paged, and ← / → move between the pages:
┌ [6] shell · tool_result · elided · 1,204 tokens ──────────────────────────┐
│ to the model │ as stored │ v2 │ v1 │
│ │
│ role: tool │
│ answers: shell │
│ │
│ [... compacted away ...] │
└ ← → the pages · 1–6 of 6 · any key closes ────────────────────────────────┘
to the model is what this item puts into the next request, taken from the projection of the
whole context rather than of the item alone — so a call the projector had to drop, or an ordered
turn it had to flatten, shows up here as the repair it really is. An item that is not going says
so, with the reason. That last one is not always visible from the row: a tool result whose call
has been taken out reads as · active and costs what it costs, and the projector drops it anyway,
because a result answering nothing is a request most providers reject. Its page says
nothing: this item is not in the request, and the box opens on that page rather than on the
text, since the projection rather than the state decides which of the two is the surprise. as stored is what the item itself holds, which for an elided or
excluded one is not the same thing at all; that gap is the reason the pages exist, and it is why
an item the model does not read in full opens on the first page instead of the second.
v1, v2 and so on are what it said before somebody rewrote it, newest first. A terminal
edit supersedes, so the old text keeps a row of its own — but amend replaces in place, to
keep the number the model refers to the item by, and the old text then exists nowhere except the
context.replaced event. This reads it back off there, up to eight versions deep.
e is the verb the others were missing. space and p decide whether the model reads an
item; e decides what it reads. The prompt turns into an editor holding the item's text, and
committing supersedes the old one rather than overwriting it:
1 ~ ledger.py reference 469 superseded: superseded by item 8
8 ▪ ledger.py reference 477 """A running-balance ledger.
The original is still there, still readable, still one u from coming back — and the next request carries only the edit, because a superseded item is not projected. Trimming a 2,000-line file down to the function that matters is two keystrokes and a delete.
trace is every event the runtime emits, as it happens, in the same names the session log is made of:
┌ chat │ context │ trace │ permissions ────────────────────────────────────────────────────────────────────────┐
│ model.requested 6 messages, 4 tools, ~1579 tokens │
│ +6.4s context.added [7] assistant, 72 tokens │
│ model.finished EndTurn, 1522 in / 19 out (reported) │
│ tool.requested shell │
│ permission.requested shell (3) │
│ state.changed requesting → deciding │
│ context.recounted 1425 → 1377 tokens │
│ +11.0s permission.decided shell: allow, answered when it was asked about │
│ state.changed deciding → ready │
│ state.changed ready → executing │
│ tool.started shell │
│ +1.3s tool.output shell, 12 bytes │
│ context.added [8] shell, 23 tokens │
│ tool.finished shell, 23 tokens │
└──────────────────────────────────────────────────────────────────── 41 events · /save keeps them all ────────┘
Every transition of the state machine is in there, and so is everything either side of it: what was
requested, what was decided, what was added to the context and what it cost — down to the wiring,
since plugging in a provider, a policy and each tool is itself an event and the screen subscribes
before any of it happens. Every event says what it carries: context.replaced shows the first line
of what an item used to say, which is the one thing nothing else can recover; tool.repaired names
the identifier a provider reused and what was wrong with it; tools.changed lists them rather than
counting them. There is a test that the tab draws every event the session recorded, and another
that none of them is a name with an empty line beside it.
The column down the left is the gap since the line above, and it is blank under a tenth of a second. Nearly everything in a session happens between one frame and the next, so what is left with a number beside it is the model thinking, a command running, and the eleven seconds somebody spent deciding whether to allow a shell — which is the question people bring to a log, without having to subtract a column of timestamps to answer it.
It is the same stream /save writes to a .jsonl, and reading it is how you find out that a
permission question became a decision became a state change became a call. tab then
up reads back through it.
The one thing it does not draw a line per is a fragment: the model's streamed text and a running
command's output arrive dozens of times a second, and a line each would push the rest of the trace
off the screen before it could be read — a cat of a thousand lines really did erase the whole of
it. Tool output is one line that counts up (tool.output shell, 12,004 bytes so far) and the
model's text is on the chat tab as it arrives. The pane keeps the last few hundred lines; /save
keeps every event there was, including the one line no subscriber can ever catch — the kernel's own
session.started, emitted while it is being constructed.
And from anywhere, ctrl+p prints the request those items add up to — the kernel's own rendering of it, not a description, with a header naming everything the projector left out and why:
12 item(s) in, 4 out:
[13] left out: an assistant turn with no content and no answered calls
[14] left out: archived: the whole output; the model was shown a truncated copy
[15] left out: excluded: pruned by `tool:shell:latest`
repaired: dropped the call `call_301842` (shell) from item 13: its result is not
in the projection
"why is that not in there?" is the question this whole runtime is for, and the JSON on its own can
only answer the other one. /payload goes one further and prints what the provider will put on
the wire, byte for byte.
✍️ what the model writes
Models answer in markdown, so the chat tab reads it as markdown: headings and emphasis get weight and colour, inline code gets told apart from prose, list continuations hang under their bullets, and a fenced block gets a rule down its left instead of a slab of background — which is the one thing a terminal cannot do without knowing what colour the theme is.
Tables are drawn here rather than by the renderer, and for the same reason as the fenced blocks: the renderer lays one out at whatever width its contents want, and a row wider than the window was then wrapped like a sentence — so half a border arrived on the next line and the table came apart. A table is a fixed shape. What gives when it does not fit is the columns, widest first, and the cells wrap inside them with their inline styling intact; the colons in the delimiter row decide which end of its column a cell sits at.
The parsing is tui-markdown; only the styling is this
crate's. Nothing else on the screen is treated as markdown: a tool's output is what the tool said,
and running that through a renderer would be inventing structure it never had.
⌨️ the rest of the keys
| key | what happens |
|---|---|
| enter / alt+enter | send / a new line |
| pgup / pgdn | scroll the conversation |
| ctrl+e | follow the newest again |
| tab | move between the prompt and the open tab |
| ctrl+t | the next tab; alt+1 … alt+4 for one in particular |
| esc | stop what is running, and keep what arrived |
| ctrl+c | the same, and again to leave |
| F1 | all of them, including the slash commands |
Where you leave the conversation is where it stays. A turn that writes four hundred lines used to pull the window down to the newest of them on every fragment, so anything it had said thirty seconds earlier was unreadable until the turn ended; now nothing but your own message moves it, and the line along the bottom says how much has arrived underneath. ctrl+e goes back to following, and so does scrolling down to the end.
Stopping is cooperative rather than a killed process. The provider notices between fragments and returns the text it has; the shell tool kills the command — and everything the command started, since it runs in a process group of its own — and still answers the call it was given. The partial turn ends up in the context like any other, where it can be read, pruned, or left alone.
A message sent while a turn is running waits for the end of it, and then goes in and gets a turn of its own — and says so when you send it, because until the turn ends it is on the screen and not yet in the context, which is the one moment those two disagree. It cannot go in any earlier: the answer the model is still writing would land after it, leaving the next request ending with the model talking rather than with your question — and mid-loop it would land between a tool call and that call's result, where a request cannot have a user message. So a message typed to steer a turn is answered after that turn rather than during it.
A pasted block arrives as the lines it was pasted as: bracketed paste keeps a pasted newline from being read as enter and sending half of it, and the carriage returns a terminal spells those newlines with are put back.
🔑 the permissions tab
The other place the policy appears is the permission prompt — one call at a time, at the moment you are least inclined to think about it. permissions is every answer you have given, in one place, where it can be changed:
┌ chat │ context │ trace │ permissions ────────────────────────────────────────────────────────────────────────┐
│ capability or path answer the tools it covers │
│ read allow read │
│ write deny write │
│ shell allow shell │
│ network allow shell, when the command reaches for it │
│ .env* deny edit, read, write │
│ │
└──────────────── shell: confined · 12 more it will ask about · space cycles · a allow · n never · r ask again ┘
A fresh session has no rows at all: everything starts at ask, and the tab fills up as you answer.
Rows are decisions, not defaults. ask is what this policy does about anything nobody has
mentioned, so a row per undecided thing would be a screenful of "it will stop and ask" burying the
one or two lines that say what this agent can do without stopping. What is not listed is counted
instead — 12 more it will ask about — because a screen showing five decisions while standing for
seventeen answers would be a different kind of dishonest. A subject arrives here when somebody
answers a question about it, and cycling one back to ask takes it off again, which is what taking
a decision back looks like.
What that costs is worth saying plainly: you cannot refuse something here that has never come up. Deciding in advance means answering the first question with a or n.
The line along the bottom comes first because it is the one thing on this tab that is not
negotiable. A registered shell that is not refused can read, write and reach the network whatever
the other rows say — so shell: confined (or shell: a command can do any of these) is what makes
the rest of the table mean anything.
Two kinds of row. A capability is what a tool declares, which is what makes "always" work for
tools this program has never heard of — including an MCP server's, which all carry mcp:<name>. A
path rule is finer than any capability: read: allow is a reasonable thing to want and
read .env: allow is not, and the difference is a property of the file rather than of the tool
that opened it. The strictest of everything consulted wins, so a rule can only tighten what a
capability allows. network is the odd one: no tool declares it, because a model that wants the
network writes curl — so the row says which shell it reaches, and when.
space cycles a row through ask → allow → deny, or a/n/r directly, and it takes effect on the next call. Answering "always" at a permission prompt writes to this same table — the prompt and the tab are one object, not two.
allow runs with no question. deny never runs and never asks: the model gets a tool result it
can read and work around, rather than a call that silently vanished. The transcript says which
stance did it — shell: refused by `network`, which this command reaches for — because "the
call was not permitted" beside a shell: allow is true and useless.
The model is told the same thing, and told which kind of refusal it was, which is the only part it can act on:
the call was not permitted: refused by the rule for `**/.env`. That is a standing rule
rather than an answer to this one call, so making the same call again will be refused
the same way.
the call was not permitted: this call was refused when it was asked about. That is an
answer to this call rather than a standing rule, so a different approach may well be
allowed.
A model that cannot tell those apart does the wrong thing with either: it rephrases the same call
at a rule that will never move, or it abandons an approach that was only refused once. The
sentence comes from Careful and reaches the model through PermissionPolicy::why, so the
person and the model read the same reason instead of the person reading it alone.
the question itself
┌ a tool wants to run ─────────────────────────────────────────────────┐
│ shell wants: shell, network │
│ │
│ cmd: curl -s https://example.com │
│ │
│ [y] once [a] always, for shell and network [n] no │
│ [i] the exact JSON [d] drop it │
└──────────────────────────────────────────────────────────────────────┘
It names everything the policy consulted, not just what the tool declared, and a
answers for all of it — including any calls already waiting behind this one, since a model that
asks for three things at once produces three questions and an "always" that did not reach them
would go back on itself one keystroke later. y is this call only; a curl allowed once
runs with the network open for that command and no other.
Arguments longer than the box get their own scrolling region between the header and the answers,
with pgup and pgdn moving them; the answers stay where they are. An amend
carrying a rewritten tool result is as long as the result was, and a question whose answers had
been pushed off the bottom of the screen is one nobody can answer.
Typing does not answer it. A question arrives on its own schedule, in the middle of whatever you
happen to be typing, and its keys are ordinary letters — a grants a capability for the rest of
the session and is also the third letter of "what". So a question waits for a pause in the typing
before it starts taking keys as answers, and until then your letters go where you aimed them: into
the prompt. enter sends what is in the prompt, and it waits, exactly like a message sent
into a running turn does.
🐢 one transition at a time
The loop is a state machine, and /step performs exactly one transition of it instead of a whole
turn. That is the only way to stand in ready — which the runtime documents as a resting state
on purpose, the moment the model has said what it wants and nothing has happened yet:
> /step how many lines are in ledger.py?
⟩ shell({"cmd":"wc -l ledger.py"})
· step → ready: 1 call(s) decided, none of them run yet
shell {"cmd":"wc -l ledger.py"}
The command is decided, permitted, and not running. From here you can read it, prune the context
it would have run against, drop it, or /step again to run it. A whole turn walks through this
state without ever drawing it, which is why every other agent's "approve this command?" is the
only checkpoint it has. Here the checkpoint is the state machine's own.
/step again for each transition — the tool runs, then the next request goes — or /continue for
the rest of the turn. While stepping, answering a permission does not quietly resume: you asked
to drive.
🔧 what it comes with
Four tools — read, write, edit, shell — and a policy that asks about all of it. Nothing is
allowed on your behalf before you have been asked, read included. Answering always answers for a capability, not a
tool name, which is what makes it work for tools this program has never heard of:
$ kamchatka --mcp 'files=npx -y @modelcontextprotocol/server-filesystem /srv'
Those arrive through nachalnik-mcp carrying mcp:files, so "always, for
mcp:files" is one server and not the next one. The name= is worth giving: it prefixes the
server's tools and it is what the grant is for, and without it the name comes from the program,
which for most of the servers people actually run is npx.
The registry is live rather than fixed at startup: /tools drop shell stops offering it from the
next request onward, which is one call on the kernel and no restart. When a model has gone down
the wrong path entirely, d at the permission prompt drops every call it is waiting on
with one reason — and the model is told, rather than left waiting on calls that silently vanished.
🔎 letting the agent read and manage its own context
--introspect, or /introspect at any point, offers two more tools. They are off by default,
because a model that can rewrite its own context is a decision rather than a default. There is a
write-up of two sessions: one where an agent found a
false note in its own context and corrected it, and one where it took back a hallucination of its
own by rewriting the two turns it had made things up in.
introspect reads. look lists every item it is carrying — what each one is, what it costs,
whether it is going into the next request and why not if it is not — and reads any of them in
full, block by block, including what it was thinking when it produced them. request shows the
request about to go out, message by message, with what the projector left out and what it had to
repair.
budget is the one a decision gets made from:
the next request is ~48,120 tokens of 128,000 (38% full, ~79,880 left)
47,343 in the context, 777 in the tool definitions
~9,004 tokens are being held back - excluded, archived, or elided to a marker
the last request really cost 52,905 in / 214 out, as the provider counted it
the estimate is corrected by x1.09, learned from 6 request(s)
the 4 most expensive item(s) actually going into it:
id state kind tokens if all go what it is
31 active tool_result 18,204 18,204 shell: cargo test --workspace…
14 active reference 9,880 28,084 src/kernel.rs: use std::…
9 pinned system 240 28,324 system: You are working in… · not yours
Estimates are named as estimates, the provider's own figure sits beside them, and the list is what the request actually carries — an orphaned tool result the projector repairs away costs nothing however active it looks, and offering it as something to give up would be advice that buys nothing. Items that are not the agent's to move say so, rather than costing it a refused call.
draft and fork take a snapshot of the context, resume it as a second kernel with no tools,
ask it once, and hand back only what it said. draft is for reading your own answer before you
give it; fork is for asking whether a piece of context is what is leading you astray:
⟩ introspect({"action":"fork","question":"am I overfitting to the first stack trace?",
"without":[14,15]})
a copy of you, asked `am I overfitting to the first stack trace?`, on 9 of your items,
without 14, 15. None of this is in your context and nobody has read it; it is yours to
use or drop.
A fork can think; it cannot act, and it cannot go on thinking after it has answered once. Nothing
it does reaches this session's context or its log. Forking needed no change to the runtime at all
— Kernel::snapshot and Kernel::resume already are that, and leaving an item out is one field
on a copy of the snapshot.
amend manages. prune moves items between the same states the space key does —
elide for a tool result that has served its purpose, which keeps the call answered and stops it
costing what it holds; exclude to take one out altogether; pin to protect one from compaction
— named by ids or by select, which takes the same selector language /prune does, so "the
tool results I am done with" is one call rather than twelve numbers read off a listing. revise
rewrites what an item says. note writes something into the context — a plan, a conclusion, a
thing not to try again — attributed to agent so the context pane can say who put it there, and
pinnable so that compaction cannot take it. Saying the same thing out loud in a turn is not a
promise about anything; a pin is.
undo walks back — deliberately not the kernel's undo stack. That stack is yours, bound to
u, and the top of it while a tool is running is always the assistant turn that asked
for the call: one step would erase the model's own question and orphan the answer it is waiting
for. So amend keeps a journal of what it did, and that is what it walks. A reason is required
on every change, and it is what you read in the context pane.
Three things are refused outright, with the refusal handed back to the model: a pinned item (a pin is a promise, and it was not made to the model), a system instruction, and the assistant turn it is currently speaking in. It may unpin what it pinned itself, and nothing else.
They are two tools rather than one with a mode argument, because a tool declares its capabilities
once for every call it will ever receive. One tool would mean that answering always to "may it
read its own context?" also answered "may it rewrite a tool result?" — a grant that delivers more
than it implies, which is the shape of thing this program exists not to do. So the permissions tab
has a row for introspect and a row for amend, and you can answer them differently.
🧩 two dialects, and why one of them keeps the order
--gemini talks to Google's own API instead of an OpenAI-compatible one. That is not a
convenience — it is the difference between seeing what the model did and seeing a rearrangement of
it.
generateContent answers with content.parts[]: a thinking part, a sentence, a functionCall,
in the order they were produced. The OpenAI-compatible shim in front of the same model flattens
that into a content string beside a tool_calls array, because the dialect it is imitating has
nowhere to put an order. Everything downstream then reads a turn that has been tidied up.
▸ [4] assistant · assistant_message · from model · active · 178 tokens
--- 3 block(s), in order ---
[0] reasoning: The user wants the code word, and the tool is the only place it is…
[1] text: Let me look that up.
[2] call (signed): secret({})
That is the context pane, and introspect reads the same thing back to the agent. It is only worth
having because the order is really in there: the runtime records it as Content::Blocks, counts
it, prunes it and elides it like any other content, and LinearProjector::send_blocks sends it
back the same way.
Signatures are the other half. Gemini signs the parts of a turn and answers
400 Function call is missing a thought_signature to a request that returns one without it — and
it signs text parts as well as calls, which a message with three slots has nowhere to keep. Here
each part's own fields ride back out on the block they arrived on, unread.
Both providers answer one trait, Endpoint, so /model, /models, /provider and the status
line work the same against either and nothing above them knows which wire format it got.
$ export KAMCHATKA_API_KEY=... # a Google AI Studio key
$ kamchatka --gemini --introspect "what does src/kernel.rs do?"
🔀 the model, and the address it lives at
/model says which model this is talking to, where that is, in what dialect, and how much context
it has:
· gemini-3.6-flash at https://generativelanguage.googleapis.com/v1beta/openai
(openai-compatible), 1,048,576 tokens of context
/model ID switches the model and /provider URL [ID] switches the address — and the model with
it, because a model belongs to the address that serves it. Switching one and keeping the other is
how a session ends up asking the ollama on this machine for gemini-3.6-flash; given no model the
old name is kept and the new endpoint is asked whether it has one by that name, which is a notice
now rather than a 404 on the next request. Both matter for different reasons: comparing two hosted
models is one address and two names, while comparing a hosted model with the one running on this
machine is two addresses. A comparison that cannot see the address is a comparison of names.
/models [FILTER] is what makes /model usable, because the ids belong to the endpoint rather
than to the model: the same thing is google/gemini-3.5-flash at one address and
gemini-3.5-flash at another, and after a /provider there was no way to find out which without
guessing. It asks the endpoint, marks the one you are on with ▸, and takes a filter because a
list of fifty-four is not an answer:
┌ 6 of 54 matching `flash-lite` · /model ID switches ────────────────┐
│ gemini-flash-lite-latest │
│ gemini-2.5-flash-lite │
│ gemini-3.1-flash-lite-preview │
│ gemini-3.1-flash-lite │
│ gemini-3.1-flash-lite-image │
│ ▸ gemini-3.5-flash-lite │
└ 1–6 of 6 · any key closes ───────────────────────────────────────────┘
The key is not switched with the address. It is read from the environment once, at startup, and a
key typed at a prompt would be a key in the transcript — so /provider is for the addresses that
need no key or take the same one: a local model, a proxy, another base URL on the same account.
What is not switched either way is the context. The same items go to whatever answers next, which
is the whole of what makes the answers comparable. /seams names the six replaceable parts and
what is in each of them right now, asked of the kernel rather than restated from what this program
set up at startup.
📏 the number in the status line is a guess, and says so
Nothing here has the model's tokenizer, so the figure the status line leads with is an estimate —
it is written ~2,460 for that reason. The percentage beside it names the total it is a
percentage of (0.9% (128k)), because a fraction of an unstated number is not something anybody
can act on, and it turns yellow past 70% and red past 90%. Then comes what the provider actually
charged for the last request, and /budget is where the two are reconciled:
the next request: ~20,125 tokens, 19,953 of context and 172 of tool definitions
the limit: 1,048,576, which the next request would fill 1.9% of
the last request really cost 20,063, as the provider counted it
the counter has learned from 2 request(s) and scaled itself by 1.131: its own guesses
came to 35,447 tokens where the provider counted 40,073, so it was reading 13.1% low
That correction is the runtime's Calibrating counter: every response tells it what the request
it just estimated really cost, and it adjusts. Over a real session against Gemini it went from 13%
low to within 0.3%. A budget nobody can check is a decoration.
The compactor shortens the oldest tool results to a marker once the context passes --compact
(0.8 by default) of the limit. It does not summarize them — it never read them — and it touches
nothing that is pinned, because the kernel refuses. Every one of them is still on the context tab,
marked …, still holding every byte it held, one space from coming back.
📦 installing
$ cargo install kamchatka # from the registry
$ cargo install --git https://github.com/ljedrz/nachalnik kamchatka
$ cargo install --path kamchatka # from a clone
Rust 1.88 or newer, and that is the whole list: no system libraries, no pkg-config, nothing
to install first. The TLS is rustls over ring, which builds its own cryptography rather than
looking for yours. Adding --no-default-features drops MCP support, and the --mcp flag with it.
The sandbox is Linux-only. The shell tool is confined with Landlock,
which is a Linux LSM; everywhere else the program builds and runs, but the shell is unconfined,
the permissions tab says shell: a command can do any of these rather than shell: confined,
and the stances are answers you were asked for rather than a boundary anything enforces. On Linux
it also wants a kernel new enough to have Landlock — 5.13 for the filesystem rules, 6.7 for
network: deny — and the tab says which of the two it got.
🎛️ options
kamchatka [OPTIONS] [MESSAGE]...
-m, --model <MODEL> the model to talk to [env: KAMCHATKA_MODEL]
[default: openai/gpt-4o-mini, or gemini-3.6-flash
with --gemini]
-f, --file <PATH> put a file in the context, pinned; may be repeated
-s, --system <TEXT> a system instruction; the runtime ships none of its own
-r, --resume <PATH> carry on from a session written by /save
--mcp <COMMAND> an MCP server to run, as `[name=]command`; may be repeated
--requests <N> how many requests one turn may make [default: 8]
--compact <FRACTION> how full the context may get; 1 never compacts [default: 0.8]
--parallel run the model's tool calls at the same time
--gemini talk to Google's own API rather than an OpenAI-compatible
one, so a turn keeps the order it was produced in
--introspect offer the model the two tools that read and manage its own
context; /introspect turns them on and off while it runs
--sandbox-allow <PATH> a path outside the working directory the shell may also
read and write; may be repeated
--no-sandbox run the shell tool unconfined, reaching whatever you can
Environment:
KAMCHATKA_API_KEY the key; or OPENROUTER_API_KEY, or OPENAI_API_KEY
KAMCHATKA_BASE_URL where the requests go, e.g. http://localhost:11434/v1 for
ollama; OpenRouter by default, or Google's own v1beta
with --gemini
KAMCHATKA_CONTEXT_LIMIT the model's context size, for a provider that will not say
That is --help, which lists the environment too rather than leaving three settings for the
readme alone to mention.
/save writes two files: a .jsonl of every event that happened, and a .json snapshot of the
context. The snapshot has two ways back in.
kamchatka -r PATH starts a fresh session from it, which is the faithful one: the item numbers,
the model parameters and what the token counter had learned all come back exactly as they were,
because Kernel::resume is a constructor and builds the session around them.
/load PATH brings it into the session you are already in, which is the useful one. It is a
context operation and it plays by the same rule as the rest of them — nothing is destroyed. What
was in the context is archived, keeping its numbers and its contents; anything pinned
stays where it is, because a pin is you saying so and --system is pinned; the loaded items come
in as new items with new numbers, and the conversation they were is read back onto the chat tab.
u twice puts the whole thing back.
That makes a checkpoint out of a file. /save good, let the agent go somewhere useless, /load good, and carry on from where it was still working — without losing the detour, which is sitting
in the context marked ▫ if you want to read it.
🧪 the tests
They draw the screen and read it back, against a scripted model:
harness.tab; // over to the context
harness.press.await; // the first item
harness.press.await; // out
let after = harness.app.kernel.preview_request.unwrap;
assert!;
A terminal program whose tests only checked its own state would be testing the half nobody looks at.
🎸 the name
nachalnik is an homage to KINO's Nachalnik Kamchatki. Kamchatka was the boiler room Viktor
Tsoi shovelled coal in; this is the one where the work actually happens.
licence
MIT.