claude-marathon 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 marathon contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,193 @@
+# 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.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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
+
+```bash
+# Install globally via npm
+npm install -g claude-marathon
+
+# Enable auto mode (hooks into Claude Code)
+marathon install
+```
+
+Or without npm:
+
+```bash
+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](https://docs.anthropic.com/en/docs/claude-code) (`claude` CLI), `node`, and `jq`
+
+## Usage
+
+```bash
+# 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
+
+```bash
+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:
+
+```markdown
+## 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

package/bin/marathon

@@ -0,0 +1,690 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# marathon - Infinite context sessions for Claude Code
+# https://github.com/anthropics/marathon
+#
+# When context gets large, Claude writes a handoff file, the session ends,
+# and a new session picks up right where it left off. Automatically.
+
+VERSION="0.2.0"
+# Resolve symlinks to find the actual install directory
+_resolve_script() {
+  local src="${BASH_SOURCE[0]}"
+  while [[ -L "$src" ]]; do
+    local dir="$(cd "$(dirname "$src")" && pwd)"
+    src="$(readlink "$src")"
+    [[ "$src" != /* ]] && src="$dir/$src"
+  done
+  cd "$(dirname "$src")/.." && pwd
+}
+SCRIPT_DIR="$(_resolve_script)"
+MARATHON_DIR=".marathon"
+CLAUDE_SETTINGS="${HOME}/.claude/settings.json"
+HOOKS_DIR="${HOME}/.claude/hooks"
+MAX_TURNS="${MARATHON_MAX_TURNS:-200}"
+MAX_LEGS="${MARATHON_MAX_LEGS:-50}"
+MAX_BUDGET="${MARATHON_MAX_BUDGET:-}"
+MODEL="${MARATHON_MODEL:-}"
+PERMISSION_MODE="${MARATHON_PERMISSION_MODE:-}"
+ALLOWED_TOOLS="${MARATHON_ALLOWED_TOOLS:-}"
+WORK_DIR="${MARATHON_WORK_DIR:-.}"
+QUIET=false
+DRY_RUN=false
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+DIM='\033[2m'
+BOLD='\033[1m'
+NC='\033[0m'
+
+usage() {
+  cat <<'EOF'
+marathon - Infinite context sessions for Claude Code
+
+USAGE:
+  marathon [options] "your task description"
+  marathon [options] -f task.md
+  marathon install       Install hooks for automatic mode
+  marathon uninstall     Remove marathon hooks
+  marathon status        Show if hooks are installed & any active handoffs
+  marathon continue      Continue from an existing handoff file
+
+OPTIONS:
+  -t, --max-turns <n>     Max turns per leg (default: 200)
+  -l, --max-legs <n>      Max session legs before stopping (default: 50)
+  -b, --max-budget <usd>  Max budget in USD per leg
+  -m, --model <model>     Model to use (e.g., opus, sonnet)
+  -p, --permission-mode <mode>  Permission mode (default, plan, auto, etc.)
+  -a, --allowed-tools <tools>   Comma-separated tools to pre-approve
+  -d, --work-dir <path>   Working directory (default: current)
+  -f, --file <path>       Read task from file instead of argument
+  -q, --quiet             Minimal output (no banner, less logging)
+  --dry-run               Show what would run without executing
+  -v, --version           Show version
+  -h, --help              Show this help
+
+ENVIRONMENT VARIABLES:
+  MARATHON_MAX_TURNS       Default max turns per leg
+  MARATHON_MAX_LEGS        Default max legs
+  MARATHON_MAX_BUDGET      Default budget per leg
+  MARATHON_MODEL           Default model
+  MARATHON_PERMISSION_MODE Default permission mode
+  MARATHON_ALLOWED_TOOLS   Default allowed tools
+  MARATHON_WORK_DIR        Default working directory
+
+EXAMPLES:
+  # Explicit mode - wrap a task in marathon
+  marathon "Refactor the auth module to use JWT"
+  marathon -t 100 -l 10 -m opus "Build the entire test suite"
+  marathon -f tasks/migration.md --permission-mode auto
+
+  # Auto mode - install hooks, then use claude normally
+  marathon install
+  claude   # marathon activates automatically when context gets large
+
+HOW IT WORKS:
+
+  Explicit mode (marathon "task"):
+    Marathon runs Claude in a loop. Each "leg" is a fresh session.
+    Claude writes a handoff file, marathon reads it, starts a new session.
+
+  Auto mode (marathon install):
+    Hooks are added to Claude Code that fire automatically:
+    - PreCompact: When context is about to be compacted, Claude is told
+      to write a handoff file. Zero overhead until this point.
+    - SessionStart: If a handoff file exists from a previous session,
+      Claude is given the context and picks up where it left off.
+    No wrapper needed. Just use claude normally.
+
+EOF
+  exit 0
+}
+
+# ─── Subcommands ──────────────────────────────────────────────────────────────
+
+cmd_install() {
+  echo -e "${BOLD}marathon install${NC}"
+  echo ""
+
+  # Ensure hooks dir exists
+  mkdir -p "$HOOKS_DIR"
+
+  # Copy hooks script
+  local hook_src="$SCRIPT_DIR/hooks/marathon-hooks.js"
+  local hook_dst="$HOOKS_DIR/marathon-hooks.js"
+
+  if [[ ! -f "$hook_src" ]]; then
+    log_error "Hook script not found at $hook_src"
+    log_error "Make sure you're running from the marathon directory or it's properly installed."
+    exit 1
+  fi
+
+  cp "$hook_src" "$hook_dst"
+  echo -e "  ${GREEN}+${NC} Copied hooks to $hook_dst"
+
+  # Update settings.json
+  if [[ ! -f "$CLAUDE_SETTINGS" ]]; then
+    echo '{}' > "$CLAUDE_SETTINGS"
+  fi
+
+  # Read current settings
+  local settings
+  settings=$(cat "$CLAUDE_SETTINGS")
+
+  # Check if marathon hooks already installed
+  if echo "$settings" | jq -e '.hooks.PreCompact[]?.hooks[]? | select(.command | contains("marathon-hooks.js"))' &>/dev/null; then
+    echo -e "  ${DIM}Hooks already installed, updating...${NC}"
+  fi
+
+  # Remove any existing marathon hooks first (idempotent install)
+  # Use a node one-liner since jq gets tricky with nested hook structures
+  settings=$(node -e "
+    const s = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
+    if (s.hooks) {
+      for (const [event, matchers] of Object.entries(s.hooks)) {
+        if (!Array.isArray(matchers)) continue;
+        s.hooks[event] = matchers.filter(m => {
+          if (Array.isArray(m.hooks)) {
+            m.hooks = m.hooks.filter(h => !(h.command || '').includes('marathon-hooks.js'));
+            return m.hooks.length > 0;
+          }
+          return true;
+        });
+        if (s.hooks[event].length === 0) delete s.hooks[event];
+      }
+      if (Object.keys(s.hooks).length === 0) delete s.hooks;
+    }
+    process.stdout.write(JSON.stringify(s, null, 2));
+  " <<< "$settings")
+
+  # Add marathon hooks for PreCompact, SessionStart, and Stop
+  local hook_cmd="node \"$hook_dst\""
+
+  settings=$(echo "$settings" | jq --arg cmd "$hook_cmd" '
+    .hooks //= {} |
+
+    .hooks.PreCompact //= [] |
+    .hooks.PreCompact += [{
+      "hooks": [{
+        "type": "command",
+        "command": ($cmd + " PreCompact")
+      }]
+    }] |
+
+    .hooks.SessionStart //= [] |
+    .hooks.SessionStart += [{
+      "hooks": [{
+        "type": "command",
+        "command": ($cmd + " SessionStart")
+      }]
+    }] |
+
+    .hooks.Stop //= [] |
+    .hooks.Stop += [{
+      "hooks": [{
+        "type": "command",
+        "command": ($cmd + " Stop")
+      }]
+    }]
+  ')
+
+  echo "$settings" | jq '.' > "$CLAUDE_SETTINGS"
+  echo -e "  ${GREEN}+${NC} Added hooks to $CLAUDE_SETTINGS"
+
+  echo ""
+  echo -e "${GREEN}${BOLD}Marathon auto mode installed.${NC}"
+  echo ""
+  echo "How it works:"
+  echo "  1. Use claude normally — zero overhead for small tasks"
+  echo "  2. When context gets large enough to trigger compaction,"
+  echo "     Claude is told to write a handoff file (.marathon/handoff.md)"
+  echo "  3. Next time you start claude in the same directory,"
+  echo "     it automatically picks up from the handoff"
+  echo ""
+  echo "That's it. No wrapper needed."
+  echo ""
+  echo "To uninstall: marathon uninstall"
+  exit 0
+}
+
+cmd_uninstall() {
+  echo -e "${BOLD}marathon uninstall${NC}"
+  echo ""
+
+  # Remove hooks from settings
+  if [[ -f "$CLAUDE_SETTINGS" ]]; then
+    local settings
+    settings=$(cat "$CLAUDE_SETTINGS")
+
+    settings=$(node -e "
+      const s = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
+      if (s.hooks) {
+        for (const [event, matchers] of Object.entries(s.hooks)) {
+          if (!Array.isArray(matchers)) continue;
+          s.hooks[event] = matchers.filter(m => {
+            if (Array.isArray(m.hooks)) {
+              m.hooks = m.hooks.filter(h => !(h.command || '').includes('marathon-hooks.js'));
+              return m.hooks.length > 0;
+            }
+            return true;
+          });
+          if (s.hooks[event].length === 0) delete s.hooks[event];
+        }
+        if (Object.keys(s.hooks).length === 0) delete s.hooks;
+      }
+      process.stdout.write(JSON.stringify(s, null, 2));
+    " <<< "$settings")
+
+    echo "$settings" | jq '.' > "$CLAUDE_SETTINGS"
+    echo -e "  ${GREEN}-${NC} Removed hooks from $CLAUDE_SETTINGS"
+  fi
+
+  # Remove hook script
+  local hook_dst="$HOOKS_DIR/marathon-hooks.js"
+  if [[ -f "$hook_dst" ]]; then
+    rm "$hook_dst"
+    echo -e "  ${GREEN}-${NC} Removed $hook_dst"
+  fi
+
+  echo ""
+  echo -e "${GREEN}Marathon auto mode uninstalled.${NC}"
+  echo "You can still use marathon explicitly: marathon \"your task\""
+  exit 0
+}
+
+cmd_status() {
+  echo -e "${BOLD}marathon status${NC}"
+  echo ""
+
+  # Check hooks
+  local hooks_installed=false
+  if [[ -f "$CLAUDE_SETTINGS" ]] && jq -e '.hooks.PreCompact[]?.hooks[]? | select(.command | contains("marathon-hooks.js"))' "$CLAUDE_SETTINGS" &>/dev/null; then
+    hooks_installed=true
+  fi
+
+  if [[ "$hooks_installed" == true ]]; then
+    echo -e "  Auto mode: ${GREEN}installed${NC}"
+  else
+    echo -e "  Auto mode: ${DIM}not installed${NC} (run 'marathon install')"
+  fi
+
+  # Check for active handoff
+  if [[ -f "$MARATHON_DIR/handoff.md" ]]; then
+    local first_line
+    first_line=$(head -5 "$MARATHON_DIR/handoff.md" | tr '[:upper:]' '[:lower:]')
+    if echo "$first_line" | grep -q "status:.*complete"; then
+      echo -e "  Handoff:   ${GREEN}complete${NC} (.marathon/handoff.md)"
+    else
+      echo -e "  Handoff:   ${YELLOW}active${NC} (.marathon/handoff.md)"
+      echo ""
+      echo -e "  ${DIM}Next 'claude' session will auto-continue from this handoff.${NC}"
+      echo -e "  ${DIM}Or run: marathon continue${NC}"
+    fi
+  else
+    echo -e "  Handoff:   ${DIM}none${NC}"
+  fi
+
+  # Check for run history
+  if [[ -f "$MARATHON_DIR/summary.json" ]]; then
+    local legs total_in total_out
+    legs=$(jq -r '.legs // "?"' "$MARATHON_DIR/summary.json" 2>/dev/null)
+    total_in=$(jq -r '.total_input_tokens // 0' "$MARATHON_DIR/summary.json" 2>/dev/null)
+    total_out=$(jq -r '.total_output_tokens // 0' "$MARATHON_DIR/summary.json" 2>/dev/null)
+    echo -e "  Last run:  ${legs} legs, ${total_in} in / ${total_out} out tokens"
+  fi
+
+  echo ""
+  exit 0
+}
+
+cmd_continue() {
+  if [[ ! -f "$MARATHON_DIR/handoff.md" ]]; then
+    log_error "No handoff file found at $MARATHON_DIR/handoff.md"
+    log_error "Nothing to continue."
+    exit 1
+  fi
+
+  # Read handoff as the task
+  local handoff_content
+  handoff_content=$(cat "$MARATHON_DIR/handoff.md")
+
+  TASK=$(cat <<EOF
+You are continuing a task from a previous session. Here is the handoff:
+
+---
+$handoff_content
+---
+
+Pick up where the previous session left off. Follow the "Next Steps" above.
+Update .marathon/handoff.md as you make progress.
+When the task is fully complete, add "## Status: COMPLETE" at the top.
+EOF
+)
+
+  # Fall through to the main marathon loop below
+}
+
+log() {
+  [[ "$QUIET" == true ]] && return
+  echo -e "${DIM}[marathon]${NC} $*"
+}
+
+log_leg() {
+  echo -e "${BLUE}${BOLD}[marathon leg $1/$MAX_LEGS]${NC} $2"
+}
+
+log_done() {
+  echo -e "${GREEN}${BOLD}[marathon]${NC} $1"
+}
+
+log_warn() {
+  echo -e "${YELLOW}[marathon]${NC} $1"
+}
+
+log_error() {
+  echo -e "${RED}[marathon]${NC} $1" >&2
+}
+
+# The system prompt injected into each session
+marathon_system_prompt() {
+  cat <<'PROMPT'
+## Marathon Auto-Continuation Protocol
+
+You are running inside **marathon**, an auto-continuation wrapper. This means when your context gets large, you can hand off to a fresh session that will continue your work.
+
+### How it works:
+1. You do your work normally
+2. When you sense context is getting large (many tool calls, large file reads, deep into a task), proactively write a handoff file
+3. Your session will end (via max-turns or natural completion), and marathon will start a new session with your handoff
+
+### Writing a handoff:
+When you need to hand off, write the file `.marathon/handoff.md` with this structure:
+
+```markdown
+## Task
+[Original task / goal - what are we trying to achieve]
+
+## Progress
+[What has been completed so far - be specific about files changed, decisions made]
+
+## Current State
+[Where things stand right now - what was the last thing done]
+
+## Next Steps
+[Exactly what needs to happen next - ordered list, be specific]
+
+## Key Context
+[Important details the next session needs to know - file paths, patterns found, gotchas discovered, architectural decisions]
+```
+
+### Rules:
+- Write the handoff **proactively** - don't wait until you're forced to stop
+- Be specific in the handoff - the next session has NO memory of this one
+- Include file paths, function names, error messages - anything concrete
+- If the task is **fully complete**, write the handoff with `## Status: COMPLETE` at the top and summarize what was done
+- Update the handoff file as you make progress, so it's always current even if the session ends unexpectedly
+- The handoff file is your ONLY way to communicate with the next session
+
+### Important:
+- You are leg MARATHON_LEG_NUMBER of up to MARATHON_MAX_LEGS legs
+- Each leg has up to MARATHON_MAX_TURNS turns
+- Don't rush - do quality work. Marathon gives you unlimited context.
+- After ~70% of your turns, start writing/updating the handoff file
+PROMPT
+}
+
+# Handle subcommands first
+case "${1:-}" in
+  install)   cmd_install ;;
+  uninstall) cmd_uninstall ;;
+  status)    cmd_status ;;
+  continue)  cmd_continue ;;  # sets TASK, falls through to main loop
+esac
+
+# Parse arguments
+TASK="${TASK:-}"
+TASK_FILE=""
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    -t|--max-turns) MAX_TURNS="$2"; shift 2 ;;
+    -l|--max-legs) MAX_LEGS="$2"; shift 2 ;;
+    -b|--max-budget) MAX_BUDGET="$2"; shift 2 ;;
+    -m|--model) MODEL="$2"; shift 2 ;;
+    -p|--permission-mode) PERMISSION_MODE="$2"; shift 2 ;;
+    -a|--allowed-tools) ALLOWED_TOOLS="$2"; shift 2 ;;
+    -d|--work-dir) WORK_DIR="$2"; shift 2 ;;
+    -f|--file) TASK_FILE="$2"; shift 2 ;;
+    -q|--quiet) QUIET=true; shift ;;
+    --dry-run) DRY_RUN=true; shift ;;
+    -v|--version) echo "marathon $VERSION"; exit 0 ;;
+    -h|--help) usage ;;
+    -*) log_error "Unknown option: $1"; exit 1 ;;
+    *) TASK="$1"; shift ;;
+  esac
+done
+
+# Read task from file if specified
+if [[ -n "$TASK_FILE" ]]; then
+  if [[ ! -f "$TASK_FILE" ]]; then
+    log_error "Task file not found: $TASK_FILE"
+    exit 1
+  fi
+  TASK=$(cat "$TASK_FILE")
+fi
+
+if [[ -z "$TASK" ]]; then
+  log_error "No task provided. Usage: marathon \"your task\""
+  echo "Run 'marathon --help' for options."
+  exit 1
+fi
+
+# Check dependencies
+if ! command -v claude &>/dev/null; then
+  log_error "claude CLI not found. Install Claude Code first:"
+  log_error "  https://docs.anthropic.com/en/docs/claude-code"
+  exit 1
+fi
+
+if ! command -v jq &>/dev/null; then
+  log_error "jq not found. Install it:"
+  log_error "  brew install jq  (macOS)"
+  log_error "  apt install jq   (Linux)"
+  exit 1
+fi
+
+# Setup
+cd "$WORK_DIR"
+mkdir -p "$MARATHON_DIR"
+
+# Clean previous handoff
+rm -f "$MARATHON_DIR/handoff.md"
+
+# Write run metadata
+cat > "$MARATHON_DIR/run.json" <<EOF
+{
+  "task": $(echo "$TASK" | jq -Rs .),
+  "started_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "max_turns": $MAX_TURNS,
+  "max_legs": $MAX_LEGS,
+  "version": "$VERSION"
+}
+EOF
+
+# Banner
+if [[ "$QUIET" != true ]]; then
+  echo ""
+  echo -e "${BOLD}  marathon v${VERSION}${NC}"
+  echo -e "  ${DIM}Infinite context sessions for Claude Code${NC}"
+  echo ""
+  echo -e "  Task:      ${TASK:0:80}$([ ${#TASK} -gt 80 ] && echo '...')"
+  echo -e "  Max turns: $MAX_TURNS per leg"
+  echo -e "  Max legs:  $MAX_LEGS"
+  [[ -n "$MODEL" ]] && echo -e "  Model:     $MODEL"
+  echo ""
+fi
+
+# Build base claude command
+build_claude_cmd() {
+  local leg_num=$1
+  local prompt="$2"
+  local cmd="claude -p"
+
+  # System prompt with leg number substituted
+  local sys_prompt
+  sys_prompt=$(marathon_system_prompt)
+  sys_prompt="${sys_prompt//MARATHON_LEG_NUMBER/$leg_num}"
+  sys_prompt="${sys_prompt//MARATHON_MAX_LEGS/$MAX_LEGS}"
+  sys_prompt="${sys_prompt//MARATHON_MAX_TURNS/$MAX_TURNS}"
+
+  cmd+=" --append-system-prompt $(printf '%q' "$sys_prompt")"
+  cmd+=" --max-turns $MAX_TURNS"
+  cmd+=" --output-format json"
+
+  [[ -n "$MODEL" ]] && cmd+=" --model $MODEL"
+  [[ -n "$MAX_BUDGET" ]] && cmd+=" --max-budget-usd $MAX_BUDGET"
+  [[ -n "$PERMISSION_MODE" ]] && cmd+=" --permission-mode $PERMISSION_MODE"
+  [[ -n "$ALLOWED_TOOLS" ]] && cmd+=" --allowedTools $ALLOWED_TOOLS"
+
+  cmd+=" $(printf '%q' "$prompt")"
+  echo "$cmd"
+}
+
+# Build the prompt for leg 1 (initial task)
+build_initial_prompt() {
+  echo "$TASK"
+}
+
+# Build the prompt for continuation legs
+build_continuation_prompt() {
+  local handoff_content
+  handoff_content=$(cat "$MARATHON_DIR/handoff.md")
+  cat <<EOF
+You are continuing a task from a previous marathon session. Here is the handoff from the previous leg:
+
+---
+$handoff_content
+---
+
+Continue the work described above. Pick up exactly where the previous session left off.
+Remember to update .marathon/handoff.md as you make progress.
+EOF
+}
+
+# Check if the task is complete
+is_task_complete() {
+  if [[ ! -f "$MARATHON_DIR/handoff.md" ]]; then
+    return 1
+  fi
+  # Check for COMPLETE status in handoff
+  if head -5 "$MARATHON_DIR/handoff.md" | grep -qi "status:.*complete"; then
+    return 0
+  fi
+  return 1
+}
+
+# Main loop
+total_input_tokens=0
+total_output_tokens=0
+leg=1
+
+while [[ $leg -le $MAX_LEGS ]]; do
+  log_leg "$leg" "Starting..."
+
+  # Build prompt
+  if [[ $leg -eq 1 ]]; then
+    prompt=$(build_initial_prompt)
+  else
+    if [[ ! -f "$MARATHON_DIR/handoff.md" ]]; then
+      log_warn "No handoff file found. Assuming task is complete."
+      break
+    fi
+    prompt=$(build_continuation_prompt)
+  fi
+
+  # Build command
+  cmd=$(build_claude_cmd "$leg" "$prompt")
+
+  if [[ "$DRY_RUN" == true ]]; then
+    echo -e "${DIM}Would run:${NC}"
+    echo "$cmd"
+    exit 0
+  fi
+
+  # Run claude and capture output
+  # We use a temp file because the output can be large
+  output_file=$(mktemp)
+  trap "rm -f $output_file" EXIT
+
+  log "Running claude..."
+  set +e
+  eval "$cmd" > "$output_file" 2>"$MARATHON_DIR/leg-${leg}-stderr.log"
+  exit_code=$?
+  set -e
+
+  # Parse output
+  if [[ -s "$output_file" ]]; then
+    # Extract the last valid JSON object (claude may output multiple)
+    result=$(tail -1 "$output_file")
+
+    # Try to parse usage
+    input_tokens=$(echo "$result" | jq -r '.usage.input_tokens // 0' 2>/dev/null || echo 0)
+    output_tokens=$(echo "$result" | jq -r '.usage.output_tokens // 0' 2>/dev/null || echo 0)
+    session_id=$(echo "$result" | jq -r '.session_id // "unknown"' 2>/dev/null || echo "unknown")
+    stop_reason=$(echo "$result" | jq -r '.stop_reason // "unknown"' 2>/dev/null || echo "unknown")
+    response_text=$(echo "$result" | jq -r '.result // ""' 2>/dev/null || echo "")
+
+    total_input_tokens=$((total_input_tokens + input_tokens))
+    total_output_tokens=$((total_output_tokens + output_tokens))
+
+    # Save leg result
+    echo "$result" > "$MARATHON_DIR/leg-${leg}-result.json"
+
+    log "Leg $leg complete (tokens: ${input_tokens}in/${output_tokens}out, stop: ${stop_reason})"
+  else
+    log_warn "No output from claude (exit code: $exit_code)"
+    if [[ -s "$MARATHON_DIR/leg-${leg}-stderr.log" ]]; then
+      log_error "stderr: $(cat "$MARATHON_DIR/leg-${leg}-stderr.log")"
+    fi
+  fi
+
+  rm -f "$output_file"
+
+  # Check if task is complete
+  if is_task_complete; then
+    log_done "Task complete after $leg leg(s)!"
+    log "Total tokens: ${total_input_tokens} in / ${total_output_tokens} out"
+
+    # Show completion summary from handoff
+    if [[ -f "$MARATHON_DIR/handoff.md" ]]; then
+      echo ""
+      echo -e "${GREEN}${BOLD}--- Completion Summary ---${NC}"
+      cat "$MARATHON_DIR/handoff.md"
+      echo ""
+    fi
+    break
+  fi
+
+  # Check if we've hit max legs
+  if [[ $leg -ge $MAX_LEGS ]]; then
+    log_warn "Reached maximum legs ($MAX_LEGS). Task may be incomplete."
+    log_warn "Check $MARATHON_DIR/handoff.md for current state."
+    break
+  fi
+
+  # Check if handoff exists for continuation
+  if [[ ! -f "$MARATHON_DIR/handoff.md" ]]; then
+    # No handoff and not complete - Claude didn't write one
+    # This could mean the task finished without explicit COMPLETE status
+    # or Claude ran out of turns before writing handoff
+    if [[ "$stop_reason" == "max_turns" ]]; then
+      log_warn "Hit max turns without handoff. Starting recovery leg..."
+      # Create a minimal handoff for recovery
+      cat > "$MARATHON_DIR/handoff.md" <<RECOVERY
+## Task
+$TASK
+
+## Progress
+Previous session (leg $leg) ran out of turns before writing a handoff.
+
+## Current State
+Unknown - the previous session ended abruptly.
+
+## Next Steps
+1. Assess what has been done by checking recent file changes (git status/diff)
+2. Continue the original task
+3. Write a proper handoff file early this time
+
+## Key Context
+This is a recovery leg. Check the codebase state to understand progress.
+RECOVERY
+    else
+      log_done "Session ended naturally without handoff. Assuming complete."
+      log "Total tokens: ${total_input_tokens} in / ${total_output_tokens} out"
+      break
+    fi
+  fi
+
+  log "Handoff found. Continuing to next leg..."
+  echo ""
+  leg=$((leg + 1))
+done
+
+# Write final run summary
+cat > "$MARATHON_DIR/summary.json" <<EOF
+{
+  "task": $(echo "$TASK" | jq -Rs .),
+  "started_at": $(jq -r '.started_at' "$MARATHON_DIR/run.json" | jq -Rs .),
+  "finished_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "legs": $leg,
+  "total_input_tokens": $total_input_tokens,
+  "total_output_tokens": $total_output_tokens,
+  "version": "$VERSION"
+}
+EOF
+
+log "Run summary saved to $MARATHON_DIR/summary.json"

package/hooks/marathon-hooks.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+// marathon-hooks.js — Auto-continuation hooks for Claude Code
+//
+// Handles multiple hook events:
+//   PreCompact  → Inject marathon protocol, tell Claude to write handoff
+//   SessionStart → Detect existing handoff, inject continuation context
+//   Stop         → After Claude responds, check if handoff says COMPLETE
+//
+// Install via: marathon install
+// Zero overhead for normal sessions — only activates when needed.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const MARATHON_DIR = '.marathon';
+const HANDOFF_FILE = path.join(MARATHON_DIR, 'handoff.md');
+
+let input = '';
+const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const cwd = data.cwd || process.cwd();
+    const hookEvent = data.hook_event_name || process.argv[2] || '';
+
+    switch (hookEvent) {
+      case 'PreCompact':
+        handlePreCompact(data, cwd);
+        break;
+      case 'SessionStart':
+        handleSessionStart(data, cwd);
+        break;
+      case 'Stop':
+        handleStop(data, cwd);
+        break;
+      default:
+        process.exit(0);
+    }
+  } catch (e) {
+    process.exit(0);
+  }
+});
+
+// ─── PreCompact ──────────────────────────────────────────────────────────────
+// Context is about to be compacted. This is our signal that the session is big.
+// Inject the marathon protocol and tell Claude to write a handoff.
+function handlePreCompact(data, cwd) {
+  // Create .marathon dir if it doesn't exist
+  const marathonPath = path.join(cwd, MARATHON_DIR);
+  try { fs.mkdirSync(marathonPath, { recursive: true }); } catch (e) {}
+
+  // Check if handoff already exists (Claude already knows about marathon)
+  const handoffPath = path.join(cwd, HANDOFF_FILE);
+  const handoffExists = fs.existsSync(handoffPath);
+
+  let message;
+  if (handoffExists) {
+    message = [
+      'MARATHON: Context is being compacted again. UPDATE your handoff file at .marathon/handoff.md',
+      'with current progress, state, and next steps. This ensures nothing is lost during compaction.',
+      'Keep working after updating — this is not the end of the session.'
+    ].join(' ');
+  } else {
+    message = [
+      'MARATHON AUTO-CONTINUATION ACTIVATED: Context is large enough to trigger compaction.',
+      'Write a handoff file NOW at .marathon/handoff.md so your progress survives if the session ends.',
+      '',
+      'Format:',
+      '```',
+      '## Task',
+      '[What we\'re trying to achieve]',
+      '',
+      '## Progress',
+      '[What\'s been completed - files changed, decisions made]',
+      '',
+      '## Current State',
+      '[Where things stand right now]',
+      '',
+      '## Next Steps',
+      '[Ordered list of what needs to happen next]',
+      '',
+      '## Key Context',
+      '[File paths, patterns, gotchas, architectural decisions]',
+      '```',
+      '',
+      'Rules:',
+      '- Update this file as you make progress',
+      '- Be specific — the next session has NO memory of this one',
+      '- When task is fully complete, add "## Status: COMPLETE" at the top',
+      '- Keep working after writing the handoff — this is a checkpoint, not a stop signal',
+      '',
+      'If this session ends, marathon will start a fresh session with your handoff.'
+    ].join('\n');
+  }
+
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: 'PreCompact',
+      additionalContext: message
+    }
+  };
+  process.stdout.write(JSON.stringify(output));
+}
+
+// ─── SessionStart ────────────────────────────────────────────────────────────
+// Check if there's a handoff file from a previous session.
+// If so, inject continuation context so Claude picks up where it left off.
+function handleSessionStart(data, cwd) {
+  const handoffPath = path.join(cwd, HANDOFF_FILE);
+
+  if (!fs.existsSync(handoffPath)) {
+    process.exit(0);
+    return;
+  }
+
+  let handoff;
+  try {
+    handoff = fs.readFileSync(handoffPath, 'utf8').trim();
+  } catch (e) {
+    process.exit(0);
+    return;
+  }
+
+  if (!handoff) {
+    process.exit(0);
+    return;
+  }
+
+  // Check if it's a completed task (don't auto-continue completed work)
+  const firstLines = handoff.split('\n').slice(0, 5).join('\n').toLowerCase();
+  if (firstLines.includes('status: complete')) {
+    // Rename to archive instead of continuing
+    const archiveName = `handoff-complete-${Date.now()}.md`;
+    try {
+      fs.renameSync(handoffPath, path.join(cwd, MARATHON_DIR, archiveName));
+    } catch (e) {}
+    process.exit(0);
+    return;
+  }
+
+  // Active handoff found — inject continuation context
+  const message = [
+    'MARATHON CONTINUATION: A previous session left a handoff file. Here is the context:',
+    '',
+    '---',
+    handoff,
+    '---',
+    '',
+    'Pick up where the previous session left off. Follow the "Next Steps" above.',
+    'Update .marathon/handoff.md as you make progress.',
+    'When the task is fully complete, add "## Status: COMPLETE" at the top of the handoff.'
+  ].join('\n');
+
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext: message
+    }
+  };
+  process.stdout.write(JSON.stringify(output));
+}
+
+// ─── Stop ────────────────────────────────────────────────────────────────────
+// After Claude finishes responding, check if the handoff says COMPLETE.
+// If so, archive it so the next session starts fresh.
+function handleStop(data, cwd) {
+  const handoffPath = path.join(cwd, HANDOFF_FILE);
+
+  if (!fs.existsSync(handoffPath)) {
+    process.exit(0);
+    return;
+  }
+
+  let handoff;
+  try {
+    handoff = fs.readFileSync(handoffPath, 'utf8').trim();
+  } catch (e) {
+    process.exit(0);
+    return;
+  }
+
+  const firstLines = handoff.split('\n').slice(0, 5).join('\n').toLowerCase();
+  if (firstLines.includes('status: complete')) {
+    // Archive the completed handoff
+    const archiveName = `handoff-complete-${Date.now()}.md`;
+    const marathonPath = path.join(cwd, MARATHON_DIR);
+    try {
+      fs.renameSync(handoffPath, path.join(marathonPath, archiveName));
+    } catch (e) {}
+  }
+
+  process.exit(0);
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "claude-marathon",
+  "version": "0.2.0",
+  "description": "Infinite context sessions for Claude Code. Auto-continues when context gets large.",
+  "bin": {
+    "marathon": "./bin/marathon"
+  },
+  "files": [
+    "bin/",
+    "hooks/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "echo \"Tests coming soon\" && exit 0"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "context",
+    "continuation",
+    "handoff",
+    "ai",
+    "cli",
+    "anthropic",
+    "infinite-context",
+    "session-management",
+    "developer-tools"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/josephtandle/claude-marathon.git"
+  },
+  "homepage": "https://github.com/josephtandle/claude-marathon#readme",
+  "bugs": {
+    "url": "https://github.com/josephtandle/claude-marathon/issues"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}