cc-resilient

Network-resilient wrapper for Claude Code CLI.

Built as a working prototype for anthropics/claude-code#26729 -- a proposal for native streaming resilience in Claude Code.

Problem

When using Claude Code over unstable connections (Wi-Fi drops, power cuts, VPN disconnects, mobile hotspot switching), active sessions hang silently with no timeout, no recovery, and no graceful handling. The only option is to kill the process and manually restart.

What cc-resilient does

cc-resilient wraps the claude CLI and adds three capabilities:

1. Network monitoring -- pings api.anthropic.com every 5 seconds to detect connectivity loss
2. Hang detection -- identifies stalled processes with no output for a configurable timeout
3. Automatic recovery -- kills hung processes, saves session metadata, and resumes with context when connectivity returns

Install

npm install -g cc-resilient

Prerequisite: Claude Code must be installed and authenticated (claude command available in PATH).

Quick start

# Use exactly like claude, but with network resilience
cc-resilient -- "explain this project"

# Print mode
cc-resilient -- -p "refactor the auth module"

# Continue a session with resilience
cc-resilient -- --continue

# Interactive mode (stdin passed through)
cc-resilient

# Disable auto-resume (ask before resuming)
cc-resilient --no-auto-resume -- -p "build feature X"

# Verbose mode (see network status on stderr)
cc-resilient --verbose -- -p "hello"

# Check last recovery state
cc-resilient --status

How it works

                 cc-resilient
                      |
        +-------------+-------------+
        |             |             |
  Network Monitor  Process Monitor  Session Tracker
   (ping every 5s)  (track stdout)   (find session ID)
        |             |             |
        +------+------+             |
               |                    |
         Recovery Manager  <--------+
          (orchestrate disconnect/reconnect/resume)

1. cc-resilient spawns claude as a child process
2. In parallel, it pings api.anthropic.com every 5 seconds (HTTPS HEAD)
3. If 3 consecutive pings fail, it declares the connection offline
4. It gracefully kills the hung claude process (SIGTERM, then SIGKILL after 5s)
5. It saves recovery metadata to ~/.cc-resilient/recovery.json
6. When 2 consecutive pings succeed, it declares the connection restored
7. It resumes the session: claude --continue -p "You were interrupted by a network disconnection..."

Configuration

CLI flags

| Flag | Default | Description | |------|---------|-------------| | --health-interval <ms> | 5000 | How often to check connectivity | | --health-timeout <ms> | 3000 | Timeout per health check | | --hang-timeout <ms> | 300000 | No-output duration before declaring a hang (5 min) | | --no-auto-resume | false | Ask before resuming instead of auto-resume | | --max-resumes <n> | 3 | Give up after N consecutive resume failures | | --resume-prompt <text> | (see below) | Custom text for the resume context message | | --log-file <path> | null | Write structured logs to a file | | --verbose | false | Show detailed status on stderr | | --config <path> | ~/.cc-resilient.json | Path to config file | | --status | - | Print last recovery state and exit |

Config file

Create ~/.cc-resilient.json with any of these options:

{
  "healthCheckIntervalMs": 5000,
  "healthCheckTimeoutMs": 3000,
  "healthCheckEndpoint": "https://api.anthropic.com",
  "offlineThreshold": 3,
  "reconnectStabilityCount": 2,
  "processHangTimeoutMs": 300000,
  "gracefulShutdownTimeoutMs": 5000,
  "autoResume": true,
  "autoResumeDelayMs": 2000,
  "maxResumeAttempts": 3,
  "verbose": false
}

All fields are optional. Missing fields use defaults.

Limitations

This is an external wrapper, not a native feature. It can solve some problems but not all:

| What it can do | What it cannot do | |----------------|-------------------| | Detect network loss (via periodic pings) | See the SSE stream directly (instant detection) | | Kill hung processes | Save partial streaming responses | | Auto-resume sessions with context | Know exactly which tool was mid-execution | | Save recovery metadata to disk | Repair corrupted conversation state (orphaned tool_use blocks) | | Work with both interactive and print modes | Selectively retry safe vs unsafe tools |

The remaining ~60% of the proposed functionality requires native support inside Claude Code. See the full feature request for the complete design.

Recovery metadata

On disconnect, cc-resilient saves state to ~/.cc-resilient/recovery.json:

{
  "sessionId": "fdbee89f-40d1-483c-b33b-b4305d924d84",
  "workingDirectory": "/home/user/project",
  "timestamp": "2026-02-23T13:45:00.000Z",
  "lastActivityTimestamp": "2026-02-23T13:44:55.000Z",
  "disconnectReason": "network",
  "claudeArgs": ["-p", "build the auth module"],
  "pid": 12345,
  "resumeCount": 0
}

This persists even if cc-resilient itself crashes, so you can inspect what happened and manually resume.

Development

git clone https://github.com/SaravananJaichandar/cc-resilient.git
cd cc-resilient
npm install
npm run build
npm test

License

MIT