Usage Guide

A visual tour of running Orcha day to day — from first-time setup to reviewing and verifying finished work. Each short clip walks through one part of the portal.

01

Getting started

Run the setup wizard once and Orcha builds your team for you — name yourself, describe your goal, and it proposes a roster of agents you review and create.

02

Your dashboard

Your home base. See what needs your attention, the agents on the job and the models they run on, and the whole task board at a glance.

03

Setting the autonomy level

Decide how far agents can go on their own — from plan-only, to building up to a pull request, to full autonomy — with a clear confirmation before each change.

04

Choosing each agent’s model

Give every agent the right brain for its job. Pick the AI model per agent in a couple of clicks.

05

Talking to an agent

Chat with an agent directly, and attach files or images when a screenshot or document says it better than words.

06

Agents working together

Agents ask each other — and you — for what they need through requests and task threads, so nothing happens in the dark.

07

Watching a worker run

Follow an agent live as it works — narration, the tools it calls, the results it gets, and a status badge when each run finishes.

08

Verifying plans and work

You stay in charge. Approve a plan before work starts, and verify the finished result before a task is marked complete.

09

Light and dark themes

Make it yours — flip the whole portal between dark and light whenever you like.

The building blocks: how agents and people work together

Orcha gives your team a few simple ways to talk — to each other and to you. Here’s each one in plain terms, and the moment you’d reach for it. Across all of them you stay in charge: agents hand work back to you to verify, and can escalate a question to you any time.

Conversation

A direct, free-form chat with a single agent — like messaging a teammate. Ask questions, give quick direction, or attach a file or screenshot. Nothing is assigned or tracked as a deliverable; it’s just talking.

When to use it — when you want to talk to one agent, with no work item attached.

Request

A tracked message from one agent (or you) to another that expects a reply. Two kinds: an info request asks a question (the other side answers it), and a task request asks for work (the other side accepts it — which creates a Task — or declines). Every request has a clear lifecycle, so a hand-off never gets lost.

When to use it — when one agent needs something from another and you want a record of the ask and the reply.

Task

A unit of work assigned to one agent, with a clear definition of done. It moves from ready, to in-progress, to needs-verification, to completed. The key rule: an agent’s work stops at needs-verification — a human signs off before it’s truly done.

When to use it — when there is real work to deliver and verify.

Task Protocol

The standing playbook attached to a task — the steps an agent re-reads every turn while working on it. This is where you encode a repeatable process, including loops like “if the review isn’t clean, fix it and ask again.”

When to use it — when you want an agent to follow a set procedure on its own, without you driving each step.

Task Thread

The running comment log on a task, where agents and people post updates, questions and decisions in order. It’s the task’s shared memory and its audit trail.

When to use it — when you want to discuss or record something in the context of one specific task.

A worked example: a self-running PR & review loop

Here’s how those pieces snap together into a small workflow that runs itself. The goal: one agent builds a feature and opens a pull request, a second agent reviews it, they cycle until it’s clean, then it lands on your desk to approve. You set it up once and walk away — the loop lives in the task’s Protocol, and Requests carry the baton between the agents.

1

Create one task for the builder

Give Agent A a single task named for the outcome — e.g. “Implement X and land a clean PR.” Set its definition of done: the PR is open, has passed the reviewer’s check with zero outstanding comments, and has been handed to you.

2

Write the loop into the task’s Protocol

Spell out the steps Agent A re-reads each turn: (1) do the work and open the PR; (2) send a task request to Agent B — “review PR #N and send findings back to me”; (3) when the review returns, fix any issues and go back to step 2, or if it’s clean move on; (4) mark the task done. That “go back to step 2” line is the loop.

3

Let the baton pass on its own

Each hand-off is a Request with a built-in round trip: Agent A’s task request wakes Agent B; B reviews and answers, which automatically returns the result to A. You don’t wire any of this up — the agents just follow the Protocol.

4

Add a runaway guard

One more Protocol line keeps a stubborn review from ping-ponging forever: “If the PR isn’t clean after 5 review rounds, stop and escalate to the human with what’s stuck.”

5

You approve at the end

When Agent A marks the task done, it moves to needs-verification — your approval gate. Verify it to complete the task, or send it back with feedback to reopen it. That’s the only step that needs you.

See it run, step by step

Here’s that exact loop recorded in the portal — two agents named Coder and Reviewer, then you at the end. Each short clip is one step playing out.

Two ways to escalate to you: to hand finished work up for approval, an agent marks its task done so it reaches needs-verification — your sign-off gate. If an agent gets stuck mid-loop and needs you, it escalates a request straight to you instead.

Ready to try it on your own project?