orqa.sh

Run local agents as a working group.

Give this prompt to desktop Codex or cloud Codex to install Orqa, create a demo group, and see how agents can hand work to each other.

Give This To Codex

You are helping me install and try Orqa, a local CLI coordinator for groups of local agent runtimes.

Goal:
Install orqa, create a small demo group with two agents, and show me how to use mail, tasks, wake planning, and a Codex-backed agent run.

Instructions:
1. Check whether Rust/Cargo, Homebrew, curl, and ~/.local/bin are available.
2. Install orqa using the safest available method:
   - Prefer: cargo install orqa
   - Alternative: brew install ianzepp/tap/orqa
   - Alternative: curl -fsSL https://raw.githubusercontent.com/ianzepp/orqa/main/install.sh | sh
3. Ensure the installed orqa binary is on PATH.
4. Run: orqa doctor
5. Create a temporary demo home, for example /tmp/orqa-demo.
6. Run:
   orqa --home /tmp/orqa-demo pod create demo
   orqa --home /tmp/orqa-demo fin create demo planner
   orqa --home /tmp/orqa-demo fin create demo builder
7. Send a message and task from planner to builder.
8. Show:
   orqa --home /tmp/orqa-demo plan demo
   orqa --home /tmp/orqa-demo pod status demo
   orqa --home /tmp/orqa-demo fin status demo builder
9. Explain what files were created under /tmp/orqa-demo.
10. Do not run destructive cleanup unless I ask.

Manual Install

Install it yourself.

Shell Installer

curl -fsSL https://raw.githubusercontent.com/ianzepp/orqa/main/install.sh | sh

Homebrew

brew install ianzepp/tap/orqa

Cargo

cargo install orqa

Why Orqa Exists

Agents get more useful when they can coordinate.

Separate Identities

Run a planner, builder, reviewer, or researcher without forcing every agent through the same runtime home and global state.

Local Handoffs

Agents can send pod-local mail and tasks, leaving durable work items on disk instead of relying on a fragile chat transcript.

Wake Signals

Orqa can scan for unread mail and open tasks, then launch the agents that have work waiting.

Inspectable Runs

Run status, logs, and command records live under the agent home, so the coordination layer stays visible and debuggable.

What It Does

A local filesystem shape for agent groups.

Orqa does not try to be a cloud orchestration platform. It creates groups, agent homes, inboxes, task queues, config files, locks, and run records, then shells out to the backend you already use.

The project terms are simple: a group is a pod, and an agent identity inside that group is a fin.

ORQA_HOME/
  pods/
    demo/
      pod.toml
      fins/
        planner/
          fin.toml
          .codex/
          mail/
          tasks/
        builder/
          fin.toml
          .codex/
          mail/
          tasks/

First Group

Create two agents and send work between them.

Quick Start

orqa pod create demo
orqa fin create demo planner
orqa fin create demo builder

orqa mail send \
  --from planner@demo.orqa \
  --to builder@demo.orqa \
  --subject hello \
  "wake up"

orqa task send \
  --from planner@demo.orqa \
  --to builder@demo.orqa \
  --title first-task \
  "inspect the project and report back"

orqa plan demo
orqa loop --dry-run demo