Claude Heartbeat

claude-heartbeat

Stateless autonomous agent for Claude Code — no -p, no SDK credits.

The heartbeat hook turns an interactive Claude Code session into a stateless task processor. Each message from the inbox gets its own fresh session, just like -p — but using your regular subscription.

Why

Anthropic is separating -p and SDK usage into a dedicated credit bucket. If you've been using claude -p for automation, your costs just went up.

The heartbeat hook gives you -p behavior in interactive mode, which uses your regular subscription — not SDK credits.

How it works

1. The supervisor launches Claude Code in interactive mode
2. After each response, the stop hook fires
3. The hook reads the next line from io/inbox.jsonl
4. If a message exists, it's injected — one message per session
5. The agent processes it, writes a response to io/outbox.jsonl
6. The hook signals the supervisor to kill and restart with fresh context
7. Next message gets a clean session — true stateless operation

One message = one session = fresh context every time.

When the inbox is empty, the hook polls internally and blocks with minimal idle ticks (~20 tokens each) to keep the session alive until work arrives.

Setup

1. Clone

2. Start

That's it. The hook is already configured in .claude/settings.json. The supervisor launches Claude, and the heartbeat hook handles the rest.

Options:

3. Send messages

From another terminal:

Messages are processed one at a time. If 5 messages pile up, each gets its own fresh session.

4. (Optional) Start the relay

5. (Optional) Inject events

What you get

- No SDK credits — interactive mode uses your subscription
- Stateless — each message gets fresh context, like -p
- Autonomous — watches inbox, processes messages, writes responses
- Cheap idle — minimal…