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

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

/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

/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 Polytoken started, so the new context does not inherit mutations from prior tool execution.

Use /reset-shell when you want only the shell environment reset. Polytoken restores exported variables and PATH changes to the startup state without clearing context, appending a clear event, or changing your conversation history.

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

/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. The rewind picker lists every rewind point in conversation order: prompts, compaction summaries, and context-clear boundaries.

For a prompt, Polytoken drops the prompt and every event after it, and the prompt text returns to the input area so you can edit and resubmit. For a compaction or context-clear boundary, Polytoken removes that boundary card and every card after it. 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 an earlier point and the clear or compaction 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

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. A single Ctrl+C cancels the active assistant turn, the same as Esc. Press Ctrl+C twice to quit: the second press stops the daemon, and the session ends with it.

Resuming after a crash

If the daemon stops unexpectedly while a turn is in progress (a crash, a kill, or a lost connection mid-response), you can resume the session with polytoken continue. Polytoken restores the conversation from the events on disk and brings the prompt back immediately, ready for your next message.

Diagnostic artifacts from the resumed session, such as daemon logs and session records, are available for optional attachment when you send feedback through /feedback. See Crash Reporting and Feedback.

Session picker

When you run polytoken continue without a session ID, Polytoken opens a session picker. The picker lists sessions for your current project by default. Press Tab to toggle between your project and all sessions.

From the picker you can select a session with Enter, or terminate a live session that does not have an attached TUI by pressing K. Polytoken asks for confirmation before terminating the daemon process. The session history is preserved on disk and can be resumed later with polytoken continue.