Keep Session

keep-session — Session continuity ledger (SESSION_LOG + dual bootstrap)

Why this exists

Agent sessions die — crashes, context-window exhaustion, an accidental /clear, or the user simply returning days later. Each time, a fresh session reconstructs project state by grepping files and quizzing the user: slow, lossy, error-prone. This skill removes that problem with a small file set:

| File | Role | Reader | |---|---|---| | SESSION_LOG.md | State ledger — snapshot, context digest, pointers, policies, log | The agent (next session) | | CLAUDE.md | Bootstrap — auto-loaded on directory entry; forces reading the ledger first | Claude Code | | AGENTS.md | Same bootstrap for harnesses that read AGENTS.md | Codex, Cursor, etc. |

The ledger is harness-neutral. Whatever coding agent the user continues with (Claude Code → Codex or the reverse), the same ledger restores the same context — which is why the bootstrap is installed into both CLAUDE.md and AGENTS.md with identical content.

Key insight: even when a project already has human-facing docs (tracker, README), the agent needs its own ledger. Human docs record what happened; an agent that must act immediately needs system pointers (ticket/CRM IDs, Slack channel/draft IDs, email thread subjects, scheduled-send times, external file paths) and the exact state of unfinished actions. Those rarely survive in human docs.

Language: this skill file is English for token efficiency, but write the generated artifacts (SESSION_LOG.md, bootstrap files) in the user's working language — the ledger is read by future sessions serving the same user.

Operation 1: init — set up

When the user asks to "set up a SESSION_LOG", "make this directory session-persistent", etc.:

1-1. Identify the entry scenario, then capture state

init happens in two situations. Tell them apart from the directory contents and the conversation history:

(A) Mid-project — the directory already has files/history. Skim the files, and use the current conversation history if available, to reconstruct the present state. Capture:

• In-flight work and next actions (unfinished items matter most)
• System IDs: ticket/CRM IDs, Slack channel/message/draft IDs, email thread

subjects + send dates, external file paths (meeting notes, memory files), scheduled events (scheduled sends, meetings)

• Project-local policies (working rules the user has agreed to)
• The role of each file in the directory

If there is no conversation history and the files leave the state unclear, do not fill gaps with guesses. Ask the user short, targeted questions (next action, pending external events). If asking is impractical right now, add an "Unresolved items" section to the SESSION_LOG listing the open questions — when a later session (or a user answer) resolves one, fold it into the proper section, remove it from the list, and log the change. Mark unresolved items as unverified in the snapshot too, so they never read as confirmed facts.

(B) Day-one — an empty (or nearly empty) directory being set up for upcoming work. There is no past to reconstruct, so ask the user only for:

• A one-line description of the project (purpose, counterpart, deliverable)
• The first action

Start the snapshot/context sections minimal, and keep the file inventory and system pointers as empty scaffolds — the full section structure stays in place and fills in naturally through the update rules (Operation 2). The value of day-one setup is not the content; it is that the update habit runs from day one.

1-2. Write SESSION_LOG.md

Use this six-section structure (battle-tested; keep it, though sections may be adapted to the project). Write it in the user's working language:

# SESSION_LOG — 

> **Purpose**: single-file context restore so any new agent session (Claude Code, Codex,
> etc.) can continue immediately.
> **Update rule**: after every meaningful action, append to the update log and refresh
> the snapshot.

## 1. Current-status snapshot (as of YYYY-MM-DD)

## 2. Context digest

## 3. File inventory (this directory)

## 4. System pointers (per-tool IDs/paths)

## 5. Policies & agreements (project-local)

## 6. Update log (newest first)
- **YYYY-MM-DD**: 

Section 4 (system pointers) is the highest-value section — invest there. Not "shared to Slack" but "Slack draft DrXXXXXXXX → channel CXXXXXXXXXX, scheduled send Mon 09:00" — precise enough for the next session to feed straight into tool calls.

1-3. Install the bootstrap — CLAUDE.md + AGENTS.md dual

Write the bootstrap content once, then install it identically into both CLAUDE.md and AGENTS.md. Claude Code auto-loads CLAUDE.md; Codex/Cursor and others auto-load AGENTS.md; both must exist for resume to work under any harness.

Caution: if the target directory already has a CLAUDE.md or AGENTS.md, never overwrite it. Read the existing content and merge the bootstrap section in (append or insert where it fits). Only create files that don't exist.

#  — session bootstrap

## On session start (required)
1. **Read `SESSION_LOG.md` first** — the session-continuity ledger holding current
   status, system pointers, and in-flight actions
2. 

## While working (required)
- After every meaningful action (outbound communication, file create/edit, decision),
  **update SESSION_LOG.md immediately**:
  - refresh the "current-status snapshot"
  - append a dated entry to the "update log" (newest first)
  - add any new system IDs to "system pointers"
- If this bootstrap itself is edited, keep CLAUDE.md and AGENTS.md **in sync**

Keep the bootstrap and ledger wording harness-neutral — say "a new session" or "an agent session", never "a CC session".

1-4. Record the first log entry

Log the creation of the SESSION_LOG itself as the first (or newest) update-log entry.

How updates actually run: resident rule, not skill invocation

After init, the maintenance loop needs no explicit skill invocation. The bootstrap installed into CLAUDE.md/AGENTS.md is a resident rule: it auto-loads on every session start in that directory and instructs the session to update the ledger after each meaningful action. The skill's job was planting that rule; from then on, every session — any harness — self-maintains the ledger as a side effect of normal work. If a user asks "do I need to run keep-session each time?", the answer is no.

Explicit invocation after init = an audit pass. When the user does invoke the skill on an already-initialized directory, don't re-init — treat it as a request to find and fix ledger gaps. The highest-yield blind spot, observed in practice: in multi-session orchestration (e.g., a local session directing remote developer/reviewer sessions), each session records its own work faithfully, but the orchestration context that belongs to no single session — which external replies are pending and where each reply slots into the code, why a remote agent is intentionally paused at an approval gate, which session holds which role — ends up in no one's ledger. On an audit pass, specifically hunt for such orchestrator-only context and write it into the snapshot.

Good moments to suggest (or for the user to request) an audit pass:

• Right after a phase transition that rewires who-does-what (dev-environment handoff,

entering an external-wait state, a new agent joining)

• Before the user steps away for days — so any future session restores from the

top block alone

Operation 2: update — continuous refresh

Every session working in a directory where this skill is installed updates the SESSION_LOG (per the bootstrap) at these moments:

• Outbound communication (email sent, Slack posted, ticket filed)
• File creation or significant edits
• Decisions/policy agreements with the user
• Scheduled events set up (scheduled sends, confirmed meetings)

Update principles:

1. Snapshot is replaced; log is appended — rewrite §1 as of "now" and bump the as-of

date; never delete §6 entries, only stack new ones on top

1. New IDs go into §4 immediately — "later" means forgotten. The moment a draft ID,

task ID, or conversation ID exists, record it

1. Stay lean — snapshot ~15 lines, log entries 1–3 lines. Details live in the

human-facing doc (tracker etc.); the ledger holds pointers

1. Update human docs in the same breath — if a tracker exists, update both (division

of labor: tracker = human-facing dashboard, SESSION_LOG = agent-facing ledger)

Operation 3: resume — restore in a fresh session

When a new session opens in the directory, the bootstrap (CLAUDE.md for Claude Code, AGENTS.md for Codex etc.) auto-loads and points at the SESSION_LOG. Resume order:

1. Read SESSION_LOG.md thoroughly — especially §1's top-priority action and §4 pointers
2. Compare the as-of date with today — a gap of days+ means the snapshot may be

stale. For time-dependent items (scheduled sends, meetings), verify with tools whether they actually happened, then reflect the findings in the log. Never assume an elapsed event succeeded

1. Deepen with the human-facing main doc (tracker etc.)
2. Confirm with the user: "per the SESSION_LOG, current state is X, next action is Y" —

then continue

If a pointer is broken (file moved, ID expired), don't silently skip it — fix the SESSION_LOG and tell the user.

What NOT to do

• Don't duplicate human-doc content wholesale into the ledger — pointers suffice
• Don't retro-edit log entries — correct mistakes with a new dated entry
• Don't overwrite an existing CLAUDE.md/AGENTS.md — merge only
• Don't put secrets or verbatim confidential content in the ledger — location pointers only

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jesamkim
• Source: jesamkim/oh-my-skills
• License: MIT

Install and usage instructions live in the source repository linked above.