Development
ai-coding-agents-sessions
Designs session lifecycle for coding-agent runtimes. Use when implementing resume, transcript restoration, checkpoint rewind, cross-worktree recovery, or session-state persistence.
vasilyu1983 · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add vasilyu1983/AI-Agents-public --skill ai-coding-agents-sessionsAbout this skill
name: ai-coding-agents-sessions description: "Designs session lifecycle for coding-agent runtimes. Use when implementing resume, transcript restoration, checkpoint rewind, cross-worktree recovery, or session-state persistence." compatibility: Portable core. Works on Claude Code and Codex. version: "1.1" last_validated: 2026-07-11
AI Coding Agents Sessions
Use this skill to design or review the session lifecycle for a coding-agent runtime: session IDs, transcript persistence, resume pickers, stale-cache clearing, cross-worktree recovery, and what state must be restored versus recomputed.
This skill owns runtime session lifecycle. For persistent repo instructions and always-loaded memory, use ../agents-memory/SKILL.md.
ASCII Flow
new or resumed invocation
|
v
session identity
project + worktree + session_id + title + runtime mode
|
v
state restoration
transcript + summaries + tool state + task state + provider cache metadata
|
v
branch decision
continue | rewind | compact | clear | fork subagent | exact resume | claude agents (background resume)
|
v
active turn
append events, persist checkpoints, keep recovery path auditable
Quick Reference
| Question | Read | Outcome |
|---|---|---|
| What belongs in a coding-agent session model? | references/session-lifecycle-and-resume.md | Session IDs, picker flows, stale-cache reset, and resume semantics |
| How should transcripts recover across worktrees and summaries? | references/transcript-restoration-and-cross-worktree-recovery.md | Restoration boundaries, search, cross-project safeguards, and replay rules |
| How do users decide between continue / rewind / clear / compact / subagent at each turn? | references/context-lifecycle-and-branching.md | 1M-context branching model, context rot zone, rewind > correction, compact-vs-clear, bad-compact causes, subagent mental test |
| How do forked subagents change session lifecycle (cache, isolation, resume, cost)? | references/context-forking.md | Blank-vs-forked startup, CLAUDE_CODE_FORK_SUBAGENT=1 and /fork surfaces, cache-prefix economics, fork-as-exception rule |
| Which resume path should I use (session ID / picker / ACP re-attach / recipe re-seed)? | references/resume-path-decision-tree.md | Decision tree, path comparison table, prompt-cache economics in subagent spawning |
| How does OpenAI Codex split Session / Task / Turn protocol state? | references/openai-codex-session-task-turn-protocol.md | SQ/EQ protocol, response bookmarks, one-active-task invariant, and interruption rules |
| How does Codex persist, resume, fork, and cloud-resume sessions? | references/openai-codex-session-persistence.md | SQLite-backed session index, codex resume UUID lookup, codex fork branch semantics, codex cloud task-apply |
When To Use
- Design resume and continue flows for a coding-agent CLI
- Decide how session IDs, titles, or logs map to recovery behavior
- Restore transcripts, summaries, or worktree-bound state safely
- Build interactive resume pickers or exact-match resume commands
- Separate project memory from session memory and transcript state
Use Other Skills
| Need | Use Instead |
|---|---|
| Persistent repo instructions and shared memory files | ../agents-memory/SKILL.md |
| Remote execution or bridge sessions | ../ai-coding-agents-remote-runtime/SKILL.md |
| Background task lifecycle | ../ai-coding-agents-tasks/SKILL.md |
Default Workflow
- Define session identity first. Use a stable session ID and keep title or search aliases as secondary lookup keys.
- Split restoreable from recomputable state. Persist transcripts, summaries, and user-visible session identity; recompute caches and discovery indexes after resume.
- Clear stale discovery caches before restore. Resume should not inherit old file, skill, or config caches.
- Support both exact and interactive recovery. Resume should work by UUID, exact title match, and picker/search fallback.
- Treat worktree and project boundaries explicitly. Same-repo worktrees can often resume directly or adopt the worktree; different projects should route through an explicit user command.
- Use fallback lookup order deliberately. Enriched session indexes may fail; direct log or transcript lookup should exist as a second path before the runtime declares a session missing.
- Restore summary state, not just raw logs. Transcript collapse, synthesized summaries, and lightweight cost or usage state should survive resume even if the visible REPL list is truncated.
- Test failure paths. Verify missing sessions, multiple title matches, stale worktree paths, interrupted resume, index miss with direct-log fallback, and cross-project recovery.
Host Rules
- Session lifecycle is runtime state, not project memory.
- Resume should restore only state that is safe to trust from storage.
- Search aliases and custom titles are convenience layers on top of session IDs.
- Cross-project resume must be explicit and reviewable.
- Same-repo worktree adoption and cross-project resume should follow different code paths.
- Resume should clear stale discovery caches before rebuilding live runtime state.
- If enriched indexes miss a session, the runtime should have a direct-log or transcript fallback before failing hard.
- Picker flows should exclude the current session and sidechain-only artifacts.
Build Order
- Define stable session ide