Pilot COS
The one agent you give tasks to. It plans each request and replies in the task thread.
One per instanceConcepts
How pods are created
You talk to one Pilot COS. It plans your request, forms a pod led by a Pod COS, hires workers for each ticket and has a second agent review the result.
You
Pilot COS
plans, budgets, approvals
Pod COS
Research podclaude
3 workersrunning
Pod COS
Build podcodex
3 workerswaiting approval
Pod COS
Review podgemini
3 workersrunning
The cast
Four roles, one chain of command
Every instance has the same shape. You give tasks to the Pilot COS. It manages everything below it.
- You
- Pilot COS
- Pod COS
- Workers
- Reviewer
Pod COS
Leads one pod. It owns the pod's tickets, staffs them with workers and keeps the pod on its mission.
One per podWorkers
Do the tickets. Each worker is hired for a role from the JD catalog and runs on an engine.
Hired per roleReviewers
A different agent from the one who did the work. It approves a ticket or sends it back, up to 2 rounds.
Max 2 roundsLifecycle
From one message to a finished pod
A task moves through fixed states. It can pause for your approval, for example when a budget cap would be crossed.
- done
1
Plan
queuedThe Pilot COS asks its engine for a plan: a summary, a pod name and mission, and a list of tickets, each with a role code.
Terminal
$ ./pilotpods ui --open2
Staff
plannedThe pod is created or reused, a Pod COS leads it, workers are hired from the JD catalog and open tickets are filed.
Terminal
$ ./pilotpods pod create research3
Work
workingOpen tickets run one per tick through each assignee's engine. A finished ticket moves to review.
Terminal
$ ./pilotpods checkin list4
Four-eye review
reviewingA different reviewer approves the ticket or sends it back to open. The limit is 2 rounds.
Terminal
$ ./pilotpods audit list5
Reply
replyingThe Pilot COS posts the summary to your task thread and the task is done.
Terminal
$ ./pilotpods statusApproval gate
Spend caps, hires and deliverables can raise an approval request. The task waits in awaiting_approval until you approve (it resumes) or reject (it is cancelled).
awaiting_approvalapprove: resumesreject: cancelled
Do it yourself
The commands behind each step
Everything the console does is also a command. Each takes --instance NAME.
Watch a pod come up
These are real commands, shortened: set up, create a pod, hire, check health.
pilotpods
$
- Each pod is a JSON file under the instance's plans/pods folder.
- Hires and approvals are written to an append only log.
- Stopping a pod leaves other pods running.
Reference
Roles and engines at a glance
Who does what
| Role | Created by | Runs on | Job |
|---|---|---|---|
| Pilot COS | Instance onboarding | Default engine | Plans requests, replies to you |
| Pod COS | Pilot COS, or pod create | Its own engine | Leads a pod, owns its tickets |
| Worker | Hire from the JD catalog | Engine set per member | Does a ticket |
| Reviewer | Hire as a different agent | Engine set per member | Approves or sends back |
Workers run on the engine you pick
An engine is the agent backend a worker calls. Claude (including Amazon Bedrock), Codex, Antigravity and Gemini can run work. Grok is monitor only, by design.
- Claudeincl. Amazon Bedrock
- CodexCLI
- Antigravitylocal app
- GeminiCLI
- Grokmonitor only
- Install state is detected live every time, never faked.
- Credentials stay in your Keychain; PilotPods stores only a reference name.
- Gemini is wired but not yet tested end to end against a real CLI. Coming soon.
Questions
Common questions
Yes. pilotpods pod create NAME makes a pod directly, and hire adds members. The Pilot COS route adds planning, staffing and review for you.
Run your first pod in minutes
Install on a Mac, create an instance, and open the console. Everything stays on your machine.
- MIT licence
- No telemetry
- CLI and console
Quick start
$ ./install.sh$ ./pilotpods init --instance default$ ./pilotpods ui --open