AgentOps

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

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

# 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, that 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.

Nothing modifies your source code.

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

sudo apt-get install -y bubblewrap

Troubleshooting: docs/troubleshooting.md

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: 18 gates loaded, score 77.0% (14/18 passing)

[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.

> /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/

> /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

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

AgentOps gives your coding agent four things it does not have by default:

1. Bookkeeping — sessions do not just leave behind chat history; AgentOps captures learnings, findings, and reusable context, then resurfaces them through .agents/, retrieval, and the flywheel.
2. Validation — /pre-mortem, /vibe, and /council validate plans and code before they ship, and record what worked, what failed, and why.
3. Primitives — individually invocable skills, hooks, and CLI surfaces you can pull from for almost any interaction.
4. Flows — named compositions of those primitives for discovery, implementation, validation, and knowledge extraction that you can run separately, compose together, or automate end to end.

Session 1, your agent spends 2 hours debugging a timeout bug. Session 15, a new agent finds the answer in 10 seconds because the lesson was captured, validated, and surfaced back into the next cycle.

Primitives compose into flows, flows generate bookkeeping, validation shapes what gets promoted, and together they feed the flywheel so the repo compounds knowledge instead of resetting every session.

Under the hood, AgentOps acts as a context compiler: raw session signal becomes reusable knowledge, compiled prevention, and better next work.

flowchart LR
    P[Primitives<br/>skills, hooks, ao CLI] --> F[Flows<br/>discovery, implementation,<br/>validation, knowledge extraction]
    F --> B[Bookkeeping<br/>learnings, findings,<br/>reusable context]
    F --> V[Validation<br/>what worked,<br/>what failed, and why]
    B --> FW[(Flywheel<br/>capture -> retrieve -> promote)]
    V --> FW
    FW --> N[Next session<br/>better context,<br/>stronger gates, faster work]
    N --> F

Local and auditable: .agents/ is plain text you can grep, diff, review in PRs, and open in Obsidian. Stale insights decay. Useful ones promote.

Every skill works alone. Primitives are the single skills, hooks, and CLI surfaces. Flows are the named compositions built from them.

┌──────────────────────────────────────────────────────────────────────────┐
│   Traditional Cache          .agents/ Knowledge Store                    │
│  ┌────────────────────┐    ┌──────────────────────────────────────────┐  │
│  │ Stores results     │    │ Stores extracted lessons                 │  │
│  │ Hit = skip compute │    │ Hit = skip the 2-hour debugging          │  │
│  │ Flat key-value     │    │ Hierarchical: learning → pattern → rule  │  │
│  │ Static after write │    │ Promotes through tiers over time         │  │
│  │ One consumer       │    │ Any agent, any runtime, any session      │  │
│  └────────────────────┘    └──────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────────┘

> /research "retry backoff strategies"

[lookup] 3 prior learnings found (freshness-weighted):
  - Token bucket with Redis (established, high confidence)
  - Rate limit at middleware layer, not per-handler (pattern)
  - /login endpoint was missing rate limiting (decision)
[research] Found prior art in your codebase + retrieved context
           Recommends: exponential backoff with jitter, reuse existing Redis client

The ao CLI adds repo-native bookkeeping automation, retrieval, decay, maturity scoring, and terminal-native flows that run without an active chat session.

ao seed                                    # Plant AgentOps in any repo
ao rpi loop --supervisor --max-cycles 1    # Canonical autonomous cycle
ao rpi phased --from=implementation ag-058 # Resume a specific phased run
ao search "query"                          # Search session history and repo-local bookkeeping
ao lookup --query "topic"                  # Retrieve curated learnings, patterns, and findings
ao context assemble                        # Build a task briefing
ao memory sync                             # Sync session history into MEMORY.md bookkeeping notes
ao metrics health                          # Flywheel health dashboard
ao demo                                    # Interactive demo

Full reference: CLI Commands

Detailed comparisons →

See docs/CONTRIBUTING.md. Agent contributors should also read AGENTS.md and use bd for issue tracking.

docs/FAQ.md

Apache-2.0 · Docs · CLI Reference