Skip to main content

Perch Developer Onboarding Spec

1. Overview

Perch should provide a frictionless developer onboarding path where users can install the CLI and supported agent /perch commands with a single shell command.

This spec covers:

  1. Path B: developer one-line install
  2. perch doctor diagnostic command
  3. GitHub Release artifacts for prebuilt CLI
  4. README 60-second Quick Start

Important scope decisions:

  • Perch does not need to install Perch.app.
  • Primary users are developers using terminal-based AI coding agents.
  • Installer should use the latest GitHub Release by default.
  • Installer should automatically open Perch after install only if an app is already available locally; otherwise it should skip app handling.
  • No launch-at-login support is required.
  • No .app release artifact is required.

2. Goals

G-1: Enable one-line developer installation

A developer should be able to run:

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

and get a working Perch CLI plus /perch support in detected agents.

G-2: Avoid local Rust requirement for normal users

Users should not need Rust or Cargo installed for normal installation.

G-3: Install from latest GitHub Release

The installer should download the latest prebuilt CLI binary from GitHub Releases by default.

G-4: Provide setup diagnostics

Users should be able to run:

perch doctor

to verify their installation and receive actionable fix suggestions.

G-5: Improve README onboarding

The README should begin with a 60-second Quick Start focused on developer usage.

3. Target User Flow

3.1 One-line install flow

User runs:

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

Installer performs:

  1. Detects OS and CPU architecture.
  2. Downloads matching prebuilt perch CLI from the latest GitHub Release.
  3. Installs CLI to:
~/.local/bin/perch
  1. Creates config directory:
~/.config/perch/
  1. Creates session storage if missing:
~/.config/perch/sessions.json
  1. Creates default config if missing:
~/.config/perch/config
  1. Detects supported agent CLIs in PATH.
  2. Installs /perch command or skill files for detected agents.
  3. If a local Perch.app is available, automatically opens it.
  4. Prints clear install summary and next steps.

Example output:

Perch installer

Detected:
  OS: macOS
  Arch: arm64

Installing CLI:
  ✓ Downloaded perch-aarch64-apple-darwin from latest GitHub Release
  ✓ Installed to ~/.local/bin/perch

Installing agent commands:
  ✓ Claude Code → ~/.claude/commands/perch.md
  ✓ Pi → ~/.pi/agent/skills/perch/SKILL.md
  - Codex not found
  - OpenCode not found
  - Droid not found

Configuration:
  ✓ ~/.config/perch/sessions.json
  ✓ ~/.config/perch/config

Opening Perch:
  - Perch.app not found locally, skipped

Next steps:
  1. Make sure ~/.local/bin is in your PATH.
  2. Restart your coding agent.
  3. Type /perch inside a coding session.
  4. Run perch doctor to verify your setup.

4. Functional Requirements

4.1 Installer

FR-1: One-line install support

install.sh must support being executed remotely:

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

Because remote-piped scripts do not have access to repo-local files, install.sh must not require:

Commands/perch.md
cli/Cargo.toml
App/

in remote mode.

FR-2: Install modes

The installer must support two execution contexts.

Remote mode

When run through curl | sh, the installer should:

  • Download prebuilt CLI from latest GitHub Release.
  • Download command template from GitHub.
  • Not require local source files.
  • Not require Cargo.
  • Not install Perch.app.

Local repo mode

When run from a cloned repo:

./install.sh

the installer may use local files where available, especially:

Commands/perch.md

It should still prefer the latest release CLI unless explicitly configured otherwise.

FR-3: CLI binary installation

The installer must install the perch CLI to:

~/.local/bin/perch

It must:

  • Create ~/.local/bin if missing.
  • Mark binary executable.
  • Verify binary runs via:
~/.local/bin/perch --help

or equivalent.

FR-4: Platform detection

Minimum supported matrix:

OSArchArtifact
macOSarm64perch-aarch64-apple-darwin
macOSx86_64perch-x86_64-apple-darwin

Unsupported platforms should fail clearly:

Perch prebuilt binaries are currently available for macOS only.

FR-5: Latest release by default

The installer must download from latest GitHub Release by default:

https://github.com/ReScienceLab/Perch/releases/latest/download/<artifact>

No user-provided version is required for MVP.

Optional future enhancement:

PERCH_VERSION=v0.2.0 sh install.sh

FR-6: CLI fallback build in local mode only

If the release binary cannot be downloaded:

  • In remote mode: fail with a clear error.
  • In local repo mode: fallback to cargo build only if Cargo is available.

Fallback command:

cargo build --release --manifest-path cli/Cargo.toml

Then install:

cli/target/release/perch

FR-7: Agent command installation

Installer must install /perch support for detected agents.

AgentDetectionInstall path
Claude Codecommand -v claude~/.claude/commands/perch.md
Codexcommand -v codex~/.codex/skills/perch/SKILL.md
Picommand -v pi~/.pi/agent/skills/perch/SKILL.md
Droidcommand -v droid~/.factory/skills/perch/SKILL.md
OpenCodecommand -v opencode~/.config/opencode/commands/perch.md

Skill-based command files must include frontmatter:

---
name: perch
description: 'Save current AI coding agent session to Perch, or mark it as done'
disable-model-invocation: true
---

Command-based installs should use the raw markdown command body.

FR-8: Remote command template fetch

In remote mode, installer must fetch:

https://raw.githubusercontent.com/ReScienceLab/Perch/main/Commands/perch.md

This is acceptable for MVP.

Future improvement: fetch version-matched command template from release assets.

FR-9: Config initialization

Installer must create:

~/.config/perch
~/.config/perch/sessions.json
~/.config/perch/config

It must not overwrite existing files.

Default sessions.json:

[]

Default config:

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

FR-10: Automatic opening behavior

Installer should attempt to automatically open Perch only if a local app already exists.

Check paths:

/Applications/Perch.app
~/Applications/Perch.app

If found, run:

open -a Perch

or:

open /Applications/Perch.app

If not found, skip without failure:

Opening Perch:
  - Perch.app not found locally, skipped

Installer must not download or install Perch.app.

FR-11: No app release artifact required

The release process does not need to publish:

Perch.app.zip
Perch.dmg

Only CLI binaries are required.

5. perch doctor

5.1 Overview

Add a CLI command:

perch doctor

It should diagnose the local developer installation.

5.2 Functional Requirements

FR-D1: Check CLI location

Doctor should report:

  • Current executable path.
  • Whether ~/.local/bin/perch exists.
  • Whether ~/.local/bin is in PATH.

Example:

CLI:
  ✓ perch found at /Users/alice/.local/bin/perch
  ✓ ~/.local/bin is in PATH

If PATH is missing:

PATH:
  ! ~/.local/bin is not in PATH

Fix:
  Add this to your shell profile:
    export PATH="$HOME/.local/bin:$PATH"

FR-D2: Check config files

Doctor should verify:

~/.config/perch/
~/.config/perch/sessions.json
~/.config/perch/config

It should validate that sessions.json is valid JSON.

Example:

Storage:
  ✓ ~/.config/perch exists
  ✓ sessions.json exists and is valid JSON
  ✓ config exists

FR-D3: Check agent binaries

Doctor should check for:

claude
codex
pi
droid
opencode

Example:

Agents:
  ✓ Claude Code detected: /opt/homebrew/bin/claude
  ✓ Pi detected: /opt/homebrew/bin/pi
  - Codex not found
  - Droid not found
  - OpenCode not found

Missing optional agents should not be failures.

FR-D4: Check installed agent commands

Doctor should verify expected command/skill files.

Example:

Agent commands:
  ✓ Claude Code command installed
    ~/.claude/commands/perch.md

  ✓ Pi skill installed
    ~/.pi/agent/skills/perch/SKILL.md

  ! Codex detected but Perch skill is missing
    Expected: ~/.codex/skills/perch/SKILL.md
    Fix: rerun install.sh

FR-D5: App check is optional and non-blocking

Because Perch.app is not required for this developer onboarding path, perch doctor should either:

  • omit app checks entirely, or
  • show only an informational note.

Recommended output:

Menu bar app:
  - Optional for developer install; not checked

Missing app must not affect exit code.

FR-D6: Exit codes

ConditionExit code
All required checks pass0
Warnings only0
Required check failed1

Required failures:

  • ~/.local/bin/perch missing.
  • ~/.local/bin missing from PATH.
  • Config directory missing.
  • sessions.json missing or invalid.
  • Config file missing.

Non-failures:

  • Optional agent missing.
  • Optional app missing.
  • Agent detected but command missing: warning for MVP, not hard failure.

FR-D7: JSON output

Recommended but optional:

perch doctor --json

6. GitHub Release CLI Artifacts

6.1 Required artifacts

Each release should publish:

perch-aarch64-apple-darwin
perch-x86_64-apple-darwin
checksums.txt

No app artifact is required.

6.2 GitHub Actions workflow

Add:

.github/workflows/release.yml

Trigger:

on:
  push:
    tags:
      - "v*"
  workflow_dispatch:

Workflow should:

  1. Check out repo.
  2. Install Rust stable.
  3. Add macOS Rust targets.
  4. Build CLI for arm64 macOS.
  5. Build CLI for x86_64 macOS.
  6. Rename binaries.
  7. Generate checksums.
  8. Upload artifacts to GitHub Release.

6.3 Build commands

rustup target add aarch64-apple-darwin x86_64-apple-darwin

cargo build --release --manifest-path cli/Cargo.toml --target aarch64-apple-darwin
cargo build --release --manifest-path cli/Cargo.toml --target x86_64-apple-darwin

Expected outputs:

cli/target/aarch64-apple-darwin/release/perch
cli/target/x86_64-apple-darwin/release/perch

Rename to:

perch-aarch64-apple-darwin
perch-x86_64-apple-darwin

6.4 Checksums

Generate:

shasum -a 256 perch-aarch64-apple-darwin perch-x86_64-apple-darwin > checksums.txt

Installer checksum verification is optional for MVP.

7. Installer Design

7.1 Supported environment variables

VariablePurposeDefault
PERCH_INSTALL_DIRCLI install directory$HOME/.local/bin
PERCH_REPOGitHub repo overrideReScienceLab/Perch
PERCH_OPEN_APPAttempt to open local app if found1

No version variable is required for MVP because installer uses latest release.

7.2 URL resolution

Artifact URL:

https://github.com/ReScienceLab/Perch/releases/latest/download/<artifact>

Command template URL:

https://raw.githubusercontent.com/ReScienceLab/Perch/main/Commands/perch.md

7.3 Idempotency

Installer may overwrite:

~/.local/bin/perch
agent command files

Installer must not overwrite:

~/.config/perch/sessions.json
~/.config/perch/config

7.4 Error handling

Fail on:

  • Unsupported OS/arch.
  • CLI release download failure in remote mode.
  • CLI release download and local fallback both fail in local mode.
  • CLI installed but not executable.
  • Config directory cannot be created.

Warn but continue on:

  • Agent not found.
  • Agent command directory needs creation.
  • Perch app not found locally.
  • Auto-open app fails.

8. README 60-Second Quick Start

README should begin with:

## 60-Second Quick Start

Install Perch:

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

Restart your coding agent so it can find the perch CLI.

Inside Claude Code, Codex, Pi, Droid, or OpenCode, save your current session:

/perch Fix auth endpoint

Later, list saved sessions:

perch list

Or run a setup check:

perch doctor

Perch stores sessions locally in:

~/.config/perch/sessions.json

The installer:

  • Installs perch to ~/.local/bin/perch
  • Installs /perch into detected supported agents
  • Creates local config and session storage
  • Uses the latest GitHub Release CLI binary

Existing source-build instructions should move under:

```md
## Development Install

9. User Stories

US-001: One-line developer install

Description: As a developer, I want to install Perch with one command so I can use /perch without cloning or building the repo.

Acceptance Criteria:

  • curl -fsSL .../install.sh | sh installs CLI.
  • Installer downloads CLI from latest GitHub Release.
  • Installer creates config files if missing.
  • Installer installs commands for detected agents.
  • Installer prints clear next steps.
  • Installer does not require Cargo or Swift.

US-002: Local repo install still works

Description: As a contributor, I want ./install.sh to keep working from a cloned repo.

Acceptance Criteria:

  • Running ./install.sh succeeds.
  • Installer can use local Commands/perch.md.
  • Installer prefers latest release CLI.
  • Installer falls back to local Cargo build if release download fails.

US-003: Diagnose setup

Description: As a user, I want to run perch doctor so I can fix setup issues quickly.

Acceptance Criteria:

  • Checks CLI location.
  • Checks PATH.
  • Checks config files.
  • Validates sessions.json.
  • Checks supported agent binaries.
  • Checks installed command files.
  • Provides actionable fix suggestions.
  • Does not fail because app is missing.

US-004: Publish prebuilt CLI

Description: As a user, I want GitHub Releases to include prebuilt CLI binaries so install is fast and toolchain-free.

Acceptance Criteria:

  • Tagged release publishes arm64 macOS CLI.
  • Tagged release publishes x86_64 macOS CLI.
  • Tagged release publishes checksums.txt.
  • No app artifact is required.
  • Installer downloads latest release artifact.

US-005: Quick Start README

Description: As a new developer user, I want README to show the shortest path first.

Acceptance Criteria:

  • README starts with 60-second Quick Start.
  • Quick Start includes one-line install.
  • Quick Start explains restarting the coding agent.
  • Quick Start shows /perch.
  • Quick Start shows perch doctor.
  • Build-from-source docs are below primary install docs.

10. Non-Goals

Out of scope:

  • Installing Perch.app.
  • Releasing Perch.app.zip.
  • Releasing .dmg.
  • Launch-at-login.
  • Code signing.
  • Notarization.
  • Windows support.
  • Linux support.
  • Homebrew formula.
  • Auto-update.
  • GUI onboarding.
  • New agent integrations beyond current automatic install targets.

11. Suggested Implementation Order

Phase 1

  1. Add perch doctor.
  2. Update README with 60-second Quick Start.
  3. Refactor installer summary output.

Phase 2

  1. Make install.sh remote-safe.
  2. Download CLI from latest GitHub Release.
  3. Download command template from GitHub in remote mode.
  4. Preserve local repo fallback.

Phase 3

  1. Add release workflow.
  2. Build macOS arm64 CLI.
  3. Build macOS x86_64 CLI.
  4. Publish checksums.
  5. Validate one-line install against latest release.

12. Final Open Questions

None for MVP.