Hearth Cmd Setup Guide

Hearth Cmd is mission control for your AI coding agents. It launches your agent in yolo mode so it never blocks on a terminal prompt. Hearth Cmd's permission engine intercepts all reads, writes, network IO, and shell commands — routing them to your phone for approval. Smart rules auto-approve trusted actions so your agents keep working. When something needs your attention, you handle it from anywhere.

Supported Agents

What You'll Need

One of the supported agents installed and working
An iPhone with the Hearth Cmd app installed (iOS App Store listing coming soon)
macOS, Linux, or WSL2

Step 1: Get Your Device ID

Open Hearth Cmd on your phone and go to the About tab. Tap your Device ID to copy it to the clipboard.

Step 2: Install hearth-cmd-cli

curl -sSL https://hearthcmd.com/install.sh | bash

This downloads the latest binary for your system and installs it to /usr/local/bin.

hearth register YOUR_DEVICE_ID

You can also pass --device-id as a flag or set the HEARTH_DEVICE_ID environment variable.

Step 3: Set Your Default Agent

Tell Hearth Cmd which agent you want to use:

hearth agent claude

Supported values: claude, copilot, cursor, codex, pi. You only need to do this once — the setting is saved to your config.

Step 4: Launch

cd your-project
hearth connect --project myproject

That's it. hearth-cmd-cli handles everything automatically:

Launches your agent in yolo mode so it never blocks on a terminal prompt
Hearth Cmd's libhook permission engine intercepts all reads, writes, network IO, and shell commands
Enrolls the session with your phone (tap Allow on the first prompt)
Streams activity to your phone in real time

To resume a previous session:

hearth connect --project myproject --resume SESSION_ID

Step 5: Test It

Ask your agent to do something that requires permission, like writing a file:

echo "test" > /tmp/hearth-test.txt

You should see a request appear on your phone. Tap Allow and the agent will continue. If you tap Always Allow, a rule is created and the agent won't ask again for that class of command in this project.

How the Rules Work

Rules are the core of the system. Tapping "Always Allow" doesn't just approve the request — it generates a pattern that auto-approves future matching commands without interrupting you.

Pattern generation

Patterns are subcommand-aware. The system knows that git push and git status are different operations:

go build ./cmd/foo → pattern Bash(go build **) — matches any go build
git push origin main → pattern Bash(git push **) — matches any git push, but not git reset
aws s3 cp file.txt s3://bucket/ → pattern Bash(aws s3 cp **) — three-word prefix for AWS/GCloud

Destructive command safety

Commands like rm, sudo, kill, and chmod use exact matching. Granting rm -rf /tmp/coverage creates a rule that matches only that exact string — not rm -rf /home, not rm -rf /tmp/coverage /etc.

Compound commands

When the agent runs git add . && git commit -m "msg" && git push, the system splits it into three segments and generates a separate pattern for each. All segments must have matching rules for the compound command to auto-approve. If you've granted git add and git commit but not git push, the compound command still comes to your phone.

In the app, each segment is color-coded by risk (green/orange/red) and segments already covered by rules show a checkmark overlay — so you can see at a glance which part of the command is the one that needs your attention.

File operations

For Read, Write, and Edit tools, patterns match on the directory. Granting an edit to /home/user/project/src/main.go creates the pattern Edit(/home/user/project/src/**), which covers future edits in that directory.

Talk to Your Agent from Your Phone

The Activity tab in the app shows an input bar at the bottom. Anything you type is sent directly to your agent session as if you typed it at the terminal.

Use this to:

Answer prompts when your agent asks a question
Provide additional context or instructions mid-session
Nudge the agent in a different direction
Respond to interactive dialogs

Talk to Your Agent requires Hearth Cmd Pro. Pro also includes push notifications so you never miss a request.

Tips

The first few sessions generate the most requests. Once you've built up rules for your common patterns, interruptions drop off quickly.
Check the Grants tab to see your rules grouped by project. Swipe left to delete any rule.
If you're in a Focus mode on iOS, make sure Time Sensitive notifications are allowed for Hearth Cmd — permission requests use this priority.

Troubleshooting

See the troubleshooting section of the support page for common issues.

Questions?

Email support@hearthcmd.com.