Sessions, resume & compaction

Kin saves conversations as they run. Use /resume to return to saved work, /fork to explore a branch, /rewind to undo turns, and /compact to make room in a long conversation.

Resume & continue

Action	Command
Resume this project’s newest conversation	kin --continue
Resume an exact conversation	kin --resume <id>
Choose saved work inside Kin	/resume
Switch directly inside Kin	/resume <id>
List saved root conversations	kin ls
Resume and submit an initial turn	kin --continue -- "Continue the saved work"

A clean interactive exit prints the exact resume command, including --workdir when needed. Empty, unsaved, or failed-to-save sessions have no resume hint. Headless runs use the same journals and print their session id to stderr and the run report.

Resume restores the saved provider, endpoint, model, sampling, and permission mode unless you explicitly override them. Credentials come from current settings, never the journal, and must still match the saved provider and endpoint. Kin refuses incompatible history or ambiguous credentials rather than guessing. See configuration for precedence and providers for credentials. Replayed tool calls preserve their recorded failures, so reopening a conversation does not turn a failed call into a successful one.

A conversation has one live writer. If another process owns its journal, resume refuses and identifies the owner when diagnostic metadata is available. Return to that process or fork there. Switching sessions leaves the previous journal intact; it is unavailable during a turn, compaction, or open modal.

Forking

/fork copies the saved journal to a new session id and switches to the copy. The original remains resumable. This branches conversation history; both sessions still edit the same workspace. Use separate Git worktrees for file isolation.

The human /fork command differs from the model’s fork_agent tool, which starts a supervised child while leaving the root conversation in place. See subagents.

Subagent journals are hidden

Retained children save their own journals with a parent_session_id. Root pickers, --continue, and kin ls omit them. Read child transcripts through the Agent Panel (Ctrl+O) or agent_output; an explicit kin --resume <child-id> can still open a saved child.

Session titles

The first user message is the default title. After about 120 seconds idle, Kin may generate a short title through a bounded model call. A failed title request leaves the default in place.

A conversation hosted for a local client — a browser home, or any client of the session service — titles itself the same way, once per opener, and only on an assigned Utility route. Without that assignment it keeps the first message: a name is not worth evicting the live model’s prompt cache. A rewrite that changes the opener — /compact, /clear, /rewind — earns one fresh title.

Persistent sessions with Herdr

Herdr owns terminal panes and live detach/reattach. Run Kin in a pane to leave the same process working while you disconnect. Kin reports working, blocked, and idle state; reporting failures do not fail a turn. While reporting is healthy, Herdr owns attention notifications.

After a server stop or reboot, recover from the journal with kin --resume <id>; native Kin cold restoration is not part of Herdr’s agent catalog. kin ls lists journals, not live panes.

For conversations whose lifetime belongs to a background service instead of a terminal pane, see local clients.

Legacy managed-session rescue

The old Kin-managed tmux runtime is retired. If kin doctor reports surviving sessions, inspect and attach to them with tmux -L kin ls and tmux -L kin attach -t <name>. Exit each useful Kin process before stopping the emptied server with tmux -L kin kill-server. Saved journals need no migration.

Rewind & retry

/rewind [n] [conversation|files|both] rolls back completed user turns (default: one turn, conversation only). Cuts follow user-turn boundaries; they never split a tool round.

Scope	Effect
conversation	Remove those turns from history and rewrite the journal.
files	Restore the checkpoint before those turns’ first edit; keep conversation history.
both	Restore files first, then remove the turns only if restoration succeeds.

files and both always require confirmation and take a protective snapshot of the current state before restoring. Without an eligible checkpoint they report no file changes to rewind. See file snapshots for coverage limits.

/retry sends the last user message again. A separate ↻ retry button appears when the first model request fails before tools run; it removes the failed turn before resending, avoiding a duplicate message. Failures after tools run have no retry button because replay could repeat side effects. Check the result and send a follow-up instead.

Rewind and retry are unavailable during a turn or compaction.

Double-Esc rewind picker

With an empty composer and no active turn or modal, press Esc twice within about a second. Choose a recent turn, then conversation, files, or both. Esc backs out; file restoration still requires confirmation.

The journal

Journals live at ~/.kin/projects/<workdir-slug>/<session-id>.jsonl. KIN_HOME relocates the global home; KIN_SESSION_DIR or the global session_dir setting relocates the projects tree.

The append-only JSONL stores provider-native messages and bounded state. Metadata identifies the workdir, provider, endpoint, model, and wire format. Optional runtime records describe observed source and model identity without request payloads; they are diagnostic observations, not restored settings or proof of loaded code after in-place edits. A torn final line is skipped and isolated before another append, including a partially written Unicode character. Malformed lines do not prevent surrounding complete records from loading. Records marked as requiring a newer Kin still refuse resume until you update.

The current envelope is v4. Kin saves tool intent and a dispatch marker before execution, then saves the result before the next model request. On interruption or crash recovery:

Result	Meaning and recovery
TOOL_NOT_STARTED	Dispatch never began. Reconsider the action against current state.
TOOL_OUTCOME_UNKNOWN	Dispatch began without a durable result. Check workspace or external state before retrying a side effect.

Kin does not automatically replay these calls or promise exactly-once execution. Interrupted legacy calls are outcome-unknown. A storage failure stops further execution; a failure after dispatch may leave changed state. Closing waits for owned workers before releasing the journal lease.

Compaction and pruning shadow old records instead of deleting them. Explicit clear, rewind, retry, and plan acceptance can rewrite history. Older journal formats remain readable.

Submitted text

A user message record may include user_text beside the provider-native message, not inside it. A string preserves the submitted text before file mention expansion, reminders, trimming, or client-context composition:

{"type":"message","seq":0,"user_text":"Read @notes.txt, then compare the two options.","message":{"role":"user","content":"…the existing reminders and expanded file content…"}}

The example abbreviates message.content; the real record keeps its existing complete content for model replay. user_text: null means known generated input with no original submission; an absent field means legacy or unknown. A reader can use the string directly, skip null, and retain its legacy fallback only where the field is absent. Do not strip literal reminder-like text or parse file renderings inside the string. It is caller provenance, not an attestation that a human authored an automated prompt.

Ordinary client turn.text and steer.text are captured before context is added. The terminal keeps a slash invocation rather than its rendered skill body. Headless stdin retains its original whitespace; when stdin and a positional instruction are both supplied, their raw strings are joined in stdin-first order by \n\n. The - stdin selector is not part of the text.

This additive field does not change journal version 4, old replay, or model input. It shares the journal’s privacy and no-save lifecycle. Surviving records retain it through resume, fork, rewind, and provider conversion; append-only compaction preserves originals. Existing rewrite fallback and explicit history-deletion semantics still apply.

History

/history [n] reads durable records, labeling each current, shadowed, or log-only; the default is 40 rows. Shadowed rows identify their replacements. Compaction receipts record the trigger, summarized volume, model, and usage; pruning receipts record elided results and characters reclaimed.

/tokens summarizes the same breakdown. Shadowed volume is reported in characters because an arbitrary slice of old records is not a countable provider conversation.

Export

/export [--full] [path] writes the saved transcript as Markdown, with tool calls and short result summaries. The default path is kin-export-<session-id>.md in the workspace. An existing output file is overwritten without confirmation. Export is unavailable during a turn or compaction.

--full includes shadowed history. Exports contain conversation text without sanitization; review them before sharing.

File snapshots

In Git workspaces, Kin checkpoints files before each turn’s first EDIT-kind tool call. It keeps the latest 20 checkpoints under refs/kin-snapshots/ without changing your index, HEAD, or branches. KIN_SNAPSHOTS=0 or snapshots = false disables this; outside Git it is a no-op.

Shell commands and run_code writes bypass this checkpoint trigger. Check git status and git diff before relying on a rewind to recover their work.

Terminal notifications

Kin signals when a turn lasting at least 15 seconds finishes or human input is needed. Interrupting does not notify. Notifications are debounced to one per 10 seconds and suppressed while focus is confirmed.

The signal is a terminal bell plus an OSC 9 desktop notification on supported terminals (Ghostty, iTerm2, WezTerm, kitty). Text uses fixed status phrases, never model output. Set KIN_NOTIFY=0 or notify = false to disable it. Headless completion notifies only when stderr is a terminal.

Compaction

/compact summarizes older history and keeps recent turns verbatim. Add a focus when useful:

/compact the auth refactor and the failing tests

Kin first prunes oversized completed tool results, retaining their call identity, error state, and any spill reference. Pruning needs no model call. If summarization is still needed, it uses a provider-native replay when safe and a flattened transcript otherwise. A summary that does not reduce history is refused. Both operations preserve their originals for /history and /export --full.

Setting	Default	Effect
compact_threshold / KIN_COMPACT_THRESHOLD	0.45	Auto-compact at this fraction of the window; clamped to 0.1–0.98, or 0 to disable.
compact_keep_turns / KIN_COMPACT_KEEP_TURNS	4	Recent turns to retain verbatim.
compact_keep_fraction	0.16	Token ceiling on the retained tail; nonpositive disables this bound.
prune_threshold_chars	8192	Oversized-result threshold; 0 disables pruning.
prune_head_chars / prune_tail_chars	4096 / 1024	Result content kept around the elision marker.

The token ceiling takes precedence over the retained-turn count, down to one turn. Exact-count pressure can tighten the estimated tail; repeated compaction is bounded to three attempts.

Hard prompt admission remains active when auto-compaction is off. Kin reserves response space before countable requests and can summarize completed history to fit. The live user input remains verbatim: if it cannot fit, Kin refuses the request with the measured prompt/output split. Context management stays local and reconstructable from the journal.

Context usage

The session line shows prompt usage against its hard admission ceiling, such as 100k / 195k. The ceiling reserves response space; it differs from both the full model window and the earlier auto-compact trigger. The reading stays blank until trustworthy usage arrives and resets on resume or session switch. It warns at 90% of the hard ceiling.

Hover for the prompt, window, output reserve, and compact trigger. /tokens adds available component counts, cache use, and cumulative usage. Component counts include framing and may not sum exactly. Count probes update context usage without charging generated-token spend. A backend without a counter can report only its available live usage.

Ephemeral runs

--no-save skips the journal, so the conversation cannot be resumed, rewound, or listed. It also has no journal crash-recovery guarantees.

Suppressing empty sessions

A new session with no user submission leaves no journal or task sidecar. Changing only its mode does not count as a submission. Resumed history is preserved even if you submit nothing new.

Old tool names in old journals

Dispatch aliases for view_file, view_notebook, and exit_plan keep old journals readable. Current model tool schemas expose the current names.

Troubleshooting

• Missing session: check the workspace; root lists omit children and unsaved runs.
• Resume refused: check for an existing owner, incompatible provider override, or changed endpoint credentials.
• Switch refused: finish the active turn or compaction and close the modal.
• Context crowded: compact, inspect /tokens, or fork before exploring a different direction.