Claude-Thermos: Keep Your Claude Session Alive and Avoid Cold Starts

What Happened: The Session Timeout Problem

A developer named Ilya Zeigerman released an open-source utility called Claude-Thermos on GitHub. The problem it solves is painfully simple: Anthropic’s Claude Code (the CLI agent) terminates idle sessions after a fixed inactivity window. You step away to grab coffee, attend a standup, or fight a production fire, and you return to a dead terminal. Your context—the careful system prompts, the multi-turn debugging conversation, the painstakingly built mental model of the codebase—is gone. You start over from a cold shell.

Zeigerman’s tool, claude-thermos, acts as a keepalive wrapper. It injects a benign, low-cost heartbeat into the session at configurable intervals, tricking the timeout mechanism into thinking a human is still actively typing. The name is apt: a thermos keeps your coffee hot; this keeps your Claude session warm.

This isn't a complex piece of software. It’s a focused script that addresses a specific pain point for engineers who treat Claude Code as a persistent pair-programming partner rather than a stateless query box.

Why It Matters: The Cold Start Tax on Engineering Flow

For working engineers—especially Forward Deployed Engineers (FDEs) who oscillate between customer context and deep code—a cold start isn't just an inconvenience. It’s a material tax on throughput.

The Hidden Cost of Losing State

When a Claude Code session dies, you don't just lose the chat history. You lose:

• System Prompts: Custom instructions that tune the model’s behavior for a specific repository or task.
• Permission Grants: The explicit approvals you gave for bash commands, file writes, and network calls.
• Ephemeral Context: The model’s working memory of the debugging path you were on. Re-establishing this requires re-uploading files, re-explaining the bug, and re-running preliminary diagnostics.

A 15-minute timeout can easily translate into a 10-minute recovery ramp-up. If this happens three times a day, you’ve lost half an hour of focused engineering time. Over a week, that’s a full feature branch’s worth of cognitive load.

Why FDEs Feel This Acutely

Forward Deployed Engineers operate in a unique tension zone. They are not pure backend developers who can lock themselves in a dark room for six hours. An FDE’s day is fragmented by design: customer calls, urgent Slack pings about a broken integration, and context-switching between three different customer environments.

If you are an FDE using Claude Code to write a custom script against a customer’s API, you might be interrupted four times before you finish. Without a keepalive mechanism, you’d be restarting your session after every interruption. This directly attacks the metrics an FDE is measured on—time-to-value and expansion velocity. For more on how these metrics define the role, see our breakdown of FDE Metrics: Time-to-Value, Adoption, Expansion, and Revenue Influence.

How Claude-Thermos Works Under the Hood

Claude-Thermos is not a complex daemon. It’s a lightweight wrapper that leverages the interactive nature of the Claude Code REPL. The architecture is minimal:

The Heartbeat Mechanism

The tool does not interact with Anthropic’s API directly to reset a server-side timer. Instead, it operates at the client level. Claude Code’s REPL listens for stdin. If no input is received for a set duration (often 15-30 minutes), the client initiates a graceful shutdown.

Claude-Thermos intercepts this by sending a harmless, non-disruptive token to stdin. This is typically a comment character (#) or a whitespace character that the REPL ignores but registers as activity. The interval is configurable—you might set it to 5 minutes if your environment is aggressive, or 10 minutes if you want to minimize noise.

Session Integrity

A critical design consideration is that the heartbeat must not interfere with active operations. If Claude is in the middle of generating a large block of code, injecting a character could corrupt the input buffer. The tool handles this by:

1. Tracking the state of the REPL (idle vs. busy).
2. Only injecting the heartbeat when the prompt is visible and waiting for input.
3. Using a non-executing character that doesn’t trigger a newline or command submission.

This is the engineering elegance of the tool: it respects the boundary between keepalive signaling and command injection. It does not accidentally submit rm -rf / because you set the interval too low.

Getting Started: Installation and Configuration

You can get Claude-Thermos running in under two minutes. The setup is designed for engineers who live in the terminal.

Prerequisites

• Node.js: The tool is written in TypeScript and runs on Node. Ensure you have Node 18+ installed.
• Claude Code: You must have the Anthropic CLI installed and authenticated (claude command available in your path).
• Git: To clone the repository.

Step-by-Step Setup

1. Clone the repository:

   git clone https://github.com/izeigerman/claude-thermos.git
   cd claude-thermos
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

4. Run the wrapper: Instead of invoking claude directly, you now invoke the thermos wrapper.

   npm start
   

   This spawns a Claude Code session with the keepalive logic active.

Configuration Options

You can customize the behavior via environment variables or a config file:

For an aggressive timeout environment, you might set:

export THERMOS_INTERVAL_MS=180000  # 3 minutes
npm start

Integrating into Your Workflow

Most engineers will alias this to avoid typing the full command:

alias warm-claude='cd ~/tools/claude-thermos && npm start'

Now, warm-claude becomes your entry point for any long-running coding session.

The Forward Deployed Engineer’s Perspective

Let’s ground this in a real FDE workflow. You are building a natural language SQL analyst agent for a customer’s Postgres database, similar to the project we outline in our guide on Building a Natural Language SQL Analyst Agent Over Your Postgres Database.

Your session involves:

• A detailed system prompt explaining the customer’s schema (200+ lines).
• A multi-turn conversation where Claude has proposed a complex recursive CTE.
• You’ve granted it permission to run EXPLAIN ANALYZE against a read replica.

Mid-way through, the customer calls. Their ETL pipeline is down. You spend 45 minutes diagnosing a schema drift issue. Without Claude-Thermos, you return to a dead terminal. You must re-paste the schema, re-explain the query optimization goal, and re-grant permissions. The customer’s time-to-value slips by a day.

With Claude-Thermos, you return, type “continue,” and pick up exactly where you left off. This is not a luxury; it’s a requirement for maintaining the high context-switching tempo that defines the FDE role. If you’re new to this rhythm, our breakdown of What a Forward Deployed Engineer Actually Does in a Week illustrates why state preservation is your primary defense against chaos.

A Balanced Take: Benefits, Risks, and Alternatives

Claude-Thermos is a sharp tool, but it’s worth examining its edges.

The Good

• Zero-Cost State Preservation: It solves a real UX gap in Claude Code without requiring any API changes from Anthropic.
• Minimal Footprint: The utility is a few hundred lines of code. It’s auditable, lightweight, and does not introduce a heavy dependency chain.
• Flow State Enabler: For engineers practicing Context Engineering for Claude 5, where prompt structure is meticulously crafted, preserving that structure across interruptions is invaluable.

The Risks

• Token Consumption: While the heartbeat character itself is not submitted as a prompt, keeping a session alive means the local process remains active. If you walk away for eight hours, you are still holding a connection. This is not a major cost concern for the CLI, but it’s inelegant.
• Security Posture: An open, authenticated Claude Code session on an unlocked laptop is a potential vector. If you step away from your desk, a malicious actor could interact with a session that has elevated file system permissions. Always lock your machine, regardless of keepalive tools.
• Upstream Fragility: Anthropic could change the idle detection mechanism in Claude Code. If they move from a stdin listener to a server-side token-bucket timeout, Claude-Thermos breaks. This is technical debt you take on willingly.

Alternatives

Before reaching for Claude-Thermos, consider if you can solve the problem architecturally:

1. Session Serialization: For critical work, periodically ask Claude to “summarize our current debugging state and the next steps into a markdown file.” If the session dies, you can feed that summary into a new session. This is manual but robust.
2. Tmux/Screen: Running Claude Code inside a tmux session prevents network drops from killing the process, but it does not prevent Claude Code’s own idle timeout logic from triggering.
3. API Direct Calls: If you need extreme persistence, bypass the CLI and use the Anthropic API directly, managing conversation history in your own database. This is significantly more engineering effort but gives you full control over state.

FAQ

Does Claude-Thermos violate Anthropic’s Terms of Service? As of now, it operates entirely within the client-side CLI. It does not abuse the API, bypass rate limits, or automate prompts in a way that violates acceptable use policies. It simply prevents a local timeout. However, always review the latest terms.

Will this increase my API costs? No. The heartbeat is a local stdin injection. It does not generate an API request to Anthropic’s servers. Your token consumption remains tied to your actual prompts and completions.

Can I use this with other CLI tools? The concept is generalizable. Any REPL-based CLI tool that times out on stdin inactivity could be wrapped with a similar heartbeat script. The current implementation is purpose-built for Claude Code’s specific behavior.

What happens if I close my laptop lid? Claude-Thermos keeps the session alive as long as the process is running. If your system suspends the process (e.g., laptop sleep), the session will likely die. This tool prevents idle timeout, not OS-level process suspension.

Is there a GUI version? No. This is a terminal utility for terminal users. The target audience is engineers who live in the command line and use Claude Code as part of their development workflow.