Session Persistence
Kangentic persists every agent session to a local SQLite database. Sessions survive application crashes, system restarts, and intentional suspension. You never lose work.
How Persistence Works
Section titled “How Persistence Works”Every interaction between Kangentic and the agent CLI is stored in real-time:
- Conversation history — The full prompt and response chain
- Session metadata — Start time, status, worktree path, branch name
- Terminal output — Raw terminal data for replay
- Task state — Board position, description, and user notes
Data is written incrementally as the agent works, not just when the session ends. If the application crashes mid-session, the data up to that point is preserved.
Session States
Section titled “Session States”| State | Description |
|---|---|
| Running | Agent is actively working. Session data is being written in real-time. |
| Suspended | Agent was intentionally paused (by user or system). Full state is preserved for resume. |
| Exited | Agent process terminated (finished, errored, or crashed). Check exit_code for details. |
| Orphaned | Session was running when the application closed unexpectedly. Recoverable on next launch. |
Crash Recovery
Section titled “Crash Recovery”When Kangentic starts, it checks for sessions that were in a “Running” state when the application last closed. These are marked as crashed and can be:
- Resumed — Relaunch the agent with the full conversation context. The agent picks up where it left off.
- Archived — Keep the session data but don’t resume. Useful if the task is no longer relevant.
User-Paused Sessions
Section titled “User-Paused Sessions”Sessions paused manually by the user (via the pause button in the task detail dialog or the kebab menu) are remembered across restarts. On relaunch, user-paused sessions remain paused instead of auto-resuming. This respects user intent — if you paused an agent, it will not start back up on its own. Only system-suspended sessions (those suspended by shutdown or column moves) auto-resume.
Resuming Sessions
Section titled “Resuming Sessions”When you resume a suspended or crashed session, Kangentic:
- Reads the full conversation history from the database
- Recreates the agent session with the stored native session ID (via each CLI’s native resume flag)
- Reconnects the terminal to the new process
- The agent continues working with full awareness of previous context
The agent sees the same conversation it had before, so it can continue its work without repeating steps or losing context.
Resume matrix:
| Agent | Resume | Mechanism |
|---|---|---|
| Claude Code | ✓ | Kangentic supplies a caller-controlled session ID via --resume for deterministic re-entry |
| Codex CLI | ✓ | codex resume <id> with the CLI-generated rollout ID |
| Gemini CLI | ✓ | --resume <id> against the auto-generated chat session file |
| Cursor CLI | ✓ | agent --resume=<id> using the session ID captured from the init event on Cursor’s stream-JSON output |
| GitHub Copilot CLI | ✓ | Kangentic supplies a caller-controlled UUID via --resume <uuid> (same semantics as Claude) |
| Aider | — | Edit-first and relaunched fresh. Prior edits are still on the worktree, but conversation history is not carried over |
| Warp (Oz CLI) | — | oz does not expose a session-resume mechanism. Re-entry starts a new session in the preserved worktree |
Kangentic preserves terminal scrollback across resume so you still see the prior session’s output.
State Machine and Locking
Section titled “State Machine and Locking”Added in v0.15.0. Every session lifecycle transition (spawn, suspend, resume, kill, queue-promote) runs through an atomic state machine with a per-task lock. The lock prevents two transitions from interleaving on the same task, which was the root cause of several pause/resume race conditions before v0.15.0: a rapid drag could trigger a spawn while a prior kill was still cleaning up, leaving a half-alive session. Now a move that arrives while the task is mid-transition is queued until the current transition completes, then either executes or is coalesced with the target state if it became redundant.
The state machine also coordinates with the concurrency queue: if a spawn transition finishes by placing the session in the queue (because the max-concurrent limit is reached), queue promotion runs under the same lock so a later manual suspend doesn’t race with an automatic promotion.
Session History
Section titled “Session History”All completed and archived sessions are kept in the database. You can:
- Browse past sessions from the task card
- View the full conversation and terminal output
- See what files the agent modified
- Re-read the agent’s reasoning and decisions
This creates a searchable history of all agent work done in your project.
Storage
Section titled “Storage”Session data is stored in .kangentic/kangentic.db at the root of your repository. This is a SQLite database that you should add to your .gitignore (Kangentic does this automatically on first run).