tunaFlow is a desktop client that orchestrates CLI agents like Claude, Codex, and Gemini in a single app. It hasn't been released publicly yet and is currently being developed as a personal test project.

This series shares the technical considerations and design decisions made along the way. I hope it serves as even a 0.1% reference for those developing in a similar direction. If you disagree, you're all absolutely right. 😁

This is the first installment of the series (10+ parts total), and it's about "why an orchestration layer is necessary."

---

## Isn't Claude Code alone enough?

Honestly, a single agent can do a lot. Open a project in Claude Code, say "build this for me," and it does a pretty good job. The same goes for Codex and Gemini CLI.

But once a project gets a bit larger, situations like this arise.

Me: "Refactor the authentication middleware"
Claude: (immediately starts writing code)

Me: "Wait, let's start with the design"
Claude: "Sure, here's the design I propose..." (after already modifying 3 files)

Me: "Can you also do a review?"
Claude: (reviews its own code) "Looks well written ✅"

Reviewing your own code doesn't work well even for humans. The same applies to agents. Because their own context and judgment are already embedded, an objective review is difficult.

This isn't a problem of the agent's capability — it's a problem of absent process. There's no structure that applies a basic development process — design → implementation → review → revision — to agents.

This awareness of the problem was greatly inspired by a blog post by Stavros Korokithakis. Watching the workflow he naturally developed while working on a project with Claude Code — first creating a Plan (opus), implementing after approval (sonnet), and reviewing the results (codex) — led me to think "shouldn't tooling support this?" That thought became the starting point for tunaFlow's workflow pipeline.

---

## What I built: an orchestration layer

tunaFlow is not about building agents from scratch, but about coordinating existing agents (Claude Code, Codex, Gemini CLI, etc.) within a process — a layer.

Typical usage:
User ↔ Claude Code (1:1 conversation)

tunaFlow:
  User ↔ tunaFlow ↔ Claude Code Opus (Architect role)
                   ↔ Claude Code Sonnet (Developer role)
                   ↔ Codex 5.4 (Reviewer role)
                   ↔ Gemini (RT discussion participant or blind judge)

The key is not improving the agents themselves, but creating the process in which agents work.

'### Why I don't build agents directly

tunaFlow does not call LLM APIs directly. It calls Claude Code CLI, Codex CLI, and Gemini CLI as subprocesses.

// Actual code (claude.rs)
let mut cmd = Command::new("claude");

cmd.arg("-p")
    .arg(&input.prompt)
    .arg("--output-format").arg("stream-json")
    .arg("--model").arg(model);

This allows full use of each CLI's built-in capabilities (file editing, terminal execution, MCP integration, etc.). If you call the API directly via SDK, you only get chat — you'd have to implement everything yourself: editing files, running tests, and so on.

There are trade-offs. The CLI subprocess approach means you can't look inside the agent. It's hard to know which tool was called or what it was thinking in between (you can see a little). In exchange, you get the full feature set of each CLI for free.

---

## What the structure looks like

The overall architecture of tunaFlow is as follows.

┌─ Desktop App (Tauri 2) ──────────────────────────────┐
│                                                      │
│  React Frontend ←──Tauri IPC──→ Rust Backend         │
│  ├── Chat (main conversation)   ├── Agent Adapters   │
│  ├── Workflow (Plan/Review)     │    ├── claude.rs   │
│  ├── Branch (conversation fork) │    ├── codex.rs    │
│  ├── RT (agent discussion)      │    ├── gemini.rs   │
│  ├── Artifacts (outputs)        │    ├── openai_compat│
│  └── Trace (execution tracking) │    └── ...         │
│                                 ├── ContextPack      │
│                                 ├── SQLite (WAL)     │
│                                 └── rawq, CRG        │
└──────────────────────────────────────────────────────┘
        ↓ subprocess
    ┌─────────┬──────────┬──────────┐
    │ claude  │  codex   │  gemini  │  ← each CLI agent
    └─────────┴──────────┴──────────┘

It's a desktop app built with React + Rust on top of Tauri 2. Currently it's 25,894 lines of Rust, 24,419 lines of TypeScript, and 406 tests (230 Rust + 176 Frontend).

### 5 core features

Here's a brief introduction to tunaFlow's killer features. Each will be covered in detail in later installments of this series.

1. Workflow Pipeline (→ detailed in Part 2)

Chat → Plan promotion → User approval → Developer execution → Review RT → Done
          ↑ Human                                 ↑ Human

The Architect creates a Plan, and once the user approves it, the Developer implements it, and the Reviewer validates it. What's important here is that the points where humans approve are clearly defined. This is not a structure where agents do everything on their own. (Letting them do everything would be a disaster 😇)

2. Branch (conversation forking) (→ detailed in Part 3)

Branch off mid-conversation to experiment independently, and merge back into the main conversation when the results look good. It applies a concept similar to git branches to conversations.

3. Roundtable (agent discussion) (→ detailed in Part 4)

Multiple agents discuss the same topic. Claude, Codex, and Gemini each share their opinions, and the user makes the final call. Consensus is not reached by agents — it's reached by humans.

4. ContextPack (context assembly) (→ see [previously published post])

For each request, the necessary information (project info, plans, code search results, long-term memory, etc.) is assembled and passed to the agent. All 4 engines receive context of the same quality.

5. Quality assurance system (→ detailed in Part 9)

If an agent repeatedly makes the same mistake, it's automatically detected and escalated. After 5 failed reviews, it tells the human: "I think we may need to revisit the design from scratch."

---

## "Human with Agent" — humans decide, agents execute

tunaFlow's design philosophy can be summed up in one sentence.

> Humans decide the direction, and agents execute those decisions under optimal conditions.

It's not "the agent takes care of everything." Agents are good at execution, but deciding what to do is still something humans do better. Especially in these areas:

- Architecture decisions: An agent's training data contains a mix of good and bad patterns

- Deciding what NOT to do: Agents are not good at saying "No." If you ask, they'll almost always do it

- Judgment in the full context: Agents only see the context of the current conversation. They don't know the business context, team situation, timeline, etc.

That's why every critical point in tunaFlow has a gate where humans intervene.

Plan approval:      "Should we go in this direction?" → User approves/rejects/requests changes
Review judgment:    "Here are the review results" → User gives final confirmation
RT round judgment:  "Here are the discussion results" → User decides to wrap up/continue/end
Rework decision:    "Failed 3 times" → User decides whether to change direction

This is the decisive difference from "agents automatically doing everything." It's slightly slower, but it prevents running off in the wrong direction. (Though if human intelligence goes in the wrong direction, there's nothing to be done.)

---

## Engine architecture: works with one, works with many

tunaFlow can be configured with a minimum of 1 engine (agent) up to a maximum of 4–5.

What's important is that the entire workflow runs with just the Claude $20 Pro plan. Even running Architect/Developer/Reviewer with the same Claude Sonnet model works, because the ContextPack and Persona separate the roles.

Architect: claude --model claude-sonnet-4-6 + Architect Persona
Developer: claude --model claude-sonnet-4-6 + Developer Persona
Reviewer:  claude --model claude-sonnet-4-6 + Reviewer Persona
→ Same model, but different role-specific prompts lead to different behavior

Of course, separating engines is better. Having Claude design and Codex implement lets each play to its strengths, and it also distributes costs. But lowering the barrier to entry is also important.

---

## What I've learned so far

A few interim conclusions from building tunaFlow.

### 1. Context quality matters more than model quality

> "A lot of apparent 'model quality' is really context quality." — Sebastian Raschka

Even with the same model and the same question, results vary significantly depending on what context is passed along. With a well-assembled ContextPack, Sonnet can outperform Opus given a careless prompt. This isn't an exaggeration — it's something I've experienced firsthand multiple times.

### 2. Automation and autonomy are different

Automating a workflow is different from giving agents autonomy. tunaFlow automates the process while keeping decisions with humans. Plan approval, review judgment, rework decisions — humans intervene at these three points.

At first I thought "wouldn't full automation be better?" but problems surfaced quickly in real use. When an agent charges off in the wrong direction, the cost of backtracking is far greater than the cost of having a human check in from the start.

### 3. Agents need to be given a process

It's not that Claude Code can't do the job. Claude Code excels at tool execution. What's missing is a process. A structure that applies a basic development flow — design → approval → implementation → review → revision — to agents.

Giving agents a better process changes outcomes far more than giving them a better model.

---

## Limitations

Honestly, there are still many limitations.

- Constraints of the CLI subprocess approach: You can't observe the agent's internal tool calls. You can only infer what it's doing from stdout/stderr

- Token costs: Actively using multi-agents drives up costs quickly. Three agents debating for two rounds consumes ~30K tokens at a time

- Process overhead: Going through Plan → Approve → Dev → Review for a simple change is excessive. Flexibility to skip steps depending on the situation is needed

- Limits of RT consensus: Even having agents debate each other doesn't produce genuine "consensus." A human still has to make the final call

These limitations will each be addressed in later installments — how they're being handled (or not yet handled).

---

## Next direction: meta-agent

Currently in tunaFlow, it's the user who manages the process. Deciding "what to do next," "whether to rework or change direction," "which engine is appropriate" — all of this is judged by a human.

Going forward, I plan to introduce a meta-agent that helps manage the process itself. But there's an important distinction to make here. The meta-agent is not a superior to the Architect.

- The Architect designs "how to build it" (technical decomposition)

- The meta-agent proposes "what should be done right now" (process judgment)

Here's the difference, for example.

Meta-agent: "The Rework rate for auth-related Plans is 40%.
             How about revisiting the design?"
             → Project status analysis + priority suggestion
Architect:   "I'll migrate the authentication middleware to OAuth2 PKCE.
             I'll break it into 3 subtasks."
             → Technical design + decomposition

The meta-agent can suggest "revisit the design," but actually modifying the Plan is the Architect's job, and approving that modification is the human's job. Suggestions only. Decisions belong to humans. tunaFlow's "Human with Agent" principle applies equally to the meta-agent.

A detailed discussion of this hierarchy will be covered in the latter part of the series.

---

## Preview of next installment

Part 2: "Plan → Dev → Review" — Building the Workflow Pipeline

Covers the design decisions made in the process of separating agent roles into Architect/Developer/Reviewer, adding approval gates, and building the Rework loop. The core question: "where did we place the points of human intervention?"

---

## Series list

1. Give agents a process — What I learned building an AOC (this post)

2. Plan → Dev → Review — Building the workflow pipeline

3. Branching conversations — Branch design and usage

4. Making agents debate each other — Roundtable design and limitations

5. When conversations get long — Implementing agent long-term memory

6. Running a workflow on Claude $20 — Engine architecture

7. Communicating code structure to agents — rawq + code-review-graph

8. Only what's needed out of 246 skills — Implementing automatic skill application

9. When an agent keeps repeating the same mistake — Quality assurance design

10. Running a full cycle with tunaFlow — Workflow real-world test retrospective

+ [Previously published] ContextPack — Context design for a multi-agent orchestrator

---

## References

- Stavros Korokithakis — The workflow naturally formed while running a project with Claude Code (Plan → approval → implementation → review) became the foundational inspiration for tunaFlow's workflow pipeline.

https://www.stavros.io/posts/building-with-claude-code/

- Sebastian Raschka — "Components of a Coding Agent" (2025): Analysis of 6 core components of a coding agent. Source of the "model quality = context quality" quote.

https://magazine.sebastianraschka.com/p/components-of-a-coding-agent

- Addy Osmani — "Orchestrating Coding Agents" (2025): Comprehensive coverage of multi-agent orchestration patterns, scaling, and quality gates.

https://addyosmani.com/blog/code-agent-orchestra/

- tunaFlow internal documents

- CLAUDE.md — Project handoff document (currently session 22, DB v30)

- docs/ideas/techPostSeriesIdea.md — Series planning document