perk 1.1.0

Plan-oriented engineering workflow for Pi (the CLI exterior / session host).

perk

A Pi-native, plan-oriented engineering workflow: a Python perk CLI (the session exterior) plus a TypeScript Pi extension (the session interior).

Inspired by erk, formely maintained by the team at dagster

perk was built with perk.

What perk is

perk implements a plan-oriented engineering workflow (plan → implement → submit → review → address → land → learn) for Pi, split across two planes:

• the exterior — a Python perk CLI that scaffolds repos, positions worktrees, mints run ids, and launches primed pi sessions (everything that happens outside a session);
• the interior — a TypeScript Pi extension that drives stage transitions and state inside a running session.

A language-neutral shared/ contract (the stage registry + cross-plane specs) is the single source both planes read, hopefully staying in lockstep without codegen.

Quickstart

perk targets any git repo. From the repo you want to wire:

uv tool install perk        # (or run from source — see Develop)
perk init                   # scaffold/converge Pi wiring (idempotent; safe to re-run)
perk doctor                 # report health; perk doctor --fix repairs drift

perk init requires a git repo + git, gh, node ≥ 22, ast-grep, and pi on PATH. GitHub auth is verified but never required (it is reported, never fatal).

For the guided first run, follow Get started with perk.

Documentation

The operator-facing docs live under docs/user-docs/, organized as:

• Tutorials — learning-oriented lessons; start with Get started with perk.
• How-to guides — goal-oriented recipes (resume a plan, address review feedback, switch to Linear, attach a skill, …).
• Reference — the CLI surface, in-session commands & tools, the objective roadmap model, configuration, and providers & backends.
• Explanation — how perk thinks; headless/remote maturity.

perk's internal research and planning record lives under docs/ and is for perk's own developers.

Layout

• perk/ — the Python CLI (the session exterior).
• extension/ — the TypeScript Pi extension (the session interior).
• shared/ — cross-plane contracts (the stage registry + specs), bundled into both build artifacts.
• docs/ — research inputs, design notes, and durable learnings.

Develop

Two pinned toolchains:

• Python — uv (3.13, pinned in .python-version), ruff (lint/format), ty (types).
• TypeScript — npm (Node ≥ 22, .npmrc), Biome (lint/format), tsc (types).

With just:

just setup        # uv sync + npm install + git hooks + install-cli (the `perk` CLI on PATH)
just install-cli  # just the `perk` CLI on PATH (editable: tracks this clone)
just fmt          # ruff format + biome format
just lint         # ruff check + biome check
just typecheck    # ty + tsc
just test         # pytest + node:test (the regression gate)
just ci           # setup + lint + typecheck + test

just setup also runs just hooks (prek install), wiring a prek pre-commit hook that runs ruff check on staged Python (config in prek.toml; the ruff env is built by prek from the remote ruff-pre-commit repo, so it never depends on a system/.venv ruff). Re-run just hooks after a fresh clone.

Without just: uv run … for Python (uv run perk init, uv run pytest, uv run ruff check perk tests, uv run ty check) and npm run … for TypeScript (npm run lint, npm run typecheck).