Orcho in 5 minutes

Plain-language start

Your AI agent says “done” — then you find it quietly broke something that worked, or skipped the test. Orcho sits around the agent like a supervisor: it makes the agent plan first, checks the result, and refuses to call unfinished work “ready”. This page follows one task through Orcho, start to finish, in plain words.

Run quickstartWatch the run

plain words firstcommands nextreference later

one task, start to finishwhat Orcho does

You ask        "Add validation to the login endpoint"

Orcho makes the agent:
1. plan it          before touching code
2. write the code
3. review the work   a second pass looks for problems
4. fix what's wrong   here: a missing test
5. final check        is this really ready to ship?

Result
Not "the agent said done."
"Reviewed, repaired, checked — and here is the proof."

The point: Orcho does not hide the work in one long chat. It turns the task into visible steps you can trust and re-read later.

01A taskIt starts from one clear task, not a loose chat thread.02How carefulA “profile” is just how strict Orcho should be for this task.03The stepsPlan, code, review, fix, final check — in order.04The proofFiles you can open afterward instead of trusting a message.

1. You give a task

It starts with one task — the thing you want done.

Add validation to the login endpoint

In a normal agent session, that task becomes one long chat. You have to remember what was planned, what changed, whether the tests ran, and whether the final “done” is true. Orcho keeps the task inside a run — a single tracked piece of work with a beginning, checks, and an end.

2. Pick how careful to be

Before anything happens, Orcho needs to know how careful to be. That is all a profile is: not a theme, not a setting screen — just the level of strictness for this task.

Tiny fix → lightFixing a typo or a label does not need a plan and a review. A small-task profile just does it.New feature → fullAdding real functionality deserves the whole journey: plan, code, review, repair, final check.Not sure → let Orcho pickDescribe the task and Orcho suggests the right profile for you.

For this story the task is a real feature, so it uses the feature profile — the careful one.

Orcho Run  20260629_1427  profile=feature

That single line means: this work gets planned, written, reviewed, repaired if needed, and checked before it counts as ready. Want the deeper model later? Read Profile semantics.

3. The steps

With feature, Orcho runs the task through a fixed set of steps, in order:

plan  →  write code  →  review  →  fix if needed  →  final check  →  done

Each step has one job. Planning happens before code. Reviewing is separate from writing, so the work gets a real second look. The final check is its own gate, so “the code compiles” and “this is ready to ship” are not the same thing.

The shorthand you’ll see in the terminal

Orcho shows those same steps compressed into one line. It looks dense at first — here is how to read it:

⟳² (▶ plan [Claude] → · validate_plan [Codex]) → · implement [Claude]
→ ⟳² (· review_changes [Codex] → · repair_changes [Claude])
→ · final_acceptance [Codex]

⟳² this part can repeat (up to a limit)▶ the step running now· a step waiting its turn[Claude] the agent doing the work[Codex] a different agent doing the review

Two different agents on purpose: one writes, another reviews — so the work does not get to grade its own homework. See Watch the run for the full live view.

4. The agent writes the code

The “write code” step is where the AI agent actually edits your project. Orcho does not replace the agent — it still does the real work.

The difference is that the agent is now boxed inside steps:

• the task already has a profile, so the agent knows how careful to be;
• the plan came first, so it is not improvising;
• the review step that comes next knows what to check;
• the proof at the end points to real files, not vibes.

[IMPLEMENT] edited api/auth.py and tests

5. Review catches what “done” hides

This is the moment that matters. Not when the agent says “done” — when a review step decides whether the work is actually ready.

[REVIEW_CHANGES] verdict=REJECTED
  blocker  missing negative-path test
  fix      add a test for invalid input

[REPAIR_CHANGES] added the missing test

A normal chat would have ended at a confident “done”. Orcho stopped, named the exact problem, sent it back to be fixed, and kept that decision in plain view. That is the whole pitch: it catches the “looks done but isn’t” case that costs you hours.

Want the deeper version of this idea? Read False-ready delivery.

6. The final check

The last step asks one question: is this really ready to ship?

[FINAL_ACCEPTANCE] verdict=APPROVED
  ship_ready  yes

If it says no, you do not get a vague failure. You get the blocker and the next move — fix it, follow up, or pause for your decision. Either way, nothing broken slips through wearing a “done” label.

7. The proof it leaves behind

When the run ends, you are not stuck trusting a chat scrollback. Orcho leaves files behind:

output.log     the full run, as it happened
events.jsonl   the timeline of what happened, in order
plan.md        the plan it agreed to follow
review.json    what the review found
diff.patch     exactly what changed in your code

You — or a teammate, or a tool — can open these later and see what happened, why it was accepted, and what was checked. No need to reconstruct it from memory.

Read Evidence bundle for what the proof contains, or Read the result for the first thing to open after a run.

Where to go next

Run quickstartInstall Orcho, run one task, and watch it happen for real.Let your agent drive itThe lighter way in: let the AI client you already use run Orcho over MCP.Watch a live runLearn to read the terminal stream as it works.Understand profilesThe one idea worth learning early: how strict each run should be.Open the docs mapPick your next layer when you want more depth.