Cooperations

Local-first research toolkit for orchestrating specialized AI agents in software workflows.

Cooperations explores a role-based workflow built around explicit handoffs between architect, implementer, reviewer, and navigator agents. The implemented runtime is intentionally narrow and truthful: it is Codex CLI-first, Linux/bash-oriented, and stores task history, handoffs, generated artifacts, sandbox mode, and activated task capabilities on disk.

Why Inspectable Workflow

Cooperations is not trying to hide orchestration behind a single opaque agent run. The core idea is that software work is easier to trust when the execution contract stays visible:

• each task declares its sandbox up front
• capabilities are explicit and task-scoped
• handoffs and artifacts are stored locally
• the TUI shows live workflow state and ends in a completion/error view
• when an interactive TTY is unavailable, coop tui falls back to plain workflow output instead of crashing

This keeps the runtime honest about what happened, what was allowed, and where the result ended up.

Status

See docs/STATUS.md for the source-of-truth status matrix. In short:

• Implemented core: Codex CLI orchestration, heuristic routing, per-task sandbox contract, optional task-scoped capabilities, local task/handoff storage
• Secondary interfaces: Bubble Tea TUI and an opt-in Gio GUI build
• Experimental/reference: RVR, meta-cognitive reasoning notes, benchmark and planning documents

Quick Start

Requirements:

• Linux with bash
• Go 1.24+
• Installed codex CLI
• Optional local overrides from .env.example

The repository does not use the OpenAI API directly. Authenticate codex through its own CLI flow before running real tasks.

Build:

cp .env.example .env
go build -o coop ./cmd/coop

Inspect routing without running model tooling:

./coop run --dry-run "implement a health check endpoint"
./coop history

Run a real task with an explicit sandbox:

./coop run --sandbox workspace-write "implement a health check endpoint"
./coop run --task-file examples/feature-request.json
./coop run --task-file examples/feature-request.yaml --capability skill:playwright

Optional interfaces:

./coop tui --sandbox workspace-write "implement a health check endpoint"
go build -tags gio -o coop ./cmd/coop
./coop gui --demo "review the workflow"

coop tui is the first-class interactive path when a real TTY is available. In non-interactive environments it automatically falls back to plain workflow output and still runs the task instead of failing with a terminal panic.

What Works Now

• Keyword/heuristic routing into specialized roles
• Task-scoped sandbox enforcement for real runs
• Optional task-scoped capability references:
  • plugin:<name>
  • plugin_skill:<plugin>:<skill>
  • skill:<name>
• Local task persistence under .cooperations/
• Generated artifacts and task summaries under generated/
• Shared workflow event model used by the orchestrator, TUI, and GUI
• TUI completion/error views with summary-first result rendering
• Plain CLI fallback for coop tui when no controlling TTY is available

Runtime Contract

• Real workflow execution requires an explicit sandbox on every task.
• Supported sandbox modes are read-only, workspace-write, and danger-full-access.
• Capability references are optional; when omitted, the task runs as a regular Codex model task.
• If a capability is explicitly requested but not available locally, the task fails before execution.
• run --dry-run, status, and history do not require Codex CLI initialization.
• tui uses the same task contract as run; when interactive terminal startup fails, it falls back to plain workflow output with progress, summary, and artifact paths.

Example Transcript

The intended proof shape is a real read-only repository task, not a polished screenshot. This is a real non-interactive tui fallback run from this repository:

$ ./coop tui --sandbox read-only "Read this repository and summarize what it does in one short paragraph. Do not modify any files."
[fallback] interactive TUI unavailable: interactive TUI requires a controlling TTY: stdin and stdout must be interactive terminals
[fallback] continuing with plain workflow output
[workflow] plain fallback mode
Task: Read this repository and summarize what it does in one short paragraph. Do not modify any files.
Sandbox: read-only
Capabilities: none

-> [  0%] Starting: Running task: Read this repository and summarize what it does in one short paragraph. Do not modify any files.
-> Task completed successfully!

[COMPLETE] Read this repository and summarize what it does in one short paragraph. Do not modify any files.
Task ID: 1776299534231852928
Status: completed
Sandbox: read-only
Capabilities: none
Summary: generated/1776299534231852928/README.md

The exact roles, progress lines, and artifacts vary by task, but the contract stays the same: progress is visible, the result is inspectable, and the generated summary path is printed at the end.

Stability Tiers

Implemented Core

• coop run, coop status, coop history
• Codex-only role/profile runtime wiring
• Per-task sandbox and capability contract
• Local handoff and artifact persistence
• TUI stream/event model

Secondary Interfaces

• coop tui for interactive workflow execution
• coop gui as an exploratory interface for demo and playback flows when built with -tags gio

Experimental / Reference

• RVR and confidence-scoring documents in docs/
• Long-form planning and design documents
• Historical evaluation notes in docs/WORK_JOURNAL.md

Project Layout

• cmd/coop/: CLI entrypoint
• internal/orchestrator/: workflow engine, task parsing, config, hooks, and routing
• internal/agents/: role-specific agent wrappers
• internal/adapters/: Codex CLI adapter and legacy/reference adapters
• internal/capabilities/: local capability resolution for plugins and skills
• internal/context/: local task, handoff, and artifact storage
• internal/tui/: Bubble Tea interface and shared workflow stream types
• internal/gui/: Gio-based exploratory interface
• docs/: status, usage, plans, and research/reference material

Documentation

• docs/STATUS.md: current implemented vs experimental behavior
• docs/USAGE.md: command usage and runtime expectations
• docs/STRATEGY.md: research/strategy direction
• docs/WORK_JOURNAL.md: historical evaluation notes

Security

See SECURITY.md.

Contributing

See CONTRIBUTING.md.

License

GNU Affero General Public License v3.0. See LICENSE.