Claude Code Session Harness

A lightweight framework for maintaining continuity across multiple Claude Code sessions. Since each Claude Code conversation starts with a blank slate, this harness gives every new session the context it needs to pick up exactly where the last one left off.

The Problem

Claude Code has no memory between sessions. If you're building something that takes more than one conversation to complete, each new session starts from scratch — no knowledge of what was built, what broke, or what's next. You end up re-explaining context, re-discovering state, and risking duplicate or conflicting work.

How It Works

The harness uses three coordination files, a set of hooks, and slash commands to create a repeatable workflow:

your-project/
├── CLAUDE.md              # Rules Claude follows every session
├── claude-progress.txt    # Handoff log between sessions
├── feature-list.json      # Tracked features with pass/fail status
├── init.sh                # Idempotent environment setup script
└── .claude/
    ├── settings.json      # Hooks that enforce the protocol
    └── commands/
        ├── bootstrap.md   # /bootstrap - initialize a new project
        ├── wrap-up.md     # /wrap-up - end a session cleanly
        └── status.md      # /status - check project progress

The Session Lifecycle

1. Session Start — A hook fires automatically, showing feature progress and reminding Claude to run the startup ritual:

• Read claude-progress.txt for recent history
• Read feature-list.json for what's done and what's left
• Check git log for recent commits
• Run ./init.sh to get the environment into a known-good state
• Verify nothing is broken, then pick the next feature

2. Working — Claude works on one feature at a time, verifies it against the feature's defined steps, marks it as passing, and commits.

3. Session End — Before stopping, Claude writes a detailed handoff entry to claude-progress.txt with what was done, what's in progress, decisions made, and what the next session should do first. A hook warns if this step is skipped.

Core Files

feature-list.json

A JSON array of features, each with:

{
  "id": 1,
  "category": "auth",
  "description": "User can log in with email and password",
  "steps": [
    "Navigate to /login",
    "Enter valid credentials",
    "Verify redirect to dashboard"
  ],
  "passes": false,
  "depends_on": []
}

Features are immutable once written — descriptions and steps never change. The only permitted edit is flipping "passes": false to "passes": true after verification. A pre-tool-use hook enforces this by warning on any edit to the file.

claude-progress.txt

A reverse-chronological log of session handoffs. Each entry includes completed features, in-progress state, bugs found, decisions made, what the next session should tackle, and any blockers. Written for someone with zero context.

init.sh

An idempotent setup script that gets the environment into a known-good state. Safe to run repeatedly. Customized during bootstrap with project-specific setup (dependency installation, build steps, etc.).

CLAUDE.md

The rules document that Claude reads at the start of every session. Defines the startup ritual, working rules, session-end protocol, and guardrails.

Hooks (.claude/settings.json)

Three hooks enforce the protocol automatically:

Hook	Trigger	What It Does
SessionStart	Every new session	Reports feature progress, reminds Claude to run the startup ritual
Stop	Session ending	Warns if claude-progress.txt hasn't been updated in the last 5 minutes
PreToolUse	Any file edit	Warns when editing feature-list.json that only passes may change

Slash Commands

Command	Purpose
/bootstrap <description>	Initialize a new project — breaks requirements into features, sets up feature-list.json, updates init.sh with project-specific setup, then starts working
/wrap-up	End the session — commits all work, writes a handoff entry, confirms clean git status
/status	Report current progress — feature counts by category, latest handoff, what's next

Setup

The harness is already installed in this repo. To add it to a different project:

1. Copy the files into your project root:

   • CLAUDE.md
   • init.sh (make executable: chmod +x init.sh)
   • claude-progress.txt
   • feature-list.json

2. Copy the .claude/ directory:

   • .claude/settings.json
   • .claude/commands/bootstrap.md
   • .claude/commands/wrap-up.md
   • .claude/commands/status.md

3. Initialize git if not already a repo, and commit:

   git init
   git add -A
   git commit -m "Install session harness"

4. Bootstrap your project by starting a Claude Code session and running:

   /bootstrap <describe your project and its requirements here>
   

   This breaks your requirements into discrete features, populates feature-list.json, customizes init.sh, and starts working on the first feature.

Usage

Once bootstrapped, just start a Claude Code session in the project directory. The hooks and CLAUDE.md handle the rest — Claude will automatically orient itself, pick up where the last session left off, and continue working through features.

To check progress at any time: /status

To end a session cleanly: /wrap-up

Design Principles

• Everything is in files — no external databases, no hidden state. Git is the source of truth.
• Project-local — nothing is installed in ~/.claude. The harness lives entirely within the project directory and travels with the repo.
• Immutable feature specs — once a feature's description and steps are written, they don't change. This prevents scope drift and ensures every session is working against the same contract.
• Handoffs over memory — instead of trying to make Claude "remember," each session writes a detailed handoff that the next session reads. This is more reliable than any memory system.
• One feature at a time — prevents half-finished work scattered across multiple features. Complete, verify, commit, move on.