Pod helps a Codex or Claude Code conversation deliver a software objective through Orca. The conversation stays in charge. Pod keeps the few things nothing else keeps: what was asked, what proves it, and one gate before a merge.
On Linux, with the latest stable Python, Node/npx, curl or wget, and access to GitHub:
curl -fsSL https://raw.githubusercontent.com/j3w1/pod/main/install.sh | shThis installs the Pod skill for Codex and Claude Code and a user-local pod command. Pod has
no third-party Python dependency. A first preference file enables the supported routes (never
an ultra effort); an existing preference file is never rewritten. Open a new
shell if the installer adds ~/.local/bin to your PATH. For a download, inspect, then run
path and removal details, see installation and security.
- How it works
- The basic workflow
- Review and evidence
- Continuing later
- Models and routes
- What's inside
- Philosophy
- Updating and removing
- Contributing
Your existing authenticated session is the coordinator, with its current model and effort. Orca owns Runs, Tasks, workers, messages and worktrees. Git owns content. GitHub owns checks and merges. Your project decides what counts as accepted. Pod stores identifiers for all of those and reads them when it needs an answer, so its own record is small: an objective, its criteria, the facts that prove them, and the effects it performed.
Simple work needs no objective. Open one when the work is delivered through a pull request, uses workers, or must survive the conversation.
- Open the project in Orca and start a Codex or Claude Code conversation.
- In Codex, say
$pod https://github.com/owner/project/issues/123; in Claude Code, use/pod <issue-url>. You can also give a direct objective in a sentence. - The coordinator runs
pod open, which reads the issue and returns its criteria. A Proof of Done checklist, when the issue has one, becomes the criteria. - It works directly, or starts workers with
pod dispatch: an implementer on declared paths, a reviewer on a committed candidate, an investigator that only reads. Workers run only on model routes you enabled. - When a worker reports,
pod acceptreads its result from Orca and its diff from Git, and flags anything outside the declared paths. The coordinator states only what it did with the result. pod deliverruns the gate. It lists what is missing, or merges the exact reviewed candidate once, ticks the proved checklist items on the issue and comments the evidence.
pod status shows the picture at any time: criteria, workers, open findings and what
delivery still needs.
Whether an independent review is required is your project's rule, kept in .pod/config.yaml
on the target branch. When it is required, every file the candidate changes needs a passing
review by a worker that changed nothing.
Pod derives what a review still covers from Git: a review holds for a file while that file's content is unchanged. After a correction only the corrected files need another look, and merging the target branch reopens only files whose content changed in your candidate. Nobody declares what carries over.
Evidence is recorded only when it was observed and always names its exact commit. Worker success, local checks, hosted checks, independent review and the merge are separate facts. Something that could not be read stays unknown.
A merge needs your authorization: your words recorded for the exact commit, a standing one
for the objective, or your host's verifier. Set merge_authorization: coordinator in your
preference file if you want the coordinator to decide.
Objectives are not tied to a terminal or a conversation. Start a new conversation in the
objective's worktree and it runs pod resume: Orca moves the Run to it, and the status shows
where things stand, including the note the earlier conversation left. An objective closes by
itself once its delivery is merged and no criterion is open.
The command that ends an objective (pod deliver, a pod record that meets its last
criterion, or pod drop) also cleans up after it. It asks Orca to release the objective's
finished workers and to remove the worktrees it had Orca create for them, when Git shows they
are clean and hold nothing undelivered. Anything running, changed, unmerged or in use stays
and is named, and a terminal you kept open is left alone unless it is the worker's own
terminal in such a worktree, which goes with the worktree. To retry, run pod deliver again,
or pod drop again for a dropped objective.
pod models opens a keyboard-driven workspace in your terminal: every exact model and effort
route Pod can use, what the installed agents report, public benchmark observations, and your
choices. Enable or disable routes, set a Preferred route or a Pin. Press R, or run
pod models refresh, to fetch the public leaderboard; nothing else touches the network.
A green * marks a benchmark cost that is high value: no other routable route costs less
while scoring no more than two index points lower, and its index is in the upper half. Both
comparisons are among routable routes with a measured index and cost, whether or not you
enabled them; rows with an estimated index or a fallback profile take no part. Benchmark cost is not a
subscription charge, a quota or a task duration, and a public listing never makes a route
usable or changes a preference. Only you change your preferences.
pod config shows the preference file and what it enables.
- The skill (
skills/pod/SKILL.md): how a coordinator decides how much process a task needs, and the eight commands. - The command (
pod open,dispatch,accept,record,status,deliver,resume,drop; plusconfig,models,doctor,update,export). - Authoring templates for PES, SEAL and EEL documents, for those who use them.
- Architecture: the five concepts, derived proof, the gate and the interfaces a host may use.
Pod is a lightweight coordinator. The process a task needs is set by the task. Pod keeps only what no other system owns, derives the rest, never asks a coordinator for what software can compute, and never records what was not observed. Pod's Enduring Design Principles hold the reasoning.
Run pod update to fetch the current main bundle through the same staged installer. It
never rewrites your preference file. Records written by Pod 0.21 are left untouched;
pod export --to DIR writes them to plain JSON. See
the removal map before deleting anything. There are no release
packages or tags.
Start with AGENTS.md for contributor reading triggers and completion criteria.
The root VERSION is the only authored product version.
MIT. See LICENSE.