Support & Setup Guide

Getting Started

For a detailed walkthrough including how the rules system works, see the setup guide.

1. Install the App

Download Hearth Cmd from the App Store and open it. The app will automatically generate a unique device ID and connect to the relay server.

2. Copy Your Device ID

Go to the About tab in the app and tap your Device ID to copy it to the clipboard. You'll need this for the next steps.

3. Install hearth-cmd-cli

Run the install script (requires Go 1.19+):

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

This clones the repo, builds from source, and installs the binary to /usr/local/bin.

Alternatively, unsigned pre-built binaries are available from GitHub releases (see that page for macOS Gatekeeper instructions).

Register your device ID (you only need to do this once):

hearth register YOUR_DEVICE_ID

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

4. Set Your Default Agent

hearth agent claude

Supported values: claude, copilot, cursor, codex, pi. You only need to do this once.

5. Launch

cd your-project
hearth connect --project myproject

hearth-cmd-cli 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 — forwarding them to your phone for approval. The first time, you'll see a session enrollment prompt on your phone — tap Allow.

To resume a previous session:

hearth connect --project myproject --resume SESSION_ID

6. Test It

Ask your agent to do something that requires permission, like writing a file. You should see a request appear in the app.

hearth-cmd-cli Options

Option	Description	Default
--device-id ID	Your device ID from the app	Config file or env var
--project NAME	Project name shown in the app. Rules are scoped per-project.	Required
--resume SESSION_ID	Resume a previous session instead of starting a new one	—

Configuration priority: command-line flag > environment variable (HEARTH_DEVICE_ID) > config file (~/.hearth/config).

Using the App

Permission Decisions

Each request can be responded to with four actions:

• Always Allow — Approves and creates a rule so future matching requests are auto-approved.
• Allow — Approves this one request.
• Deny — Denies this one request.
• Deny & Stop — Denies and sends a halt signal to stop the agent entirely.

How Rules Work

Tapping "Always Allow" generates a pattern that auto-approves future matching commands without interrupting you.

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

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.

For compound commands like git add . && git commit -m "msg" && git push, the system splits into segments and generates a separate pattern for each. All segments must have matching rules for auto-approval. Each segment is color-coded by risk (green/orange/red) and segments already covered by rules show a checkmark overlay.

For Read, Write, and Edit tools, patterns match on the directory (e.g., Edit(/home/user/project/src/**)).

Managing Rules

The Grants tab shows all your "Always Allow" rules grouped by project. Swipe left on any rule to delete it.

Talk to Your Agent from Your Phone

The Activity tab 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, provide additional context, or nudge your agent in a different direction.

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

Notifications

Hearth Cmd uses Time Sensitive notifications that can break through Focus modes. Make sure notifications are enabled in Settings → Hearth Cmd → Notifications and that Time Sensitive notifications are allowed in your Focus mode settings.

Troubleshooting

Not receiving requests

• Check the About tab — the status should show "Connected" with a green dot.
• Verify your device ID in ~/.hearth/config matches the one shown in the app.
• Make sure you launched your agent with hearth connect.

Session not appearing on phone

• Verify the device ID in your ~/.hearth/config matches the one in the app's About tab.
• Check the phone's connection status — the About tab should show a green "Connected" dot.
• The session should appear immediately when you run hearth connect. If it doesn't, check the hearth log file for errors.

Talk to Your Agent not working

• Talk to Your Agent requires a Hearth Cmd Pro subscription.
• You must launch your agent with hearth connect.
• Check that the Activity tab shows an input bar at the bottom when viewing the session.

Not receiving push notifications

• Check that notifications are enabled: Settings → Hearth Cmd → Notifications.
• If using a Focus mode, make sure Hearth Cmd is in the allowed apps list or Time Sensitive notifications are enabled.
• Push notifications are sent when the app is backgrounded. If the app is in the foreground, requests arrive directly via WebSocket.

Requests timing out

• The default timeout is 590 seconds.
• If the app is not connected and push notifications fail, the request will time out and be denied.

Contact

For bug reports, feature requests, or any questions, email support@hearthcmd.com.