Quickstart

Pilothouse is one inbox for every coding agent on your machine. It watches Claude Code and Codex through their official hooks, checks your rules before every tool call, and sends what needs a person to wherever you are: the terminal at your desk, or your phone when you step away.

This page gets you from nothing to your first approval from a phone. Each step links to a longer guide.

1. Install

curl -fsSL https://pilothouse.dev/install.sh | sh

Or with Homebrew:

brew install xasdta/tap/pilothouse

Pilothouse is a single binary for macOS and Linux (amd64 and arm64). See Install for versions, install locations and checksums.

2. Run setup

pilothouse setup

setup does three things:

1. Installs hooks into Claude Code (~/.claude/settings.json) and Codex. Your existing hooks are kept; the original file is backed up first.
2. Installs a user service (launchd on macOS, systemd on Linux) so the daemon starts at login.
3. Checks everything the way pilothouse doctor does, and tells you what to fix.

Codex asks you to review and trust new hooks before it runs them. Open Codex, run /hooks, and trust the Pilothouse entries.

3. Start an agent the way you always do

claude

Any terminal works: Ghostty, iTerm2, the VS Code terminal, tmux, herdr, an SSH session. Open the inbox in another tab:

pilothouse

You’ll see every session on the machine, what state it’s in, and anything waiting for you.

4. Write your first rule

pilothouse policy init

This writes a starter ~/.pilothouse/policy.yaml with commented examples. A rule that asks before anything is pushed to main looks like this:

version: 1
rules:
  - name: ask-before-push-main
    match: { kind: shell, command: "git push*main*" }
    action: ask

Try it without running anything:

pilothouse policy test --tool Bash --command "git push origin main"

More in Policies.

5. Pair your phone

The web app runs on your machine and listens on 127.0.0.1 only. To reach it from your phone, put it on your tailnet with Tailscale Serve, then pair:

pilothouse remote tailscale
pilothouse pair

Scan the QR code with your phone, add the page to your home screen, and allow notifications. Full walkthrough in Phone setup.

6. Step away

Leave the keyboard alone for a minute (the default idle threshold is 60 seconds), or force it:

pilothouse away

The next time an agent asks for permission, your phone gets a push. Tap Allow, Allow for session or Deny. The first answer wins, wherever it comes from. Run pilothouse auto to go back to automatic presence detection.

What next

• How it works: the daemon, the two checkpoints, presence, and what each agent supports.
• Wrap mode: keep agents alive after you close the terminal.
• Tasks: one prompt, one worktree, one branch, one agent.
• Notifications: ntfy, Slack, Discord and desktop.
• Security model: what protects a remote “Allow”, and what doesn’t.