Sessions
A session is the durable record of your work, stored on your machine. Polytoken writes every event in order as it happens (your prompts, the model’s replies, tool calls, and markers for compactions and clears) and replays those events to reconstitute the conversation. The session holds them all, however few the model is working from on a given turn.
Compacting, clearing, and rewinding all work against this record. They change what the model is working from, or move you to an earlier event. None of them touches the events already on disk.
Context
Section titled “Context”The context is what the model works from on a given turn: the events Polytoken draws from the session and sends to the model. A model can take in only so much at once, so the context is bounded while the session keeps growing. Compacting and clearing both act on the context, not the session: they change what the model works from without touching the events on disk.
Compacting
Section titled “Compacting”/compact summarizes the conversation so far. Polytoken writes a summary and
appends it to the session as a compaction event. From then on the model works
from the summary instead of the full transcript, which frees up room in the
context.
Compacting is also what lets a session run for a long time. When the context fills past a threshold, Polytoken compacts on its own, so the conversation continues instead of stopping when the context is full. Your todos live on the session rather than the context, so they survive a compaction. The model keeps its plan even as the older conversation becomes a summary.
You can pass guidance with /compact to steer what the summary keeps.
Clearing
Section titled “Clearing”/clear resets the context. The model starts fresh, as if the conversation had
just begun, and Polytoken records the reset as a clear event in the session.
Your todos are part of the session, so clearing the context leaves them
untouched. Polytoken also resets the shell environment (exported variables and
PATH changes) to the state captured when the daemon started, so the new context
does not inherit mutations from prior tool execution.
Flagged files carry across a clear according to how they were flagged: an included file is injected into the new context, and a referenced file is named in it without its contents.
Rewinding
Section titled “Rewinding”/rewind moves the conversation backward through the session. Trigger it with
the /rewind command, or with the rewind key on a card in the conversation, then
choose a point to return to. Polytoken drops every event after that point. The
rewind is destructive, and the dropped events do not come back.
Because the session is one continuous record, a rewind can move past a clear or a compaction. Rewind to a point before a clear or a compaction and that event disappears along with everything after it. The model returns to the complete conversation it had before the clear or compaction. Polytoken restores your todos to the state they were in at the point you rewound to.
You cannot rewind into the middle of a tool call. Polytoken returns you to a clean boundary: before the call or after its result.
Detaching and re-attaching
Section titled “Detaching and re-attaching”Polytoken runs as two parts: the daemon, which holds your session and does the work, and the TUI, the interface you read and type in. Because they are separate, closing the interface does not end the work.
Detach with /detach (or Ctrl+D) and the daemon keeps running with your session.
Run polytoken again in the same project and the TUI reconnects to the session.
Ctrl+C is the exception: it stops the daemon, and the session ends with it.