hi-ai docs

hi-ai is a small background helper for Claude Code. It queues the prompt Claude Code drops when you hit your usage limit and sends it into the same session when the limit resets. When a five-hour window ends, it says hi so the next one starts right away.

Install

You need Node.js 22 or newer and Claude Code, signed in, on macOS or Linux.

$ npm install -g hi-ai && hi-ai setup

hi-ai setup makes two changes and prints both:

• Two hooks in ~/.claude/settings.json. UserPromptSubmit remembers your last prompt per session. StopFailure, with the rate_limit matcher, queues it when the limit stops a turn. Your own hooks and settings are kept. The first run saves a backup as settings.json.hi-ai.bak.
• A background worker that starts at login. A launchd agent on macOS, a systemd user unit on Linux. Without a service manager, keep hi-ai run open in a terminal.

Running hi-ai setup again is safe. It refreshes paths and restarts the worker. Check the result with hi-ai doctor:

$ hi-ai doctor
✓ Claude Code CLI: 2.1.296 (Claude Code) (/opt/homebrew/bin/claude)
✓ Node.js: 26.10.0
✓ Auto-queue hooks: ~/.claude/settings.json
✓ Worker service (launchd): ~/Library/LaunchAgents/dev.magnificalabs.hi-ai.plist
✓ Worker running: pid 25304, log ~/.hi-ai/worker.log
✓ Config: keepalive=on notify=on permission-mode=inherit ping-model=haiku

How it works

• Limits come from Claude Code itself. Every claude -p --output-format stream-json run reports a rate_limit_event with the status, the window and the exact reset time. hi-ai keeps the latest in ~/.hi-ai/state.json.
• A rejected job isn't a failed job. It goes back in the queue without using a retry, and the worker sleeps until the reset.
• Half-done turns continue. The hook reads the session transcript. If Claude already made progress, the queued prompt asks it to continue instead of starting over.
• The hi only goes out when it helps. Never while a job is queued or running, while you're blocked, or while the weekly limit is used up.
• One worker, clean shutdowns. A pid file prevents a second worker. Stopping the worker stops the running claude and its tools, and re-queues the job.

Commands

Options for hi-ai add: --cwd DIR, --model M, --permission-mode MODE, --allow Bash,Edit, --resume SESSION_ID.

$ hi-ai add "write tests for src/parser.ts" --cwd ~/code/app
$ hi-ai add --model sonnet --permission-mode acceptEdits --allow Bash,Edit - < plan.md
$ hi-ai add --resume 3e8cedfe-b53c-41cb-a02f-008d78c148de "now update the changelog"

Permissions in unattended runs

Queued prompts run while nobody is at the keyboard, so Claude can't ask you to approve a tool call.

• Auto-queued prompts inherit the session's permission mode. A prompt dropped in an acceptEdits session runs with acceptEdits.
• Your allow rules apply, such as "allow": ["Bash(npm test)"] in your Claude Code settings.
• Anything else is denied, not stuck. The job finishes, and hi-ai ls and the notification say how many tool calls were denied.

To use one mode for every queued prompt:

$ hi-ai config permission-mode acceptEdits   # or auto, bypassPermissions, plan; "inherit" to undo

What it costs

Queued prompts cost what they would have cost when you typed them. hi-ai only re-runs a prompt the limit stopped.

The hi is the smallest request Claude Code can send: Haiku, with tools, skills, MCP servers, CLAUDE.md, settings and thinking switched off. Measured with Claude Code 2.1.291 on 14 October 2026, with a mostly cold cache, as a real ping hours apart would be:

At most one hi per five-hour window, about five a day. Change the model with hi-ai config ping-model <model>, or turn it off with hi-ai config keepalive off.

Configuration

hi-ai config prints the current settings, stored in ~/.hi-ai/config.json. Changing one restarts the worker.

Environment variables: HIAI_HOME moves the data folder, HIAI_CLAUDE_BIN points at a different claude, and HIAI_DEBUG=1 logs every hook call to ~/.hi-ai/hooks.log.

Files and privacy

hi-ai talks to nothing but your local claude command. It has no server, no account, no telemetry and no runtime dependencies. Everything lives in ~/.hi-ai:

Good to know

• Your computer has to be awake. The worker catches up as soon as it wakes.
• The weekly limit can't be worked around. hi-ai waits for it and skips the hi until it resets.
• Open the result with claude --resume. A terminal already open on that session won't refresh by itself.
• Auto-queue covers interactive sessions. A claude -p script exits before the hook runs. Queue scripted work with hi-ai add.

Troubleshooting

$ hi-ai doctor                  # what's missing, and the command that fixes it
$ tail -f ~/.hi-ai/worker.log   # what the worker is doing
$ HIAI_DEBUG=1 claude           # then read ~/.hi-ai/hooks.log

Still stuck? Open an issue with the hi-ai doctor output.

Uninstall

$ hi-ai uninstall
$ npm uninstall -g hi-ai
$ rm -rf ~/.hi-ai   # optional: queue, state and logs