AgentOps

Coding agents don't do their own bookkeeping.

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

Install · Quick Start · Skills · CLI · Docs

---

Install

Pick the runtime you use.

Claude Code

claude plugin marketplace add boshu2/agentops
claude plugin install agentops@agentops-marketplace

Codex CLI on macOS, Linux, or WSL

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

npx skills@latest add boshu2/agentops --cursor -g

Restart your agent after install. Then type /quickstart in your agent chat.

The ao CLI is optional, but recommended. It unlocks repo-native bookkeeping, retrieval, health checks, and terminal workflows.

macOS

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

Windows PowerShell

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

You can also install the CLI from release binaries or build from source.

Concern	Answer
What it touches	Installs skills globally and registers runtime hooks when requested; agent work writes local bookkeeping to .agents/
Source code changes	None during install
Network behavior	Install and update paths fetch from GitHub; repo artifacts stay local unless you choose external tools or remote model runtimes
Telemetry	None required
Permission surface	Skills can run shell commands and read or write repo files during agent work, so install where you want agents to operate
Reversible	Remove the installed skill directories, delete .agents/, and remove hook entries from your runtime settings

Troubleshooting: docs/troubleshooting.md · Configuration: docs/ENV-VARS.md

---

Quick Start

Inside a repo, run one command in your agent chat:

/quickstart

That detects setup, explains the system, and gives you the next action.

Then try the smallest useful flow:

/council validate this PR

Or let AgentOps run the full discovery-to-validation loop:

/rpi "a small goal"

If you installed the CLI, check your local setup:

ao doctor
ao demo

New project? Use the guided CLI path:

ao quick-start

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

---

See It Work

One command: validate a PR

> /council validate this PR

[council] 3 judges spawned independently
[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 loop: research through post-mortem

> /rpi "add retry backoff to rate limiter"

[research]    Found 3 prior learnings on rate limiting
[plan]        2 issues, 1 wave
[pre-mortem]  Council validates the plan
[crank]       Executes the scoped work
[vibe]        Council validates the code
[post-mortem] Captures new learnings in .agents/
[flywheel]    Next session starts with better context

The point is not a bigger prompt. The point is a repo that remembers what worked.

---

What AgentOps Gives You

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

Layer	What changes
Bookkeeping	Learnings, findings, handoffs, and reusable context land in local .agents/ files
Validation	/pre-mortem, /vibe, and /council challenge plans and code before they ship
Primitives	Skills, hooks, and the ao CLI give agents reusable building blocks
Flows	/research, /implement, /validation, and /rpi compose those primitives end to end

Session 1, your agent spends two hours debugging a timeout bug. Session 15, a new agent finds the lesson in seconds because the repo kept it.

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

flowchart LR
    S[Session work] --> B[Bookkeeping]
    S --> V[Validation]
    B --> F[Knowledge flywheel]
    V --> F
    F --> N[Next session]
    N --> S

Loading

Local and auditable: .agents/ is plain text you can grep, diff, review, and commit when you choose. There is no telemetry or cloud service requirement.

---

Skills

Every skill works alone. Flows compose them when you want more structure.

Skill	Use it when
/quickstart	You want the fastest setup check and next action
/council	You want independent judges to review a plan, PR, or decision
/research	You need codebase context and prior learnings before changing code
/pre-mortem	You want to pressure-test a plan before implementation
/implement	You want one scoped task built and validated
/rpi	You want discovery, build, validation, and bookkeeping in one flow
/vibe	You want a code-quality and risk review before shipping
/evolve	You want a goal-driven improvement loop with regression gates
/dream	You want overnight knowledge compounding that never mutates source code

Full catalog - validation, flows, bookkeeping, and session skills

Validation: /council · /vibe · /pre-mortem · /post-mortem

Flows: /research · /plan · /implement · /crank · /swarm · /rpi · /evolve

Bookkeeping: /retro · /forge · /flywheel · /compile

Session: /handoff · /recover · /status · /trace · /provenance · /dream

Product: /product · /goals · /release · /readme · /doc

Utility: /brainstorm · /bug-hunt · /complexity · /scaffold · /push

Full reference: docs/SKILLS.md

Cross-runtime orchestration - mix Claude, Codex, Cursor, and OpenCode

AgentOps keeps the workflow shape consistent across runtimes. Use the same validation, research, delivery, and bookkeeping flows whether the active worker is Claude Code, Codex, Cursor, or OpenCode.

That lets one runtime lead a session, another review the result, and a third handle focused implementation. The exact adapter is runtime-specific; the product contract is the same: independent context, auditable files, and explicit validation before promotion.

---

The ao CLI

The ao CLI is the repo-native control plane behind the skills. It handles retrieval, health checks, compounding, goals, and terminal workflows.

ao quick-start                            # Set up AgentOps in a repo
ao doctor                                 # Check local health
ao demo                                   # See the value path in 5 minutes
ao search "query"                         # Search session history and local knowledge
ao lookup --query "topic"                 # Retrieve curated learnings and findings
ao context assemble                       # Build a task briefing
ao rpi phased "fix auth startup"          # Run the phased lifecycle from the terminal
ao evolve --max-cycles 1                  # Run one autonomous improvement cycle
ao overnight setup                        # Prepare private Dream runs
ao metrics health                         # Show flywheel health

Full reference: CLI Commands

---

Advanced: Day Loop And Night Loop

Use /evolve when you want code improvement. It reads GOALS.md, fixes the worst fitness gap, runs regression gates, and records the cycle.

> /evolve

[evolve] GOALS.md loaded
[cycle-1] Worst gap selected
[rpi]     Implements the fix
[gate]    Tests and quality checks pass
[learn]   Post-mortem feeds the flywheel

Use /dream when you want knowledge compounding. It runs offline-style bookkeeping work over .agents/, reports what changed, and never mutates source code, invokes /rpi, or performs git operations.

> /dream start

[overnight] INGEST  harvest new artifacts
[overnight] REDUCE  dedup, defrag, close loops
[overnight] MEASURE corpus quality
[halted]    plateau reached

Morning report: .agents/overnight/<run-id>/summary.md

Run Dream overnight, then run Evolve in the morning against a fresher corpus. The model may be the same; the environment is smarter.

---

How AgentOps Fits With Other Tools

Tool	What it does well	What AgentOps adds
GSD	Clean subagent spawning, fights context rot	Cross-session bookkeeping and validation gates
Compound Engineer	Knowledge compounding, structured loop	Multi-runtime skills, council validation, and repo-native ao workflows

Detailed comparisons

---

Docs

Topic	Where
Start navigating	Docs index
New contributor orientation	Newcomer guide
Full skill catalog	Skills
CLI reference	CLI commands
Architecture	Architecture
Behavioral discipline	Behavior guide
FAQ	FAQ

---

Contributing

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

License

Apache-2.0 · Docs · CLI Reference