marathon

Infinite context sessions for Claude Code.

Two modes. Same result: Claude never loses context.

Auto mode (recommended)

Install once, then use claude normally. Marathon activates only when context gets large.

marathon install    # one-time setup
claude              # use normally — marathon kicks in when needed

Zero overhead for small tasks. When context triggers compaction, Claude is automatically told to write a handoff file. Next session picks up where it left off.

marathon status     # check if hooks are installed & any active handoffs
marathon uninstall  # remove hooks

Explicit mode

Wrap a task in marathon for guaranteed multi-session execution.

marathon "Refactor the entire auth module to use JWT tokens"

  marathon v0.2.0
  Infinite context sessions for Claude Code

  Task:      Refactor the entire auth module to use JWT tokens
  Max turns: 200 per leg
  Max legs:  50

[marathon leg 1/50] Starting...
[marathon] Leg 1 complete (tokens: 45000in/12000out, stop: end_turn)
[marathon] Handoff found. Continuing to next leg...

[marathon leg 2/50] Starting...
[marathon] Leg 2 complete (tokens: 38000in/9000out, stop: end_turn)
[marathon] Task complete after 2 leg(s)!

How it works

Auto mode (marathon install)

1. Adds hooks to Claude Code's ~/.claude/settings.json
2. PreCompact hook: When context is about to be compacted (signal that it's getting large), Claude is told to write .marathon/handoff.md with current progress
3. SessionStart hook: When a new session starts and a handoff file exists, Claude is given the context and picks up where it left off
4. Stop hook: When a task is marked complete, the handoff is archived

No wrapper, no extra commands. Just claude.

Explicit mode (marathon "task")

1. Marathon runs Claude Code with --print and a system prompt teaching the handoff protocol
2. Claude works normally, writing/updating .marathon/handoff.md as it goes
3. When the session ends (max turns or completion), marathon checks the handoff
4. If work remains, a new "leg" starts with the handoff context
5. Repeats until ## Status: COMPLETE or max legs reached

Each "leg" is a fresh session with full context budget.

Install

# Install globally via npm
npm install -g claude-marathon

# Enable auto mode (hooks into Claude Code)
marathon install

Or without npm:

git clone https://github.com/josephtandle/claude-marathon.git
ln -s $(pwd)/claude-marathon/bin/marathon /usr/local/bin/marathon
marathon install

Requirements: Claude Code (claude CLI), node, and jq

Usage

# Auto mode — install once, forget about it
marathon install

# Explicit mode — for specific tasks
marathon "Build a REST API for the user management system"
marathon -f tasks/migration-plan.md
marathon -m opus "Design and implement the caching layer"
marathon -t 100 -l 10 "Fix all TypeScript errors"
marathon -a "Bash,Read,Edit,Write,Glob,Grep" "Fix all lint errors"
marathon -p auto "Migrate database schema"

# Continue from an existing handoff
marathon continue

# Management
marathon status
marathon uninstall

Options (explicit mode)

| Flag | Description | Default | |------|-------------|---------| | -t, --max-turns <n> | Max turns per leg | 200 | | -l, --max-legs <n> | Max session legs | 50 | | -b, --max-budget <usd> | Budget per leg (USD) | unlimited | | -m, --model <model> | Model (opus, sonnet, etc.) | default | | -p, --permission-mode <mode> | Permission mode | default | | -a, --allowed-tools <tools> | Pre-approved tools | none | | -d, --work-dir <path> | Working directory | current | | -f, --file <path> | Read task from file | - | | -q, --quiet | Minimal output | false | | --dry-run | Preview without running | false |

Environment variables

export MARATHON_MAX_TURNS=150
export MARATHON_MAX_LEGS=20
export MARATHON_MAX_BUDGET=5.00
export MARATHON_MODEL=opus
export MARATHON_PERMISSION_MODE=auto
export MARATHON_ALLOWED_TOOLS="Bash,Read,Edit,Write,Glob,Grep"

The handoff file

Claude writes .marathon/handoff.md with this structure:

## Task
What we're trying to achieve

## Progress
What's been completed so far

## Current State
Where things stand right now

## Next Steps
1. Specific next actions
2. In order

## Key Context
File paths, decisions made, gotchas found

When the task is done, Claude adds ## Status: COMPLETE at the top, and the handoff is archived automatically.

Output files

.marathon/
  handoff.md          # Current handoff (auto mode + explicit mode)
  run.json            # Run metadata (explicit mode)
  summary.json        # Final summary (explicit mode)
  leg-1-result.json   # Claude output per leg (explicit mode)

Add .marathon/ to your .gitignore.

Recovery

If Claude hits max turns before writing a handoff, marathon creates a recovery handoff that tells the next session to check git status/git diff and continue.

FAQ

Does auto mode slow down normal sessions? No. The hooks only fire on specific events (PreCompact, SessionStart, Stop). PreCompact only fires when context is large enough to need compaction — small sessions never trigger it.

Can I use both modes? Yes. Auto mode handles interactive sessions. Explicit mode is better for headless/CI automation where you want the full loop.

What if I want to stop auto-continuation? Delete .marathon/handoff.md in your project, or run marathon uninstall to remove hooks entirely.

Does it work with subagents? The hooks only fire for the main session, not subagents. This is intentional — subagents have their own context management.

License

MIT