Session state

Step 0: Gather project context

_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
_SLUG=$(basename "$_ROOT")
_BRANCH=$(git branch --show-current 2>/dev/null || echo "main")
_MEM="$_ROOT/memory"
mkdir -p "$_MEM" "$_MEM/sessions" "$_MEM/checkpoints" "$_MEM/retros" "$_MEM/reviews" "$_MEM/specs"
echo "=== Context: $_SLUG / $_BRANCH ==="
[ -f "$_MEM/context.md" ]      && echo "--- last context ---"     && tail -30 "$_MEM/context.md"
[ -f "$_MEM/learnings.jsonl" ] && echo "--- recent learnings ---" && tail -5  "$_MEM/learnings.jsonl"
[ -f "$_MEM/timeline.jsonl" ]  && echo "--- recent timeline ---"  && tail -5  "$_MEM/timeline.jsonl"

Memory dir (memory/): replaces gbrain. grep -r "X" memory/ ≡ gbrain search X · echo '...' >> memory/timeline.jsonl ≡ gbrain store

---

/context-save

/context-save — Save Working Context

You are a Staff Engineer who keeps meticulous session notes. Your job is to capture the full working context — what's being done, what decisions were made, what's left — so that any future session (even on a different branch or workspace) can resume without losing a beat via /context-restore.

HARD GATE: Do NOT implement code changes. This skill captures state only.

---

Detect command

Parse the user's input to determine the mode:

• /context-save or /context-save <title> → Save
• /context-save list → List

If the user provides a title after the command (e.g., /context-save auth refactor), use it as the title. Otherwise, infer a title from the current work.

If the user types /context-save resume or /context-save restore, tell them: "Use /context-restore instead — save and restore are separate skills now."

---

Save flow

Step 1: Gather state

eval "$(echo "$_SLUG" 2>/dev/null)" && mkdir -p $_MEM/projects/$SLUG

Collect the current working state:

echo "=== BRANCH ==="
git rev-parse --abbrev-ref HEAD 2>/dev/null
echo "=== STATUS ==="
git status --short 2>/dev/null
echo "=== DIFF STAT ==="
git diff --stat 2>/dev/null
echo "=== STAGED DIFF STAT ==="
git diff --cached --stat 2>/dev/null
echo "=== RECENT LOG ==="
git log --oneline -10 2>/dev/null

Step 2: Summarize context

Using the gathered state plus your conversation history, produce a summary covering:

1. What's being worked on — the high-level goal or feature
2. Decisions made — architectural choices, trade-offs, approaches chosen and why
3. Remaining work — concrete next steps, in priority order
4. Notes — anything a future session needs to know (gotchas, blocked items, open questions, things that were tried and didn't work)

If the user provided a title, use it. Otherwise, infer a concise title (3-6 words) from the work being done.

Step 3: Compute session duration

Try to determine how long this session has been active:

if [ -n "$_TEL_START" ]; then
  START_EPOCH="$_TEL_START"
elif [ -n "$PPID" ]; then
  START_EPOCH=$(ps -o lstart= -p $PPID 2>/dev/null | xargs -I{} date -jf "%c" "{}" "+%s" 2>/dev/null || echo "")
fi
if [ -n "$START_EPOCH" ]; then
  NOW=$(date +%s)
  DURATION=$((NOW - START_EPOCH))
  echo "SESSION_DURATION_S=$DURATION"
else
  echo "SESSION_DURATION_S=unknown"
fi

If the duration cannot be determined, omit the session_duration_s field from the saved file.

Step 4: Write saved-context file

Compute the path in bash (NOT in the LLM prompt) so user-supplied titles can't inject shell metacharacters into any subsequent command. The sanitizer is an allowlist: only a-z 0-9 - . survive.

eval "$(echo "$_SLUG" 2>/dev/null)" && mkdir -p $_MEM/projects/$SLUG
eval "$(# lrn-paths removed
CHECKPOINT_DIR="$_MEM/projects/$SLUG/checkpoints"
mkdir -p "$CHECKPOINT_DIR"
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
# Bash-side title sanitize. Pass the raw title as $1 when running this block.
# Example: TITLE_RAW="wintermute progress" bash -c '...'
RAW="${TITLE_RAW:-untitled}"
# Lowercase, collapse whitespace to hyphens, strip to allowlist, cap length.
TITLE_SLUG=$(printf '%s' "$RAW" | tr '[:upper:]' '[:lower:]' | tr -s ' \t' '-' | tr -cd 'a-z0-9.-' | cut -c1-60)
TITLE_SLUG="${TITLE_SLUG:-untitled}"
# Collision-safe filename: if ${TIMESTAMP}-${SLUG}.md already exists (same-second
# double save with same title), append a short random suffix. Filenames are
# append-only — never overwrite.
FILE="${CHECKPOINT_DIR}/${TIMESTAMP}-${TITLE_SLUG}.md"
if [ -e "$FILE" ]; then
  SUFFIX=$(LC_ALL=C tr -dc 'a-z0-9' < /dev/urandom 2>/dev/null | head -c 4 || printf '%04x' "$$")
  FILE="${CHECKPOINT_DIR}/${TIMESTAMP}-${TITLE_SLUG}-${SUFFIX}.md"
fi
echo "CHECKPOINT_DIR=$CHECKPOINT_DIR"
echo "TIMESTAMP=$TIMESTAMP"
echo "FILE=$FILE"

The on-disk directory name is checkpoints/ (not contexts/) — this is a legacy path kept so existing saved files remain loadable. Users never see it.

Write the file to the $FILE path printed above (use the exact string — do not reconstruct it in the LLM layer).

The file format:

---
status: in-progress
branch: {current branch name}
timestamp: {ISO-8601 timestamp, e.g. 2026-04-18T14:30:00-07:00}
session_duration_s: {computed duration, omit if unknown}
files_modified:
  - path/to/file1
  - path/to/file2
---

## Working on: {title}

### Summary

{1-3 sentences describing the high-level goal and current progress}

### Decisions Made

{Bulleted list of architectural choices, trade-offs, and reasoning}

### Remaining Work

{Numbered list of concrete next steps, in priority order}

### Notes

{Gotchas, blocked items, open questions, things tried that didn't work}

The files_modified list comes from git status --short (both staged and unstaged modified files). Use relative paths from the repo root.

After writing, confirm to the user:

CONTEXT SAVED
════════════════════════════════════════
Title:    {title}
Branch:   {branch}
File:     {path to saved file}
Modified: {N} files
Duration: {duration or "unknown"}
════════════════════════════════════════

Restore later with /context-restore.

---

List flow

Step 1: Gather saved contexts

eval "$(echo "$_SLUG" 2>/dev/null)" && mkdir -p $_MEM/projects/$SLUG
eval "$(# lrn-paths removed
CHECKPOINT_DIR="$_MEM/projects/$SLUG/checkpoints"
if [ -d "$CHECKPOINT_DIR" ]; then
  echo "CHECKPOINT_DIR=$CHECKPOINT_DIR"
  # Use find + sort instead of ls -1t: filename YYYYMMDD-HHMMSS prefix is the
  # canonical order (stable across copies/rsync; mtime is not), and empty-result
  # behavior is clean (no files → no output, no "lists cwd" fallback).
  find "$CHECKPOINT_DIR" -maxdepth 1 -name "*.md" -type f 2>/dev/null | sort -r
else
  echo "NO_CHECKPOINTS"
fi

Step 2: Display table

Default behavior: Show saved contexts for the current branch only.

If the user passes --all (e.g., /context-save list --all), show contexts from all branches.

Read the frontmatter of each file to extract status, branch, and timestamp. Parse the title from the filename (the part after the timestamp).

Present as a table:

SAVED CONTEXTS ({branch} branch)
════════════════════════════════════════
#  Date        Title                    Status
─  ──────────  ───────────────────────  ───────────
1  2026-04-18  auth-refactor            in-progress
2  2026-04-17  api-pagination           completed
3  2026-04-15  db-migration-setup       in-progress
════════════════════════════════════════

If --all is used, add a Branch column:

SAVED CONTEXTS (all branches)
════════════════════════════════════════
#  Date        Title                    Branch              Status
─  ──────────  ───────────────────────  ──────────────────  ───────────
1  2026-04-18  auth-refactor            feat/auth           in-progress
2  2026-04-17  api-pagination           main                completed
3  2026-04-15  db-migration-setup       feat/db-migration   in-progress
════════════════════════════════════════

If there are no saved contexts, tell the user: "No saved contexts yet. Run /context-save to save your current working state."

---

Important Rules

• Never modify code. This skill only reads state and writes the context file.
• Always include the branch name in frontmatter — critical for cross-branch /context-restore.
• Saved files are append-only. Never overwrite or delete existing files. Each save creates a new file.
• Infer, don't interrogate. Use git state and conversation context to fill in the file. Only use AskUserQuestion if the title genuinely cannot be inferred.
• This is a LRN skill, not a Claude Code built-in. When the user types /context-save, invoke this skill via the Skill tool. The old /checkpoint name collided with Claude Code's native /rewind alias — the rename fixed that.

---

/context-restore

/context-restore — Restore Saved Working Context

You are a Staff Engineer reading a colleague's meticulous session notes to pick up exactly where they left off. Your job is to load the most recent saved context and present it clearly so the user can resume work without losing a beat.

HARD GATE: Do NOT implement code changes. This skill only reads saved context files and presents the summary.

Default: load the most recent saved context across ALL branches. This is intentionally different from /context-save list, which defaults to the current branch. /context-restore is for Conductor workspace handoff — a context saved on one branch can be resumed from another.

Do NOT filter the candidate set by current branch. The list flow does that; /context-restore does not.

---

Detect command

Parse the user's input:

• /context-restore → load the most recent saved context (any branch)
• /context-restore <title-fragment-or-number> → load a specific saved context
• /context-restore list → tell the user "Use /context-save list — listing lives on the save side" and exit. No mode detection here.

---

Restore flow

Step 1: Find saved contexts

eval "$(echo "$_SLUG" 2>/dev/null)" && mkdir -p $_MEM/projects/$SLUG
eval "$(# lrn-paths removed
CHECKPOINT_DIR="$_MEM/projects/$SLUG/checkpoints"
if [ ! -d "$CHECKPOINT_DIR" ]; then
  echo "NO_CHECKPOINTS"
else
  # Use find + sort instead of ls -1t. Two reasons:
  # 1. Canonical order is the filename YYYYMMDD-HHMMSS prefix (stable across
  #    copies/rsync). Filesystem mtime drifts and is not authoritative.
  # 2. On macOS, `find ... | xargs ls -1t` with zero results falls back to
  #    listing cwd. `sort -r` on empty input cleanly returns nothing.
  # Cap at 20 most recent: a user with 10k saved files shouldn't blow the
  # context window just listing them. /context-save list handles pagination.
  FILES=$(find "$CHECKPOINT_DIR" -maxdepth 1 -name "*.md" -type f 2>/dev/null | sort -r | head -20)
  if [ -z "$FILES" ]; then
    echo "NO_CHECKPOINTS"
  else
    echo "$FILES"
  fi
fi

Candidates include every .md file in the directory, regardless of branch (the branch is recorded in frontmatter, not used for filtering here). This enables Conductor workspace handoff.

Step 2: Load the right file

• If the user specified a title fragment or number: find the matching file among the candidates.
• Otherwise: load the first file returned by the sort -r above — that is the newest YYYYMMDD-HHMMSS prefix, which is the canonical "most recent."

Read the chosen file and present a summary:

RESUMING CONTEXT
════════════════════════════════════════
Title:       {title}
Branch:      {branch from frontmatter}
Saved:       {timestamp, human-readable}
Duration:    Last session was {formatted duration} (if available)
Status:      {status}
════════════════════════════════════════

### Summary
{summary from saved file}

### Remaining Work
{remaining work items}

### Notes
{notes}

If the current branch differs from the saved context's branch, note this: "This context was saved on branch {branch}. You are currently on {current branch}. You may want to switch branches before continuing."

Step 3: Offer next steps

After presenting, ask via AskUserQuestion:

• A) Continue working on the remaining items
• B) Show the full saved file
• C) Just needed the context, thanks

If A, summarize the first remaining work item and suggest starting there.

---

If no saved contexts exist

If Step 1 printed NO_CHECKPOINTS, tell the user:

"No saved contexts yet. Run /context-save first to save your current working state, then /context-restore will find it."

---

Important Rules

• Never modify code. This skill only reads saved files and presents them.
• Always search across all branches by default. Cross-branch resume is the whole point. Only filter by branch if the user explicitly asks via a title-fragment match that happens to be branch-specific.
• "Most recent" means the filename YYYYMMDD-HHMMSS prefix, not ls -1t (filesystem mtime). Filenames are stable across file-system operations; mtime is not.
• This is a LRN skill, not a Claude Code built-in. When the user types /context-restore, invoke this skill via the Skill tool.

---

Merged from: memory

Memory Skills

|------|------| | SSOT | See references/ssot-initialization.md | | Plans.md | See references/plans-merging.md | | **** | See references/workflow-migration.md | | **** | See references/sync-project-specs.md | | →SSOT | See references/sync-ssot-from-memory.md |

Unified Harness MemoryDB

Claude Code / Codex / OpenCode harness_mem_* MCP

• : FRM_mem_search, FRM_mem_timeline, FRM_mem_get_observations
• : FRM_mem_resume_pack
• : FRM_mem_record_checkpoint, FRM_mem_finalize_session, FRM_mem_record_event

Claude Code D22

Harness SSOT Layer 2 Claude Code Layer 1 Layer 1 /memory ssot Layer 2

: D22: 3

SSOT

Claude-mem / SerenaSSOT

• "Save what we learned" → references/sync-ssot-from-memory.md
• "Promote decisions to SSOT" → references/sync-ssot-from-memory.md

---

Merged from: session

Session Skill (Unified)

Consolidates all session-related functionality into one skill.

Usage

/session              # Show available options
/session list         # Show active sessions
/session inbox        # Check incoming messages
/session broadcast "message"  # Send message to all sessions

Subcommands

/session list - List Active Sessions

Shows all active Claude Code sessions in the current project.

📋 Active Sessions

| Session ID | Status | Last Activity |
|------------|--------|---------------|
| abc123     | active | 2 min ago     |
| def456     | idle   | 15 min ago    |

/session inbox - Check Inbox

Checks for incoming messages from other sessions.

📬 Session Inbox

| From | Time | Message |
|------|------|---------|
| abc123 | 5m ago | "Ready for review" |
| def456 | 10m ago | "API implementation done" |

/session broadcast "message" - Broadcast Message

Sends a message to all active sessions.

/session broadcast "Review complete, ready for merge"

---

Capabilities

Feature	Description	Reference
Initialization	Start new session, load context	See ../session-init/SKILL.md
Memory	Persist learnings across sessions	See ../session-memory/SKILL.md
State Control	Resume/fork session based on flags	See references/session-control.md
Communication	Cross-session messaging	See ../session-state/SKILL.md

---

CC 2.1.49+

Claude Code 2.1.49 **68% **

|------------|---------| | **** | 1-2 --resume | | **** | /work all --resume | | **** | --resume |

CC 2.1.41+

claude
# → 1

claude --resume
# → 1

claude --resume

|---------|------| | **Plans.md ** | |

Codex 0.123.0 session shell / terminal

Codex 0.123.0 stale proxy env shell snapshot VS Code WSL terminal Unicode / dead-key input keyboard Harness proxy snapshot scrubber key input wrapper

---

When to Use

• Session initialization (/FRM-init)
• Session resume/fork (/work --resume, /work --fork)
• Memory persistence (automatic)
• Cross-session communication (/session broadcast)

Execution Flow

1. Session Initialization

/FRM-init
    ↓
├── Load project context
├── Initialize session.json
├── Load previous session memory (if exists)
└── Display session status

2. Session Control (from /work)

/work --resume
    ↓
├── Check session.json exists
├── Load session state
└── Continue from last checkpoint

/work --fork
    ↓
├── Create new session branch
├── Copy relevant context
└── Start fresh with context

3. Memory Persistence

Session end
    ↓
├── Extract learnings (gotchas, patterns)
├── Update .claude/memory/*.md
└── Prepare handoff summary

4. Cross-Session Communication

/session broadcast "message"
    ↓
├── Find active sessions
├── Write to session.events.jsonl
└── Notify all sessions

Files Managed

File	Purpose
.claude/state/session.json	Current session state
.claude/state/session.events.jsonl	Event log for cross-session communication
.claude/memory/*.md	Persistent memory files

Migration Note

This skill consolidates:

• session-init → Session initialization
• session-memory → Memory persistence
• session-control → Resume/fork control
• session-state → State management & communication

The individual skills are deprecated but still work for backward compatibility.