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. Before the reset, Polytoken cancels any running subagents so their output does not leak into the new context. Your todos are part of the session, so clearing the context leaves them untouched. Shell environment changes made during the session survive the clear. Variables that existed at startup retain their current values, and variables created during the session remain available. If a variable that existed at startup was removed, Polytoken restores its original value.

Use /reset-shell when you want the full shell environment restored to the state captured at startup. Polytoken undoes all changes to variables, PATH, aliases, functions, and shell options 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.

Set daemon.disable_context_clear to true in your config to prevent clearing the context. When this flag is on, /clear returns an error and the plan handoff option to implement with a new context is not shown. Compaction is not affected.

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, terminate a live session that does not have an attached TUI by pressing K, or create a new session by pressing N. Polytoken asks for confirmation before terminating the daemon process. The session history is preserved on disk and can be resumed later with polytoken continue.