AgentOps

Coding agents don't do their own bookkeeping.

The operational layer for coding agents. AgentOps adds bookkeeping, validation, primitives, and flows so every session starts where the last one left off.

Install · See It Work · Start Here · Behavior · What You Get · Skills · CLI · FAQ · Docs · Newcomer Guide

Install

# Claude Code (recommended): marketplace + plugin install
claude plugin marketplace add boshu2/agentops
claude plugin install agentops@agentops-marketplace

# Codex CLI on macOS/Linux/WSL (v0.115.0+ native hooks by default)
curl -fsSL https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install-codex.sh | bash

# Codex CLI on Windows PowerShell
irm https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install-codex.ps1 | iex

# OpenCode
curl -fsSL https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install-opencode.sh | bash

# Other Skills-compatible agents (example: Cursor)
npx skills@latest add boshu2/agentops --cursor -g

Then type /quickstart in your agent chat.

For Codex, use the shell installer on macOS/Linux/WSL and the PowerShell installer on native Windows. The installer stages the native plugin, installs ~/.codex/hooks.json, archives stale raw mirrors when found, and makes native hooks the default path. Restart Codex after install.

| Concern | Answer | |---------|--------| | What it touches | Installs skills globally, writes knowledge artifacts to .agents/, registers Claude hooks in .claude/settings.json when requested, and for Codex writes the native plugin cache plus ~/.codex/hooks.json | | Source code changes | None. AgentOps does not modify your source code during install | | Network behavior | Install and update paths fetch from GitHub. Repo artifacts stay local unless you choose external tools, browsing, or remote model runtimes | | Permission surface | Skills may run shell commands and read or write repo files as part of agent work, so install it where you want an agent to operate | | Reversible | Remove the installed skill directories, delete .agents/, and remove hook entries from .claude/settings.json |

Nothing modifies your source code.

Skills work standalone. The ao CLI adds bookkeeping automation, retrieval and injection, maturity scoring, goals, and terminal-native flows.

# macOS
brew tap boshu2/agentops https://github.com/boshu2/homebrew-agentops
brew install agentops
which ao
ao version

# Windows PowerShell
irm https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install-ao.ps1 | iex
ao version

Or install via release binaries or build from source.

On Linux, install system bubblewrap so Codex uses it directly:

sudo apt-get install -y bubblewrap

OpenCode details: .opencode/INSTALL.md

All configuration is optional. Full reference: docs/ENV-VARS.md

Troubleshooting: docs/troubleshooting.md

See It Work

One command — validate a PR:

> /council validate this PR

[council] 3 judges spawned (independent, no anchoring)
[judge-1] PASS — token bucket implementation correct
[judge-2] WARN — rate limiting missing on /login endpoint
[judge-3] PASS — Redis integration follows middleware pattern
Consensus: WARN — add rate limiting to /login before shipping

Full pipeline — research through post-mortem:

> /rpi "add retry backoff to rate limiter"

[research]    Found 3 prior learnings on rate limiting (injected)
[plan]        2 issues, 1 wave → epic ag-0058
[pre-mortem]  Council validates plan → PASS (knew about Redis choice)
[crank]       Parallel agents: Wave 1 ██ 2/2
[vibe]        Council validates code → PASS
[post-mortem] 2 new learnings → .agents/
[flywheel]    Next: /rpi "add circuit breaker to external API calls"

The endgame — define goals, walk away, come back to a better codebase:

> /evolve

[evolve] GOALS.md: 19 gates loaded, score recalculated

[cycle-1]     Worst: wiring-closure (weight 6) + 3 more
              /rpi "Fix failing goals" → score 93.3% (25/28) ✓

              ── the agent naturally organizes into phases ──

[cycle-2-35]  Coverage blitz: 17 packages from ~85% → ~97% avg
[cycle-38-59] Benchmarks added to all 15 internal packages
[cycle-60-95] Complexity annihilation: zero functions >= 8
[cycle-96-116] Modernization: sentinel errors, exhaustive switches

[teardown]    203 files changed, 20K+ lines, 116 cycles
              All tests pass. Go vet clean. Avg coverage 97%.
              /post-mortem → 33 learnings extracted

That ran overnight on this repo. Regression gates auto-reverted anything that broke a passing goal.

The night-shift endgame — your agent wakes up smarter, even when you don't touch code:

> /dream start

[overnight]  RunLoop starting (budget=2h, max_iter=4, K=2, warn_only=true)
[iter-1]     INGEST   harvest catalog: 152 artifacts (dry-run preview)
             REDUCE   harvest-promote → dedup → defrag-prune → close-loop
                      findings-router: 7 new → next-work.jsonl
                      inject-refresh: in-process
                      metadata integrity: PASS (0 stripped fields)
             COMMIT   staging → live (per-subpath rename)
             MEASURE  corpus-quality snapshot captured  (4.2s)
[iter-2]     INGEST clean · REDUCE clean · MEASURE Δ +0.003 (plateau)
[halted]     plateau — K=2 consecutive sub-epsilon deltas

Morning report: .agents/overnight/<run-id>/summary.md
  • 2 committed iterations · 0 rolled back
  • 7 findings routed into next-work.jsonl
  • 0 source mutations · 0 git ops · 0 symlinks  (anti-goals enforced)
  • Inject cache rebuilt — /evolve tomorrow starts against a fresher corpus

/evolve is the day loop — fitness-driven code improvement that can touch source. /dream is the night loop — fitness-driven knowledge compounding that never touches source, runs through a checkpointed overlay, and rolls back on regression. Run Dream overnight, run Evolve in the morning against the compounded corpus, and the environment gets sharper even when you're asleep.

Parallelize anything with /swarm:

> /swarm "research auth patterns, brainstorm rate limiting improvements"

[swarm] 3 agents spawned — each gets fresh context
[agent-1] /research auth — found JWT + session patterns, 2 prior learnings
[agent-2] /research rate-limiting — found token bucket, middleware pattern
[agent-3] /brainstorm improvements — 4 approaches ranked
[swarm] Complete — artifacts in .agents/

Session continuity across compaction or restart:

> /handoff
[handoff] Saved: 3 open issues, current branch, next action
         Continuation prompt written to .agents/handoffs/

--- next session ---

> /recover
[recover] Found in-progress epic ag-0058 (2/5 issues closed)
          Branch: feature/rate-limiter
          Next: /implement ag-0058.3

| Intent | Commands | What happens | |--------|----------|--------------| | Review before shipping | /council validate this PR | One command, actionable feedback | | Understand before changing | /research → /plan → /council validate | Surface prior context, scope the work, then validate the approach | | Ship one change end to end | /rpi "add user auth" | Run discovery through post-mortem in one flow | | Parallelize or compound improvements | /swarm + /evolve | Fan out work and keep improving the repo over time |

Start Here

A few commands, zero methodology. Pick an entry point and go:

/council validate this PR          # Multi-model code review — immediate value
/research "how does auth work"     # Explore the codebase and surface prior bookkeeping
/pre-mortem "add retry backoff"    # Pressure-test the plan before you build
/implement "fix the login bug"     # Run one scoped task end to end

When you want bigger flows:

/plan → /crank                     # Decompose into issues, then parallel-execute
/validation                        # Review finished work and extract learnings
/rpi "add retry backoff"           # Full pipeline: discovery → build → validation → bookkeeping
/evolve                            # Fitness-scored improvement loop

If you want the explicit operator surface instead of individual primitives:

ao factory start --goal "fix auth startup"
/rpi "fix auth startup"           # or: ao rpi phased "fix auth startup"
ao codex stop

That path keeps briefing, runtime startup, delivery, and session closeout on one surface.

Full catalog: docs/SKILLS.md · Unsure which skill to run? Skill Router

What Good Agent Behavior Looks Like

AgentOps is not only about chaining commands together. It also pushes agents toward better behavior during implementation and review.

User: "Make search faster"

With