Perry runs the office. You run the project.
Perry is a skill for Claude Code and Codex CLI that keeps track of your project for you: what you're trying to achieve, what's being worked on right now, what's blocking you, and what was decided and why.
You talk to it with one command: /perry.
It keeps everything in plain markdown files inside your project folder, so you can read them, edit them, and commit them like any other file. Nothing is hidden in a database.
| You want to… | Perry gives you |
|---|---|
| Know where the project stands | A one-screen snapshot every time you type /perry |
| Set goals and actually track them | An OKR file, plus a "current phase" with its own goals |
| Run a task list without a tracker | A board of open tasks with owners, priorities and blockers |
| Stop losing context between sessions | A daily journal and a handoff note you can start tomorrow from |
| Remember why you chose something | A decision log (one file per decision) |
| Think a feature through before building | A design doc / RFC with the open questions listed for you to answer |
| Hand work to an AI agent | Written task specs and one-command dispatch to another agent session |
| Digest a PDF, spreadsheet or long doc | A short structured summary Perry can cite later instead of re-reading it |
Perry is built for one person or a small team. It gives you structure without meetings, tickets, or process for its own sake.
setup finds whichever agent you have (claude and/or codex) and installs Perry for it.
Paste this into a fresh Claude Code or Codex CLI session:
Install the Perry skill set from https://github.com/ranjiao/Perry.
Steps:
1. Run: git clone https://github.com/ranjiao/Perry.git ~/perry && ~/perry/setup --yes-deps
2. Read setup's output. If it lists "Skipped installs" or asks for Xcode CLT / Homebrew, tell me — those need my permission.
3. Confirm /perry is available.
Or install it yourself:
git clone https://github.com/ranjiao/Perry.git ~/perry &&~/perry/setup~/perry is only a suggestion — any folder works.
Options:setup --claude or setup --codex to force one host, setup --claude --codex for both.
Update:cd ~/perry && git pull (Perry also reminds you about once a week).
Details, dependencies and Codex differences: INSTALL.md.
Type /perry in your project folder. It will ask two quick questions (what language to write in, and how your repo is laid out), then walk you through:
/perry okr init # a short interview → your goals
/perry okr plan-phase <name> # goals for the current stretch of work
/perry pmo # sets up the task board
/perry okr plan-week # proposes 3–5 tasks for this week; you approve
That's roughly 15 minutes and you're set up.
Don't start from a blank page — Perry can read what's already there:
/perry adopt
It reads your README, roadmap, git history, existing design notes, TODOs and issues, then proposes goals, tasks and decisions. Nothing is written until you say yes.
/perry diagnose
This looks at how your project is set up for working with AI agents and tells you what's actually wrong — sessions stepping on each other, too many stale markdown files, no way to tell what's done. It works on any folder, and "your setup is fine, change nothing" is a perfectly normal answer. It never installs Perry without asking.
Just type /perry to see where things stand. From there:
| I want to… | Type |
|---|---|
| See the whole picture | /perry |
| See what's available | /perry help |
| Plan this week | /perry okr plan-week |
| Add a task | /perry pmo add-task |
| Check what's stuck | /perry pmo triage |
| Mark something done | /perry pmo close-task <id> |
| Give a task to an AI agent | /perry pmo dispatch <id> |
| Write down a decision | /perry pmo decide <topic> |
| Write this week's status | /perry pmo friday-review |
| Save context before you stop | /perry pmo handoff |
| Start a design doc | /perry design new <name> |
| Open a live view in your browser | /perry pmo viewer |
You can drop the lane name when it's unambiguous — /perry plan-week and /perry okr plan-week are the same thing.
Everything lives under /perry. Inside it there are three areas, so Perry knows which kind of work you mean.
Two levels. Overall goals (OKR.md) are your mission and 1–3 objectives; they change rarely, and old versions stay in the file so you can see how your thinking moved. The current phase (phase/002-release-pipeline.md) is what you're doing right now.
A phase is not a month. It ends when its key results are hit — that might be 3 days or 8 weeks. No calendar theater, no month-end retro for work that finished on day 5.
| Command | Does |
|---|---|
init | Interview → your overall goals |
plan-phase <name> | Start a new phase |
plan-week | Propose this week's tasks |
snapshot | Save the current phase state without ending it |
score-phase | Close the phase and score each key result |
revise / pivot | Change the goals (deliberately a bit of work, so pivots are visible) |
dashboard | Detail per objective |
The task board, the daily journal, decisions, status reports and handoffs. This is where most of your day happens.
| Command | Does |
|---|---|
triage | Walk the board, flag anything stale or stuck |
add-task / close-task / drop-task | Task lifecycle |
delegate <id> | Write a prompt you paste into another agent session |
dispatch <id> | Send the task to an agent and collect the result automatically |
autopilot | Dispatch everything that's safe to dispatch while you're away |
digest <file> | Turn a PDF / spreadsheet / long doc into a short summary Perry can reuse |
decide <topic> | Record a decision (with context, options and consequences) |
monday-plan / midweek-check / friday-review | Weekly rhythm |
mid-phase-review / end-phase-retro | Phase checkpoints |
handoff | Write a note so tomorrow's session starts informed |
risk / nudge | Review risks; chase things waiting on you |
incident <name> | Record what broke in production and what you changed |
viewer | Open a live browser view of the project |
For anything worth thinking through first: multi-part changes, hard-to-undo choices, or anything with several open questions only you can answer. Perry drafts the doc, lists the decisions you need to make, then walks you through them one at a time.
| Command | Does |
|---|---|
new <name> | Start a design doc |
decide <id> | Answer the open questions one by one |
lock <id> | Freeze it; Perry proposes the tasks to build it |
revise / supersede / drop | Change it later |
status | Where each doc stands |
These exist because they're what stops a project quietly going wrong.
- "Done" needs proof. You can't mark a task done without pointing at something real — a file, a commit, command output. "Looks good" and "the agent says it's finished" are rejected.
- Each file has one owner. The goal files, the board and the design docs are written by different lanes and never by each other. This is what keeps things from being overwritten.
- Important files stay short. The files you need to read — goals, phase, architecture — have size limits. When something would overflow, Perry moves the detail into a side file and leaves a summary. The point is that you can still read them in one sitting.
- Perry never makes up a number. If it doesn't know, it prints
—and asks you. - IDs always come with names. You'll see
REL-002 ("Flake detector"), never a bare code you'd have to look up.
All plain markdown, all yours:
your-project/
├── .perry/config.md your settings (language, layout)
├── OKR.md overall goals
├── phase/ the current stretch of work + saved snapshots
├── BOARD.md open tasks, right now
├── journal/ what happened each day
├── DECISIONS.md index of decisions
├── decisions/ one file per decision, with the reasoning
├── design/ design docs / RFCs
├── evidence/ proof that tasks were finished
├── weekly/ weekly status reports
├── handoff/ notes to your next session
├── inputs/ + knowledge/ documents you gave Perry, and its summaries
└── ... your actual project files
A few more appear only if you use them: ARCHITECTURE.md (a system overview you own, that every dispatched agent must respect), runbook/ (how to operate what you've deployed), incidents/ (what went wrong in production).
Everything is optional and created on demand. Perry doesn't scaffold 20 folders on day one.
Markdown is great to write and diff, less great to read once there's a lot of it. Two options:
- aiMark — point it at your project folder; it renders everything live and understands Perry's structure. Reloads the moment a file changes.
/perry pmo viewer— a zero-setup local page (Today / Board / OKR / Phase / Risks / Architecture). Read-only, runs on your machine, stops with Ctrl-C. First run installs itself; ignore it and you carry no extra dependencies.
Perry is written in English; your project doesn't have to be. At first-time setup it records two separate settings:
- Document language — what gets written into files: goals, task titles, journal entries, decisions, design docs.
- Chat language — what Perry says to you in conversation. Defaults to mirroring whatever you type.
They're separate on purpose: an English open-source project you think about in Chinese works fine, and so does the reverse.
Some things stay English in every language, so tools keep working: IDs (REL-002), status words (in_progress, blocked), file names, dates, paths and command names. So a Chinese board row reads:
| REL-002 | 抖动检测器 | Coding Agent | blocked | 等 USER-014 | evidence/… |
Any language works for prose. Details, and how to switch later: reference/i18n.md.
/perry okr init # set your goals
/perry okr plan-phase mvp # goals for this stretch
/perry okr plan-week # this week's tasks — you approve them
/perry # every morning: where are we
... work ...
/perry pmo dispatch REL-002 # hand a task to an agent
/perry pmo close-task REL-002 # done, with evidence
/perry pmo decide caching # write down why you chose Redis
/perry pmo friday-review # this week's status
/perry pmo handoff # before you stop
/perry pmo end-phase-retro # key results mostly hit → wrap up
/perry okr score-phase # score it
/perry okr plan-phase beta # next phase
Do I have to use all of it? No. Plenty of people only use the board and the journal. Every file is created when first needed.
Does it work without a git repo? Yes. Git makes the history nicer but nothing requires it.
Can I use it for non-code projects? Yes — research, writing, ops, business planning. /perry diagnose even recognises those as different project types.
What if my project already has a design/ folder? Perry asks. You can put all of its files under a subfolder (perry/) and leave your tree untouched.
Can I add my own commands? Yes. A new lane is a folder with a SKILL.md that declares which files it owns and never writes to anyone else's. That single rule is what lets the set grow.
- INSTALL.md — install details, dependencies, Claude Code vs Codex differences
- reference/i18n.md — writing in another language
- reference/diagnose.md — how the project audit works
- reference/adoption.md — how adopting an existing project works
- schema/README.md — the file format, if you're building something that reads Perry's files