Ourocode

Ourocode is a terminal workbench for planning real work, delegating it to guided agents, and verifying the result without leaving your shell. It gives you a fast keyboard UI, structured interviews with selectable answers, active-work views, connected-tool checks, and JSON evidence for automation.

Product site draft: docs/site

The current release is optimized for local macOS development and guided workflow testing.

What It Does

• Starts structured work with ooo pm <goal> and keeps the first useful choice visible quickly.
• Shows delegated work with task, state, current output, and actions.
• Turns interview checkpoints into focused pickers with number keys, custom answers, pause, and cancel.
• Exposes /agents, /sessions, /mcps, /config, /sandbox, and /verify as product surfaces, not only debug logs.
• Runs headless with --prompt and --format json for scripts, CI, and remote operators.
• Supports command discovery with /, ooo, @file, and prompt overlays.
• Writes current visual verification captures to docs/assets/visual/ when /verify or --verify runs, including first start, PM picker, agents, cancel, verify, theme, and README media.

Quick Start

Install the latest prerelease build:

curl -fsSL https://raw.githubusercontent.com/Q00/ourocode/release/bootstrap/install.sh | bash

Then run:

ourocode

Optional model backends:

• Claude CLI
• Codex CLI
• Gemini CLI
• ChatGPT/Codex login

For a local source checkout:

./install.sh
ourocode

Detect available model backends:

./ourocode --detect

Run product verification or drive Ourocode from automation:

./ourocode --verify --format json --project-dir .
./ourocode --prompt "/agents" --format json --project-dir .
./ourocode --prompt "ooo pm design plugin onboarding" --format json --project-dir .

See Headless CLI Automation for JSON evidence, active-work views, connected-tool readiness, and safety posture.

Inside the TUI:

/               choose ooo pm, ooo interview, or ooo auto
/help           show the guided starts and command reference
/commands       list every available command
/model          choose a model backend
/login          sign in for ChatGPT/Codex OAuth
/agents         inspect active work and answers waiting on you
/mcp            show connected tools and readiness
/mcps           show connected tools and readiness
/config         show local setup status
/theme          switch light or dark mode
/verify         run product checks
/sandbox        inspect safety mode, roots, network posture, and actions
ooo pm          shape product requirements with answer choices
ooo interview   start a structured interview flow
ooo auto        interview, draft a plan, then execute after approval
@               mention project files
Ctrl-G          show active key help

Install Locally

Install from GitHub without cloning:

curl -fsSL https://raw.githubusercontent.com/Q00/ourocode/release/bootstrap/install.sh | bash
ourocode

install.sh downloads the matching GitHub Release tarball, installs ourocode into ~/.local/ourocode/<version>, and writes a launcher at ~/.local/bin/ourocode. The launcher sets OUROCODE_TTY so the installed escript can find the bundled native tty helper.

When run from a source checkout, the same installer uses bundled release binaries if present, or builds from source when needed. Set OUROCODE_BUILD_FROM_SOURCE=1 to force a local build.

Set OUROCODE_SKIP_OUROBOROS=1 to skip the best-effort Ouroboros install step.

Package A Release

Build a local release tarball:

./scripts/package.sh

The release contains:

ourocode
bin/ourocode_tty
install.sh
README.md

Generated artifacts:

dist/ourocode-v0.1.12-darwin-arm64.tar.gz
dist/ourocode-v0.1.12-darwin-arm64.tar.gz.sha256

Install from an unpacked release:

tar -xzf dist/ourocode-v0.1.12-darwin-arm64.tar.gz
cd ourocode-v0.1.12-darwin-arm64
./install.sh
ourocode

Homebrew is planned but not yet the supported install path:

brew tap Q00/ourocode
brew install ourocode

Longer term, Ourocode should move toward a single self-contained binary or app bundle so users do not need to install Elixir/Rust just to run it.

Architecture

This section is for contributors and plugin authors. Day-to-day users should start with ourocode, ooo pm <goal>, /agents, and --verify.

Terminal TUI
  -> command registry and prompt overlays
  -> runtime dispatcher
  -> MCP transport layer
  -> Ouroboros / model backends
  -> journaled event stream
  -> dashboard projections

Key areas:

• lib/ourocode/terminal/ - raw terminal UI, key decoding, palette, prompt history, screen diffing
• lib/ourocode/runtime/ - workflow orchestration, dispatch, focus state, stream supervision
• lib/ourocode/mcp/ - stdio, SSE, and streamable HTTP normalization
• lib/ourocode/wonder_tool/ - decision request parsing and answer capture
• lib/ourocode/dashboard/ - data-only pane projections
• rust/ourocode_ipc/ - native tty helper

Development

Run tests:

mix test

Run focused terminal tests:

mix test test/ourocode/terminal

Build everything:

./build.sh

Status

This is an early release branch for getting real users onto the terminal workflow. The current priority is packaging, installer polish, and feedback from actual guided interview sessions.