Install

Reference

Troubleshooting

Fix common Pilothouse problems — sessions not showing up, Codex hooks not running, no phone notifications, Tailscale HTTPS errors, and requests going to the wrong place.

Start with:

pilothouse doctor

It checks your setup — daemon, hooks, service, remote access — and prints a fix for each problem it finds.

A session doesn’t show up

  • Is the daemon running? pilothouse status. If not, pilothouse start, or pilothouse setup to install the service.
  • Are the hooks installed? pilothouse hooks status. Re-run pilothouse hooks install if your agent’s settings were reset.
  • Codex: Codex only runs hooks you’ve trusted. In Codex, run /hooks and trust the Pilothouse entries. Hooks must also be enabled ([features] hooks is on by default).
  • Sessions started before setup won’t report until their next hook event; restart the agent if in doubt.

The state looks wrong

pilothouse explain <session>

shows the evidence behind the state and which rule picked it. If it still looks wrong, please open an issue with the explain output.

My phone isn’t getting notifications

  1. pilothouse notify test — does anything arrive?
  2. iPhone: web push only works for web apps added to the home screen. Open Pilothouse from the home-screen icon and allow notifications there.
  3. Check that the phone is connected to Tailscale and can open your web.public_url.
  4. Check presence: at your desk, requests go to the terminal, not the phone. Run pilothouse away to test.

“HTTPS is not enabled for this tailnet”

Enable MagicDNS and HTTPS certificates in the Tailscale admin console (DNS page), then run pilothouse remote tailscale again.

The request went to my terminal, but I was away

Presence uses OS idle time with a default threshold of 60 seconds. Background input (a mouse jiggler, a game controller, some remote-desktop tools) can make you look present. Use pilothouse away before you leave, lower presence.idle_threshold, or set approvals.always_hold: true.

The agent showed its own dialog after a few minutes

That’s the hold limit. If nobody answers on a device within approvals.hold_limit (default 9 minutes), Pilothouse hands the question back to the agent so it never hits the agent’s own hook timeout. You’ll get a notification saying so.

Policy changes don’t seem to apply

  • pilothouse policy status shows loaded files, ignored rules and errors. An invalid file keeps its last good version.
  • Repo allow rules are ignored until you pilothouse policy trust the repo.
  • Remember precedence: any deny wins over ask, which wins over allow.
  • Test the exact call with pilothouse policy test.

“agent_caller” errors

Pilothouse refuses approval and admin commands when they’re run from inside an agent (any process whose ancestors include claude or codex). Run the command from a normal terminal. This is deliberate — see Security model.

Detach key doesn’t work in wrap mode

The detach key is ctrl+\. Some terminals or tmux bindings capture it; check your bindings. Press it twice to send a literal ctrl+\ to the agent.

Logs

  • Foreground daemon (pilothouse daemon): stderr.
  • As a service: ~/.pilothouse/logs/daemon.log (rotated at 10 MB, three files kept).
  • Wrapped agents: ~/.pilothouse/logs/holder-<session>.log.

Found a mistake? Open an issue.