Penfold - Multi-session Claude Code Monitor

Quick Start

Install

Install prerequisites, then download and run the installer:

brew install tmux jq curl

tar xzf penfold-YYYYMMDD-darwin-universal.tar.gz
cd penfold-YYYYMMDD
bash install.sh

This installs the penfold binary to ~/.local/bin/, sets up a LaunchAgent, generates an API key, and starts the daemon.

Add to your ~/.zshrc if needed:

export PATH="$HOME/.local/bin:$PATH"

Configure Claude Code Hooks

Add the following to ~/.claude/settings.json (merge the hooks key if the file already exists):

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command",
          "command": "bash ~/.local/share/penfold/penfold-hook.sh" }] }
    ],
    "Notification": [
      { "matcher": "", "hooks": [{ "type": "command",
          "command": "bash ~/.local/share/penfold/penfold-hook.sh" }] }
    ],
    "PreToolUse": [
      { "matcher": "", "hooks": [{ "type": "command",
          "command": "bash ~/.local/share/penfold/penfold-hook.sh" }] }
    ],
    "PostToolUse": [
      { "matcher": "", "hooks": [{ "type": "command",
          "command": "bash ~/.local/share/penfold/penfold-hook.sh" }] }
    ],
    "UserPromptSubmit": [
      { "matcher": "", "hooks": [{ "type": "command",
          "command": "bash ~/.local/share/penfold/penfold-hook.sh" }] }
    ]
  }
}

Run Claude Code in tmux

Penfold tracks sessions via tmux. Start Claude Code inside a tmux session:

tmux new -s claude
# Now inside tmux:
claude

iOS App (Optional)

The iOS app is distributed via Ad Hoc. You'll need to send your device UDID to the project owner to receive a signed IPA.

Get Your UDID

Via Finder:

Connect your iPhone to your Mac with a cable
Open Finder and select your iPhone in the sidebar
Click the text below the device name — it cycles through serial, UDID, ECID, model
Click until it shows UDID (a long hex string like 00008110-001A2B3C4D5E6F78)
Right-click the UDID and copy it

Via terminal:

xcrun devicectl list devices 2>/dev/null | grep -i iphone

Install & Configure

Once you receive the .ipa file, drag it onto your iPhone in Finder (or use Apple Configurator 2). Then open the app and configure:

Mac hostname — your Tailscale hostname or local IP
API key — contents of ~/.config/penfold/api_key

Your Mac and iPhone must be on the same network or connected via Tailscale.

Verify

# Daemon is running
curl -s localhost:9765/health | jq .status
# → "ok"

# TUI connects
penfold attach
# (Ctrl-C to exit)

# Check hooks are flowing (start Claude Code in tmux first)
tail -f ~/.config/penfold/penfold.log | grep HOOK

Troubleshooting

Problem	Fix
`penfold: command not found`	Add `export PATH="$HOME/.local/bin:$PATH"` to `~/.zshrc`
Port 9765 in use	`lsof -i :9765` to find the process, kill it, re-run `install.sh`
Hooks not firing	Check `~/.claude/settings.json` has all 5 hook types with correct path
TUI shows stale data	Check `cat ~/.config/penfold/health.json \| jq .last_poll_age_secs` (should be < 2). Restart the LaunchAgent.
iOS won't connect	Verify same network/Tailscale, check hostname and API key in app settings