An AI as the P.O. of my agent fleet
How I use Orca to orchestrate a fleet of coding agents: harness, worktrees, skills, MCPs and always-human merges.
On this page
I still build software every day. What changed is where my time pays off most: instead of typing every line, I design and supervise a system where agents do the typing. Claude Code and Codex CLI work in isolated copies of the repository, inside Orca, an IDE built exactly for this. And an AI acts as the team's P.O., running the day-to-day, while product decisions, review and the merge stay with me.
The whole setup in one paragraph:
I use Orca with an AI acting as P.O. and orchestrator: it prioritizes tasks in Linear, writes briefings, follows specialized agents working in isolated child worktrees, answers blockers and validates tests, security and isolation. When everything is approved, it merges, updates Linear and cleans up the runs, while I stay responsible for the product decisions.
This post unpacks that paragraph piece by piece: the problem the setup solves, the concepts behind it, Orca in depth, the P.O.'s job and the limits of all of it. Building this pipeline took real engineering work, and nothing here is theory: it is what runs on my workstation right now, defects included. A note on the figures: they are in Portuguese (they come from a deck I made for a talk in Brazil), but the text carries everything in English.
The problem: you are the bottleneck#
Almost everyone uses AI for coding the same way: ask in the chat, copy the answer, paste it into the editor, hit an error, copy the error, paste it back. Repeat until it works, or until you give up.
It works. I started like this. But look at the drawing: the one carrying context back and forth is you. You became the data bus between the model and your project.
And the problem is not the model's intelligence. It is access and verification. In the chat, the model only sees the text you paste. It cannot see the rest of the repository, it runs nothing, it never learns whether the code compiled, and memory resets on every round. Your project needs exactly the opposite: the whole repository as context, tests actually running, memory that survives between sessions and more than one front moving at once. In the middle of that gap stands you, pasting things, one chat at a time.
The thesis: the value is in the harness#
The thesis holding everything else up: the value is not just in the model. It is in the harness, in the environment you build around it. Context engineering beats prompt engineering.
Whoever structures the agent's environment multiplies their own productivity. In practice, you stop being a typist and become the engineering manager of a team that never sleeps. Before: one dev feeding one chat. After: one dev supervising N agents, with PRs, review and merge. The rest of the post is the how.
The pieces#
There are six pieces, and each solves one specific limitation of the chat. None of them is magic. The magic is the sum.
Harness and agent#
Nobody drives an engine. You drive a car. The LLM is the engine; the harness is the car that gives it hands and eyes: reading files, running commands, editing code, iterating in a loop. Claude Code and Codex CLI are the ones I use.
And the harness is what turns a model into an agent. My operational definition, because the word is worn out: an agent is when the model closes its own feedback loop. It writes, runs the test, reads the error, fixes it, runs again. No human in the middle. The practical difference is brutal: the chat hands you something plausible; the agent hands you something tested.
MCP#
MCP is the Model Context Protocol, the standard that plugs tools and data into the agent. People call it the USB-C of AI, and the comparison is fair: before it, every integration was a hack; now it is a plug.
A real example from here: my orchestrator reads the Linear issue directly. I copy nothing. But here is the honest warning: integration has a cost. Every MCP consumes memory and context, and a headless browser MCP spins up a Chrome of around 470 MB. I removed the browser ones from my default. Plug in only what you use.
Skill#
A skill is a best practice, packaged and executable. The checklist I would run by hand becomes a procedure that any agent of mine executes the same way. It does not pollute the context: the agent loads it only when needed.
Real examples from my day: UI review, requirements interview, integration spec scaffolding. This is how experience becomes an asset. Write it once, every agent on the team inherits it.
Git worktree#
The piece almost nobody knows, and it is native to git. Worktree creates N working copies of the same repository. One worktree per task, each agent with its own branch, files and terminal. Same repo, parallel universes.
This is what unlocks real parallelism: four tasks moving at the same time without one agent stepping on another agent's files. Without worktrees, an agent fleet turns into a merge fight.
Plan mode and permissions#
House rule: no agent of mine implements anything without an approved plan. The agent plans, I (or the orchestrator) approve, it executes. It costs two minutes and avoids hours of rework, because a plan error is the expensive error.
Full autonomy is marketing. Calibrated autonomy is engineering.
The repo constitution#
And there is a seventh piece, invisible, holding the other six together:
structured context. My repo has a constitution file (CLAUDE.md, AGENTS.md,
the name matters less than the habit) with the architecture rules, what NEVER
to do, the sensitive files that require extra review and the lessons learned.
Every agent, from any vendor, reads it before acting.
What we learn by breaking things becomes persistent memory: the machine remembers forever that the local postgres uses port 5433, not 5432. The agent is only as good as the context you structure. Context is the product. The prompt is just the interface.
Orca: the fleet IDE#
All of this runs inside Orcaopens in a new tab, and it deserves its own section, because it is the piece that turned the setup from a pile of open terminals into a system.
Orca is an ADE, an Agent Development Environment: an IDE designed from scratch for working with agents in parallel, not a traditional editor with AI grafted on. It is open source (MIT), by stablyai, and runs on macOS, Windows and Linux, with a headless mode on a VPS over SSH for anyone who wants the fleet off their local machine.
The central concept is the same as piece 5: every task becomes an isolated worktree. The difference is what Orca hangs on each one. Every worktree is born with its own terminal (WebGL rendering, splits, scrollback that survives restarts), an embedded Chromium browser and a diff view with line-by-line comments. Each worktree becomes a card with status; the whole fleet is visible on one screen, and commit and merge happen without leaving the app.
A few features that change the game in real use:
- Any CLI agent. Claude Code, Codex, Cursor, OpenCode and 30+ others, each running on your own subscription. A new agent comes in with one config file. Switching vendors is still changing one line.
- Fan-out. A single prompt can go to up to 5 agents at once, each in its own worktree, and at the end you assemble the merge picking the best of each diff, hunk by hunk. I use it sparingly; my default is one task per agent. But for a hard implementation decision, comparing three real approaches is worth every token.
- Design Mode. In the embedded browser, you click an element on the page and Orca sends the HTML, the computed CSS and a cropped screenshot straight into the agent's prompt. For frontend work, this kills an entire class of manual description.
- Tracker integration. Native Linear and GitHub: you can create a worktree straight from an issue. In my flow the orchestrator does that, through MCP, but the manual path exists.
- Scriptable CLI.
orca worktree create, snapshot, browser click and fill: Orca itself becomes automatable. My watchers talk to this.
On the phone, from anywhere#
Orca has a mobile companion (iOS and Android) that tracks the fleet: each agent's status, a push when one finishes or gets stuck on a question, and replies straight from the phone.
The app talks to the desktop, so the workstation needs to be on. To make this work away from home, I use Tailscaleopens in a new tab: the workstation and the phone join the same private network (WireGuard underneath), without opening a single port to the world. The phone reaches the Orca on my machine from anywhere, as if they were in the same room.
In practice: an agent asks for plan approval, the push lands on my phone, I read the plan in the supermarket line and approve it. The fleet does not stop because I left the desk.
And the honest costs, because everything has them: idle Orca takes around 400 to 800 MB of RAM, running agents in parallel multiplies token spend (3 agents, 3x), and mobile depends on the desktop being on. Tailscale solves the access, not the power bill.
The AI as P.O.#
The central piece of my setup is not an agent that codes. It is an agent that manages the ones that code: a Claude Code session inside Orca whose job is to be the P.O.
The architecture#
This is the whole system in one drawing. At the top there is me, supervising. Right below, the orchestrator: the P.O. It talks to Linear through MCP and dispatches work to worktrees, each with its own agent (Claude Code or Codex CLI). Every worktree ends in a PR, and every PR goes through review gates: subagents looking at security, data isolation, overall quality and database. The merge is a human decision, always.
Underneath, holding everything up: the repo constitution, the memory with the lessons that survive between sessions, and the watchers, sentinels that wake me up if an agent stalls.
I do not open four chats. I talk to ONE agent, the P.O., and it runs the team. The full flow: the issue is born in Linear; the orchestrator writes a self-sufficient briefing; it creates the worktree and dispatches the right agent; the agent asks, the orchestrator answers; the plan goes through approval; the implementation becomes a PR; the PR goes through the gates; the merge is mine; Linear gets updated. When a child agent has a question, the orchestrator answers first. Only product decisions come up to me. It is an org chart, except the nodes are processes.
The self-sufficient briefing#
The briefing is the most underrated artifact of the setup. The child agent never sees Linear, so the briefing carries the whole task: the issue pasted in full, the code pointers saying where to touch, the invariants with what never to do (plus the machine's quirks, like that postgres port), the required validation to prove it works, and the protocol: when in doubt, ask the orchestrator, do not assume.
The last line is sacred: STOP after opening the PR. Merge is a human decision. Every dispatch becomes a document a senior engineer could execute without asking anything. Because the agent can too. Writing a good briefing is 80% of the result.
Dispatch by specialty#
A detail that always surprises people: I do not use a single model. Frontend goes to Claude Code with a UI skill, which gives the best visual results in my tests. Backend and infra go to Codex CLI, which in my case proved more solid at server logic. Empirical criteria: each one where it does best, decided by testing, not by faith.
Since the constitution and the briefings are standardized, switching vendors means changing one line in the dispatch table. That is strategic freedom.
Supervision and watchers#
A good agent asks BEFORE assuming. A skill I use forces this: one decision at a time, interview style. A real dialogue, just anonymized:
Agent: decision 3 of 8. Should the queue exclude the requester from the approver list? (a) yes, always (b) no (c) configurable
Orchestrator: (a). A requester never approves their own request. Recording the decision in the briefing.
There was a morning of answering more than eight design decisions this way, most of them resolved by the orchestrator itself, without waking me.
And since there are several agents in parallel, I have watchers: scripts that notice when a child got stuck waiting for an answer and let me know. Even supervision gets automated.
Layered quality#
The question that always comes: what about quality? Answer: layers. Before the code, an approved plan. After the code, other agents review it: one only hunts security issues, another only data leaks, another overall quality, another database. Then comes the PR, local validation and the merge, which is still mine.
AI did not remove the review. It multiplied the reviewers.
A real day#
This is not a benchmark. It is my Monday. Four agents in parallel, one Claude and three Codex, on four fronts: an approvals UI with an open PR and green gates, NLU calibration running, a CRM integration waiting on an answer, test infra with a plan under approval. Between yesterday and today, three sprint PRs reviewed, validated and merged.
And the detail I like the most: one of the agents, still in the planning phase, found out the problem was bigger than the issue said. It became a new issue in Linear. A good agent does not just execute. It finds work.
Limits: where it breaks and when not to use it#
The most important part of the post: all of this broke on me, and recently.
The watcher gave a false positive: the agent looked stuck, it was just thinking. I sent a path with an uninterpolated variable to four agents at once. I got an urgent alert that was just a broken hook. And a confidence threshold that was too conservative made a feature impossible to trigger, and we only found out by actually testing it.
Orchestration is code too, and code has bugs. Anyone promising you an agent fleet with no supervision is selling something. The difference is what happens next: every one of those breaks became persistent memory and a new protection. The system learns.
Just as important as knowing how to use it is knowing when NOT to:
- Trivial change: the agent overhead costs more than doing it by hand. A typo I fix myself.
- Code you do not know how to review: you are the gate. If you do not understand it, you do not merge it.
- Secrets and credentials without guard-rails: no way.
- Repo without tests: an agent without a compass iterates in the dark.
- Architecture decisions: delegate the execution, never the decision.
The agent multiplies your judgment. If the judgment does not exist, it multiplies zero.
Golden rules#
If you forget everything else, take these five:
alias rule1='plan first, always a plan before code'
alias rule2='the merge is YOURS, human review is not optional'
alias rule3='versioned context, constitution + memory in the repo'
alias rule4='start with 1 agent, the fleet comes later'
alias rule5='measure before you scale'The order matters. Nobody builds a fleet on day one. First you learn to work with ONE well contextualized agent. Then you parallelize what already works. And you measure before you scale.
Start with one agent#
The path I recommend is the one I climbed myself, step by step:
- Install a harness and use it instead of the chat (Claude Code, Codex CLI).
- Write your repo's constitution: one file with rules and prohibitions.
- Turn on plan mode and never turn it off again: plan, approval, execution.
- Add your first MCP (the tracker) and your first skill.
- Real parallelism: worktrees, and then a fleet IDE like Orca.
Steps 1 to 3 already change your life on their own. Worktrees, Orca and the fleet are the bonus for whoever consolidated the base. You can start tomorrow with step 1.
A good part of this material was born in a talk I gave at LIA, the academic AI league at UFSC, in Brazil, in July 2026; the diagrams come from that deck. If something is still open, reach out on LinkedInopens in a new tab or GitHubopens in a new tab.
To go deeper:
- Orcaopens in a new tab, the official repo
- An independent Orca reviewopens in a new tab, with real-use details
- Tailscaleopens in a new tab
- Claude Codeopens in a new tab
- Model Context Protocolopens in a new tab
- git worktreeopens in a new tab
- Codex CLIopens in a new tab
- awesome-claude-code-subagentsopens in a new tab
- skills.shopens in a new tab
The fleet does not replace me. It multiplies my judgment. And the merge is still mine.