Perch

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.

Why Perch?

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.

Common Use Cases

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.

60-Second Quick Start

Install the Perch CLI and supported agent /perch commands:

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

Then:

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

perch doctor

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

Demo

# 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.

Highlights

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.

Feature Checklist

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

Supported Agents

Agent	`/perch` install	Resume command
Claude Code	Automatic	`claude --resume <id>`
Codex	Automatic	`codex resume <id>`
Pi	Automatic	`pi --session <id>`
Droid	Automatic	`droid --resume <id>`
OpenCode	Automatic	`opencode session resume <id>`
Hermes	Automatic	`hermes --resume <id>`
Goose	Manual CLI add	`goose session -r --name <id>`
Kiro	Manual CLI add	`kiro-cli chat --resume-id <id>`
Windsurf	Manual CLI add	`windsurf <working-dir>`
Cursor	Manual CLI add	`cursor <working-dir>`
Trae	Manual CLI add	`trae <working-dir>`
Amp	Manual CLI add	`amp threads continue <id>`

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.

Install

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.

Installed command locations

Agent	Installed file
Claude Code	`~/.claude/commands/perch.md`
Codex	`~/.codex/skills/perch/SKILL.md`
Pi	`~/.pi/agent/skills/perch/SKILL.md`
Droid	`~/.factory/skills/perch/SKILL.md`
OpenCode	`~/.config/opencode/commands/perch.md`
Hermes	`~/.hermes/skills/perch/SKILL.md`

Menu Bar App

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

Raycast Extension

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.

Usage

Save the current session

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.

Mark the current session done

Inside a supported agent:

/perch done

Or from a terminal:

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

Delete a saved session

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.

Resume a session

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.

Add a session manually

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"

CLI Reference

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

Save Semantics

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.

How `/perch` Finds the Current Session

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.

Architecture

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.

Data Storage

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.

Configuration

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.

Development

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

Troubleshooting

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.

`/perch` says `perch: command not found`

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

`/perch` cannot determine the session ID

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.

The menu bar app shows no sessions

Check what the CLI sees:

perch list --all

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

The menu bar app did not install or start

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.

Launch at login is not working

Inspect and reset the LaunchAgent:

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

Links

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

License

Perch is released under the MIT License. See LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 89 Commits
.claude		.claude
.github/workflows		.github/workflows
.hal		.hal
.pi		.pi
App		App
Commands		Commands
assets		assets
cli		cli
raycast-extension		raycast-extension
schema		schema
scripts		scripts
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
install.sh		install.sh

Folders and files

Latest commit

History

Repository files navigation

Perch

Why Perch?

Common Use Cases

60-Second Quick Start

Demo

Highlights

Feature Checklist

Supported Agents

Install

Installed command locations

Menu Bar App

Raycast Extension

Usage

Save the current session

Mark the current session done

Delete a saved session

Resume a session

Add a session manually

CLI Reference

Save Semantics

How /perch Finds the Current Session

Architecture

Data Storage

Configuration

Development

Troubleshooting

/perch says perch: command not found

/perch cannot determine the session ID

The menu bar app shows no sessions

The menu bar app did not install or start

Launch at login is not working

Links

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 6

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

How `/perch` Finds the Current Session

`/perch` says `perch: command not found`

`/perch` cannot determine the session ID

Packages