What is claude-heartbeat?

claude-heartbeat is a small JavaScript tool that turns an interactive Claude Code session into an automated task processor, without needing to use Claude's command-line -p flag or the API SDK, which require separate billing credits. Instead, it works through the regular Claude Code subscription. The way it works is through a "stop hook", a script that runs automatically after each Claude response. This hook checks a file called the inbox (a simple text file where you write tasks line by line). When a new task is found, it injects that task into the Claude session, which processes it and writes its response to an outbox file. The session is then restarted fresh so the next task starts with clean context, with no leftover conversation history from previous tasks. A supervisor process sits above everything, watching for crashes or stuck sessions and restarting them automatically. While the inbox is empty, the system sends minimal "heartbeat" ticks to keep the session alive with very low token usage. The inbox and outbox files use plain text or simple JSON format, making it easy to feed tasks from a cron scheduler, an HTTP webhook, or a chat relay (a Discord bot relay is included as an optional example). Running multiple parallel agents is possible by setting up multiple working directories, each with their own supervisor and inbox. The project is aimed at developers who want to automate Claude Code tasks cheaply using an existing subscription rather than paying per-call API credits.