Perch helps developers park AI coding sessions and resume them later from the CLI, menu bar, or Raycast. Run /perch inside a supported coding agent, and Perch saves the current session into ~/.config/perch/sessions.json.

AI coding sessions are valuable context, but every agent has a different way to resume work. Perch gives you one local, agent-agnostic parking lot for those sessions so you can:

• Save the current thread with the same /perch command across supported agents.
• Resume from the correct project directory without remembering each agent's command syntax.
• Keep everything local in a simple JSON file — no account, server, or sync service required.
• Use the CLI, menu bar, or Raycast depending on where you are already working.

• Waiting on another person: You are drafting an email, reviewing a PR, or coordinating a decision, but the other person cannot reply in real time. Park the AI session with /perch Waiting on Alex about API contract, close the terminal, and quickly resume the exact context when they respond.
• Too many terminal windows: Your desktop is full of half-finished agent sessions. Save the ones you are not actively using to Perch, close those terminals, and bring them back later from Raycast, the menu bar, or perch list.
• Context switching between projects: Pause a debugging thread in one repo, jump to another urgent task, then resume from the right working directory without hunting through shell history.
• End-of-day cleanup: Park unfinished work before shutting down so tomorrow starts with a searchable list of pending AI sessions instead of scattered terminal tabs.

Install the Perch CLI and supported agent /perch commands:

curl -fsSL https://raw.githubusercontent.com/ReScienceLab/Perch/main/install.sh | sh

Then:

1. Make sure ~/.local/bin is in your shell PATH.
2. Restart your coding agent.
3. Type /perch My task title inside Claude Code, Codex, Pi, Droid, OpenCode, or Hermes to save the current session.
4. Resume from Raycast with Search Sessions, from the menu bar, or by running perch list and copying the resume command.
5. Verify setup any time with:

perch doctor

Perch stores sessions locally only; no service or account is required.

# 1. Save the current AI coding session from inside a supported agent
/perch Backend: finish OAuth callback

# 2. Later, list parked sessions from any terminal
perch list

# 3. Resume from the saved project directory
cd '/path/to/project' && claude --resume <session-id>

Prefer a launcher? Open Raycast's Search Sessions command or the Perch menu bar icon, choose a parked session, and Perch copies the right project-aware resume command for you.

• One /perch command shared across agents — no per-agent prompt drift.
• Fast session detection where the agent exposes a session ID (for example CLAUDE_CODE_SESSION_ID in Claude Code), with safe fallbacks when needed.
• Simple local JSON storage; no service or account required.
• Menu bar UI for viewing pending/completed sessions.
• CLI for scripting, listing, marking done, and reopening sessions.

• Local-only session storage in ~/.config/perch/sessions.json
• Shared /perch command for Claude Code, Codex, Pi, Droid, and OpenCode
• Resume command generation for additional workspace/session-based agents
• Native macOS menu bar app
• Raycast extension for search, resume, add, mark done, and reopen flows
• perch doctor diagnostics for install and environment issues

Automatic means install.sh detects the agent binary and installs /perch into that agent's command/skill directory. Manual CLI add means Perch supports the resume command, but there is no installed slash-command path yet.

Recommended remote install:

curl -fsSL https://raw.githubusercontent.com/ReScienceLab/Perch/main/install.sh | sh

You can also download prebuilt release assets from the latest GitHub Release.

Local repo install for contributors:

git clone https://github.com/ReScienceLab/Perch.git
cd Perch
./install.sh

The installer is idempotent. It:

• Installs the perch CLI to ~/.local/bin/perch, using the latest GitHub Release prebuilt binary by default.
• Falls back to a local Cargo build only when running from a cloned repo and release download is unavailable.
• Installs the native macOS PerchApp menu bar app to ~/.local/share/perch/PerchApp by default on macOS.
• Installs the same agent-agnostic command from Commands/perch.md for every detected agent.
• Creates ~/.config/perch/sessions.json if missing.
• Creates ~/.config/perch/config if missing.

Installer environment flags:

PERCH_INSTALL_APP=0          # skip native menu bar app installation
PERCH_INSTALL_APP=1          # force native menu bar app installation on macOS
PERCH_APP_INSTALL_DIR=...    # override app install directory; default ~/.local/share/perch
PERCH_OPEN_APP=0             # install but do not open PerchApp after install

Make sure ~/.local/bin is in your shell PATH and is also visible inside your coding agents. Run perch doctor after installation for actionable diagnostics.

On macOS, the one-line installer installs and opens the native menu bar app by default:

curl -fsSL https://raw.githubusercontent.com/ReScienceLab/Perch/main/install.sh | sh

The app is installed to ~/.local/share/perch/PerchApp unless PERCH_APP_INSTALL_DIR is set. The Perch icon appears in the menu bar. Open it to view active and completed sessions.

Control the app from the CLI:

perch menubar start [--app-path <path>]
perch menubar stop
perch menubar status
perch menubar login enable [--app-path <path>]
perch menubar login disable
perch menubar login status

perch menubar login enable writes ~/Library/LaunchAgents/com.resciencelab.perch.plist and uses launchctl bootstrap/enable for the current GUI user. The LaunchAgent runs with your user privileges and only launches the configured PerchApp binary. The installer opens the app after install but does not enable launch-at-login automatically.

If launch-at-login fails with permission errors, check that your terminal has the required macOS privacy permissions for writing ~/Library/LaunchAgents and running launchctl in your GUI session.

Local development still requires macOS 13+ and a Swift toolchain:

cd App
swift build
.build/debug/PerchApp

Perch also includes a Raycast extension for searching, resuming, and managing parked sessions from Raycast.

cd raycast-extension
npm install
npm run dev

Available commands:

• Search Sessions — browse ~/.config/perch/sessions.json, copy/paste project-aware resume commands, open working directories, mark sessions done, and reopen sessions.
• Add Session — manually add sessions for agents that do not yet have an installed /perch command.

Run npm run lint and npm run build in raycast-extension/ before publishing or submitting changes.

Inside a supported agent:

/perch [optional title]

Examples:

/perch
/perch Backend: add auth endpoint

If you omit the title, the agent generates a short Project: action title.

Inside a supported agent:

/perch done

Or from a terminal:

perch done <perch-id-or-prefix>
perch done --session-id <agent-session-id>

Open the Perch menu bar item, open a session's submenu, and choose Delete Session. This removes the saved Perch entry only; it does not delete the underlying agent history from Claude/Codex/Pi/etc.

Open the Perch menu bar item and click a session. Perch copies a project-aware shell command to your clipboard:

cd '/absolute/path/to/project' && claude --resume <id>
cd '/absolute/path/to/project' && pi --session <id>
cd '/absolute/path/to/project' && opencode session resume <id>

Paste it into any terminal to resume from the correct working directory.

Use this for agents that do not yet have an installed /perch command:

perch add \
  --title "MyApp: fix login" \
  --agent claude \
  --session-id <id> \
  --working-dir "$PWD"

For workspace-based agents such as Cursor/Windsurf/Trae, Perch stores the working directory and creates the appropriate resume command:

perch add --title "Site: continue CSS" --agent cursor --session-id unused --working-dir "$PWD"

perch add --title "..." --agent <agent> --session-id <id> [--working-dir <dir>] [--note "..."]  # create or update
perch list
perch list --all
perch list --all --json
perch done <perch-id-or-prefix>
perch done --session-id <agent-session-id>
perch reopen <perch-id-or-prefix>
perch reopen --session-id <agent-session-id>
perch menubar start [--app-path <path>]
perch menubar stop
perch menubar status
perch menubar login enable [--app-path <path>]
perch menubar login disable
perch menubar login status
perch doctor
perch doctor --json

perch add is an upsert keyed by agent + session_id:

• First save creates a new pending entry.
• Saving the same resumed session again updates the existing entry instead of creating a duplicate.
• Updates refresh title, working_dir, note, resume_cmd, set status back to pending, and write updated_at.
• created_at remains the original first-save timestamp.

Perch uses one shared command file. The agent identifies itself (claude, codex, pi, droid, opencode, or hermes) and runs only its own session detector.

Current fast paths and fallbacks:

• Claude Code: prefers CLAUDE_CODE_SESSION_ID, then older env vars, then the current project's ~/.claude/projects/.../sessions-index.json.
• Pi: prefers PI_SESSION_ID, then the current project's ~/.pi/agent/sessions/.../*.jsonl.
• Codex: prefers CODEX_SESSION_ID, then the latest file in ~/.codex/sessions.
• Droid: prefers DROID_SESSION_ID, then droid session list --json.
• OpenCode: prefers OPENCODE_SESSION_ID, then opencode session list.
• Hermes: prefers HERMES_SESSION_ID, then HERMES_TUI_ACTIVE_SESSION_FILE, then hermes sessions list --source cli --limit 1.

The command is intentionally strict: it should not try another agent's detector just because that binary exists on your machine.

flowchart LR
    Agent[AI coding agent] -->|/perch title| Command[Shared /perch command]
    Command --> CLI[perch CLI]
    Terminal[Terminal] --> CLI
    Raycast[Raycast extension] --> Store[(sessions.json)]
    MenuBar[macOS menu bar app] --> Store
    CLI --> Store
    Store --> Resume[Project-aware resume command]
    Resume --> Agent

Perch keeps the core simple: supported agents call the same installed command, the CLI writes local session records, and UI surfaces read the same sessions.json file.

Sessions are stored locally at:

~/.config/perch/sessions.json

Each entry looks like:

{
  "id": "perch-entry-uuid",
  "agent": "claude",
  "session_id": "agent-native-session-id",
  "working_dir": "/path/to/project",
  "title": "Project: action",
  "note": "",
  "priority": "medium",
  "status": "pending",
  "created_at": "2026-05-18T10:00:00Z",
  "updated_at": "2026-05-18T10:30:00Z",
  "resume_cmd": "claude --resume agent-native-session-id"
}

The schema is documented in schema/session.json.

Open config from the menu bar (Open Config) or edit:

~/.config/perch/config

Default file:

# Perch configuration
terminal = ghostty
sort-by = date
max-sessions = 20
auto-start = true
show-badge = true

show-badge controls whether the menu bar icon shows the pending session count. Other keys are kept for app behavior and future UI options.

Run the full test suite:

./scripts/test.sh

Run individual suites:

cargo test --manifest-path cli/Cargo.toml
cd App && swift test
./tests/install.sh
python3 tests/schema.py

Build release artifacts locally:

cargo build --release --manifest-path cli/Cargo.toml
cd App && swift build -c release

Quick checks:

perch doctor
perch doctor --json
perch list --all

Most setup issues come from one of these causes:

• ~/.local/bin is not on PATH for the shell or agent process.
• The coding agent was not restarted after installation.
• The agent does not expose a session ID and the fallback detector cannot find one.
• ~/.config/perch/sessions.json is missing or contains invalid JSON.

Add ~/.local/bin to your PATH, then restart the agent so it inherits the updated environment.

Update the relevant agent and reinstall Perch:

./install.sh

For Claude Code, newer versions expose CLAUDE_CODE_SESSION_ID to Bash tools, which is the fastest path.

Check what the CLI sees:

perch list --all

Also verify that ~/.config/perch/sessions.json exists and contains valid JSON.

Check app status:

perch menubar status

Re-run the installer with app installation enabled:

PERCH_INSTALL_APP=1 ./install.sh

If a checksum mismatch is reported, the artifact was not installed. Retry later or install from a known-good release asset.

Inspect and reset the LaunchAgent:

perch menubar login status
perch menubar login disable
perch menubar login enable

• GitHub: https://github.com/ReScienceLab/Perch
• Issues: https://github.com/ReScienceLab/Perch/issues

Perch is released under the MIT License. See LICENSE.