orqa
Description: Orqa helps local agents run as a working group with separate identities, local state, mail, tasks, wake scans, and inspectable runs.

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