Skip to content
MAIB

How an AI coordinates my coding agents

My workflow with Orca, worktrees, skills, and MCPs, while review and merges stay human.

13 min read
  • orca
  • claude-code
  • workflow
  • ai
en → pt
On this page

I still build software every day, but I no longer need to type every line myself. I now spend more time defining tasks, preparing context, and reviewing what the agents did.

Claude Code and Codex CLI work in isolated copies of the repository inside Orca. A third session follows the tasks in Linear, prepares briefings, and answers many of the questions that come up. I remain responsible for product decisions, review, and the merge.

This post explains how I built the workflow, which pieces I use, and where it still fails. It is the system running on my workstation today, including the problems I found along the way. The figures are in Portuguese because they came from a talk I gave in Brazil, but the full explanation is included here.

From chat to an agent inside the repository#

My first way of coding with AI was the usual one: ask a question in chat, copy the answer into the editor, and take any error back to the chat.

the manual path between chat and editor

the manual path between chat and editor

That approach works for small tasks, but it depends on a person moving context all the time. The model only knows what was pasted into the conversation. It cannot see the rest of the repository or confirm on its own whether the code compiled and the tests passed.

A coding agent changes this because it can read files, edit the project, run commands, and use the result as feedback for the next attempt. To do that well, the model needs a prepared environment around it.

from an isolated chat to a coordinated workflow

from an isolated chat to a coordinated workflow

This is why I started paying more attention to the harness, the repository rules, and isolation between tasks. The model still matters, but the result depends heavily on the access, context, and checks it receives.

The pieces of the workflow#

There is no single tool that handles everything. My setup combines a few pieces, each with a specific job.

Harness#

the harness provides project access and closes the feedback loop

the harness provides project access and closes the feedback loop

The harness is the program that connects the model to the development environment. It can read files, run commands, edit code, and repeat the process after an error. Claude Code and Codex CLI are the two I use.

It is also what turns a conversation into a continuous execution. The agent writes, runs a test, reads the failure, fixes it, and tries again without waiting for me to copy every result between tools.

MCP#

each integration needs to justify its cost

each integration needs to justify its cost

MCP, or Model Context Protocol, is the standard I use to connect tools and data sources to an agent. My orchestrator, for example, reads a Linear issue without me copying its contents into the prompt.

Every integration takes up context and may use a fair amount of memory. One headless browser MCP launched a Chrome process of roughly 470 MB, so I removed browser MCPs from the default configuration. I only keep connections that are part of the active workflow.

Skills#

reusable procedures loaded when needed

reusable procedures loaded when needed

A skill is a reusable procedure. Instead of explaining the same checklist in every task, I keep the instructions in a file that the agent loads when needed.

I use skills for interface reviews, requirements interviews, and integration spec scaffolding. This keeps the process consistent without holding every rule in the context window all the time.

Git worktrees#

one isolated working copy for each task

one isolated working copy for each task

Git worktree creates multiple working copies connected to the same repository. Each task gets its own worktree, branch, and terminal.

This isolation lets me keep four agents working at once without one changing another agent's files. Conflicts may still appear during the merge, but not while each task is being implemented.

Plan mode and permissions#

No agent starts implementing before presenting a plan. I or the orchestrator review the decisions that would change the result, then approve the execution.

I also restrict destructive commands and high-impact files. This control adds a few minutes at the beginning of a task, but it avoids discovering a wrong interpretation after a full diff is already written.

Versioned repository rules#

the same rules for every agent

the same rules for every agent

The rules live in the repository itself. AGENTS.md is the canonical file, with a mirror in CLAUDE.md. It records architecture decisions, prohibited actions, invariants, and files that require confirmation before an edit.

I also keep environment details that frequently cause mistakes, such as the port used by the local Postgres instance. When a new session starts, this information is already available and does not depend on the memory of an earlier conversation.

Using Orca day to day#

I keep all of these pieces together in Orcaopens in a new tab. It is an Agent Development Environment, an IDE designed to track several agents and worktrees in parallel. The project is open source under the MIT license, maintained by stablyai, and runs on macOS, Windows, and Linux. It also has a headless mode for a VPS over SSH.

Each worktree gets its own terminal, splits, persistent scrollback, an embedded Chromium browser, and a diff view with line comments. On the main screen, every task appears as a card with its current status. I can review, commit, and prepare the merge without switching applications.

These are the features I use most:

  • Different CLI agents. Orca supports Claude Code, Codex, Cursor, OpenCode, and more than 30 other options. Each one uses its own subscription and is added through configuration.
  • Fan-out. One prompt can be sent to up to five agents, each in its own worktree. Their diffs can then be compared, with individual hunks selected from each solution. I only use this when I want to compare approaches for a difficult decision.
  • Design Mode. In the embedded browser, I select an element and send its HTML, computed CSS, and a screenshot crop to the agent. This reduces the manual description needed for frontend work.
  • Tracker integration. Linear and GitHub can create worktrees from issues. My orchestrator uses the Linear MCP, but the manual path is also available.
  • Scriptable CLI. Orca exposes commands for creating worktrees and operating the browser. My supervision scripts use this interface.

Following the work from a phone#

Orca's mobile companion, available for iOS and Android, shows the status of each agent and sends notifications when a task finishes or waits for an answer. I can also reply from the phone.

The app depends on the desktop being on. To reach my workstation away from home, I use Tailscaleopens in a new tab. The computer and phone join the same private network, built on WireGuard, without requiring a public port.

In practice, I can review a plan or answer a question away from my desk. There are costs: idle Orca uses roughly 400 to 800 MB of RAM, three agents in parallel can use close to three times as many tokens, and the mobile app stops working when the desktop is off.

The AI as P.O.#

The central part of my setup is a Claude Code session that coordinates the agents doing the implementation. I treat it as an operational P.O.: it organizes issues, prepares context, and follows the execution. Product decisions stay with me.

Architecture#

the full path from issue to merge

the full path from issue to merge

The orchestrator talks to Linear through MCP and sends each task to a worktree with Claude Code or Codex CLI. When the implementation is ready, the agent opens a PR. Subagents review security, data isolation, overall quality, and database work before my final validation.

The flow looks like this:

  1. An issue enters Linear.
  2. The orchestrator writes a briefing and creates the worktree.
  3. The agent prepares a plan, asks questions when needed, and implements after approval.
  4. The change becomes a PR and goes through the review gates.
  5. I review the result and decide whether to merge it.
  6. The orchestrator updates Linear and closes the run.

When a child agent has an operational question, the orchestrator tries to answer it first. Only product decisions or choices that change scope come to me.

The briefing#

the context needed to execute the task

the context needed to execute the task

The child agent does not access Linear directly. The briefing therefore carries the full issue, the files that deserve attention, the rules that cannot be broken, and the commands required to validate the result. It also includes environment details, such as the Postgres port.

The protocol tells the agent to ask the orchestrator when information is missing. The final instruction is to stop after opening the PR. The merge only happens after my review.

Choosing the agent#

the agent changes with the type of task

the agent changes with the type of task

I do not use the same agent for everything. In my tests, Claude Code with a UI skill worked better for frontend tasks. For backend and infrastructure, I had more consistent results with Codex CLI.

The briefings and project rules stay the same regardless of the provider. The choice lives in a dispatch table and can change as I collect results from future projects.

Questions and watchers#

One skill requires the agent to present one decision at a time when a requirement is incomplete. This is a real dialogue with the project details removed:

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.

On one morning, more than eight design decisions came up in this format. The orchestrator resolved most of them from existing rules and called me only for the ones that affected the product.

I also use scripts that detect when an agent is waiting for an answer and notify me. These watchers do not resolve the question, but they stop a run from sitting idle for hours without me noticing.

Review in layers#

each stage has a different check

each stage has a different check

Review starts before the code, with the plan. After implementation, subagents split the analysis by topic: security, data leaks, overall quality, and database work. Then come the PR, the local tests, and my own reading of the diff.

Adding more agents does not remove human review. It increases the number of checks before the work reaches the merge.

A day of work#

four tasks tracked on the same screen

four tasks tracked on the same screen

On one Monday, I kept four tasks moving in parallel: an approvals interface with an open PR and green gates, an NLU calibration in progress, a CRM integration waiting for an answer, and test infrastructure with a plan under review. Between the day before and that moment, three sprint PRs had been reviewed, validated, and merged.

During planning, one of the agents noticed that the problem was larger than the issue described. Instead of expanding the scope on its own, it recorded the gap and the work became a new Linear issue.

Where the workflow fails#

This system has produced several problems. A watcher marked an agent as stuck when it was still thinking. In another run, I sent four agents a path containing a variable that had not been interpolated. I also received an urgent alert caused only by a broken hook. In one feature, an overly conservative confidence threshold prevented every trigger, and the error only appeared during manual testing.

Orchestration code has the same kinds of bugs as any other software. After each case, I recorded the cause and added a safeguard or a clearer instruction. The workflow still requires supervision.

There are also tasks where I do not use agents:

  • Trivial changes. For a typo, the setup costs more than the edit.
  • Code I cannot review. If I cannot evaluate the result, I do not merge it.
  • Unprotected secrets. Credentials do not belong in an environment without clearly defined permissions.
  • A repository without tests. Without automated feedback, the agent has little evidence for correcting its own mistakes.
  • Architecture decisions. I can delegate research and implementation, but the decision remains human.

Five rules I follow#

I summarized my daily use in these aliases:

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'

I started with one agent and only added parallel work after the basic workflow became predictable. Measuring time, cost, and rework helps me decide whether a new layer is actually worth it.

How to start#

To build something similar, I would follow this order:

  1. Install a harness such as Claude Code or Codex CLI and use it on a real task.
  2. Add a repository file with rules, decisions, and prohibited actions.
  3. Require a plan and approval before implementation.
  4. Add one MCP with a clear use and one skill for a procedure you repeat often.
  5. Once one agent works reliably, try worktrees and an IDE such as Orca.

The first three steps already remove much of the manual transport between chat and editor. Parallelism can come later, once there are enough tests and review criteria to follow more than one task.

Much of this material came from a talk I gave at LIA, UFSC's academic AI league, in July 2026. The diagrams came from the same deck. If you want to discuss any detail, you can find me on LinkedInopens in a new tab and GitHubopens in a new tab.

References:

This workflow lets me follow several projects without handing the final decision to the agents. They implement and help with review; I remain responsible for the product and the merge.

Share