double-o 0.4.4

  ██████   ██████ 
 ███▒▒███ ███▒▒███
▒███ ▒███▒███ ▒███
▒███ ▒███▒███ ▒███
▒▒██████ ▒▒██████ 
 ▒▒▒▒▒▒   ▒▒▒▒▒▒ 

"Double-o, agent's best friend."

Or: how I learned to stop worrying and love my context-efficient command runner for AI coding agents.

Why oo?

AI coding agents waste context tokens on verbose command output. A single cargo build can produce thousands of lines that the agent must process but rarely needs in full.

oo solves this transparently:

• Commands run normally — oo wraps them, not replaces them
• Output is classified and compressed using patterns
• Agents get the signal (pass/fail, errors, summaries) without the noise
• No agent modification required — just prefix commands with oo

Unlike manual truncation (head/tail), oo understands command semantics. Unlike agent-native output limits, oo preserves the information the agent actually needs.

The Problem

AI agents see everything you print. A cargo test run producing 8 KB of output costs the agent hundreds of tokens just to learn "tests passed." Multiply that across a session and the context window fills with noise, not signal. oo runs commands for you and collapses their output to what the agent actually needs.

Output Tiers

Without oo: Your agent receives the full output.

$ cargo test
   Compiling myapp v0.1.0 (/path/to/myapp)
    Finished test [unoptimized + debuginfo] target(s) in 0.52s
     Running unittests src/lib.rs (target/debug/deps/myapp)

running 47 tests
test auth::tests::login_success ... ok
test auth::tests::login_invalid_password ... ok
test db::tests::connection_pool ... ok
... 44 more tests ...
test result: ok. 47 passed; 0 failed; finished in 2.1s

With oo: Your agent gets the signal.

$ oo cargo test
✓ cargo test (47 passed, 2.1s)

Large output with a known success pattern collapses to a single summary line.

When things fail: Actionable errors, no noise.

$ oo pytest tests/
✗ pytest

FAILED tests/test_api.py::test_login - AssertionError: expected 200, got 401
FAILED tests/test_api.py::test_create_user - ValueError: email already exists
=== 2 failed, 45 passed in 1.8s ===

Failure output is filtered to the actionable tail.

Large unrecognised output: Indexed for retrieval.

$ oo gh issue list
● gh (indexed 47.2 KiB → use `oo recall` to query)

Query indexed output with oo recall "<terms>". Small outputs pass through unchanged. Output handling depends on command category: content commands like git show and git diff always pass through regardless of size, while data commands like git log and ls are indexed when large. See the patterns guide for details.

Installation

Pre-built binaries (recommended)

Download from GitHub Releases:

# macOS (Apple Silicon)
curl -LO https://github.com/randomm/oo/releases/latest/download/double-o-aarch64-apple-darwin.tar.xz
tar xf double-o-aarch64-apple-darwin.tar.xz
sudo mv double-o-aarch64-apple-darwin/oo /usr/local/bin/

# Linux (x86_64)
curl -LO https://github.com/randomm/oo/releases/latest/download/double-o-x86_64-unknown-linux-gnu.tar.xz
tar xf double-o-x86_64-unknown-linux-gnu.tar.xz
sudo mv double-o-x86_64-unknown-linux-gnu/oo /usr/local/bin/

# Linux (ARM64)
curl -LO https://github.com/randomm/oo/releases/latest/download/double-o-aarch64-unknown-linux-gnu.tar.xz
tar xf double-o-aarch64-unknown-linux-gnu.tar.xz
sudo mv double-o-aarch64-unknown-linux-gnu/oo /usr/local/bin/

From crates.io

cargo install double-o

From source

git clone https://github.com/randomm/oo.git
cd oo
cargo build --release
cp target/release/oo /usr/local/bin/

Commands

Note: oo help sources from cheat.sh which covers common Unix tools. For modern CLIs not yet in cheat.sh (e.g., gh, kamal), use oo learn <cmd> to teach oo the command's output patterns.

Agent Integration

Add this to your system prompt or CLAUDE.md:

Prefix all shell commands with `oo`. Use `oo recall "<query>"` to search large outputs.

That's it. The agent runs oo cargo test, gets ✓ cargo test (47 passed, 2.1s), and moves on.

Built-in Patterns

oo ships with 10 patterns that match commands automatically:

Add your own patterns with oo learn <cmd> (generates a TOML pattern file via LLM) or write one manually in ~/.config/oo/patterns/.

FAQ

What if oo doesn't recognize my command? Unknown commands pass through unchanged (under 4KB) or get indexed for later retrieval via oo recall. Use oo learn <command> to teach oo a compression pattern.

Can I disable compression for a command? Unknown commands already pass through by default. For commands with built-in patterns, you can override with a custom TOML pattern. See Custom Patterns.

Does oo work in CI? It can, but oo is designed for interactive AI agent sessions where context tokens matter. In CI, full output is usually fine.

Which LLM providers does oo learn support? Anthropic only. Set ANTHROPIC_API_KEY in your environment. See Learning Patterns.

Troubleshooting

oo: command not found Ensure ~/.cargo/bin is in your PATH, or use the full path to the binary.

Pattern not matching my command Run oo patterns to see all loaded patterns and their command regexes. Custom patterns in ~/.config/oo/patterns/ override built-ins.

oo learn fails or produces bad patterns Ensure ANTHROPIC_API_KEY is set. Run the command normally first so oo has real output to analyze. See Learning Patterns.

Documentation

Documentation Index — Extensive project documentation:

• Testing Guide — How to run, write, and understand tests
• Architecture — System design and module responsibilities
• Security Model — Trust assumptions and data handling
• Custom Patterns — Creating patterns for command output compression
• Learning Patterns — Using oo learn to generate patterns automatically

For contributors: See CONTRIBUTING.md for development setup and workflow. For agents: See AGENTS.md for project-specific agent conventions.

License

Apache-2.0 — see LICENSE.

oo help fetches content from cheat.sh, which includes tldr-pages content (CC BY 4.0). See NOTICE.