{"id":37341431,"url":"https://github.com/boshu2/agentops","last_synced_at":"2026-04-10T05:59:33.173Z","repository":{"id":331171253,"uuid":"1090518613","full_name":"boshu2/agentops","owner":"boshu2","description":"The missing DevOps layer for coding agents. Flow, feedback, and memory that compounds between sessions.","archived":false,"fork":false,"pushed_at":"2026-04-02T23:10:13.000Z","size":48759,"stargazers_count":237,"open_issues_count":1,"forks_count":22,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-03T01:15:32.475Z","etag":null,"topics":["ai-agents","claude-code","claude-code-plugins","claude-marketplace","codex","codex-plugin","cursor","devops","opencode-plugin","vibe-coding"],"latest_commit_sha":null,"homepage":"https://github.com/boshu2/12-factor-agentops","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/boshu2.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-05T19:18:56.000Z","updated_at":"2026-04-02T23:10:16.000Z","dependencies_parsed_at":"2026-02-07T03:04:45.904Z","dependency_job_id":null,"html_url":"https://github.com/boshu2/agentops","commit_stats":null,"previous_names":["boshu2/agentops"],"tags_count":87,"template":false,"template_full_name":null,"purl":"pkg:github/boshu2/agentops","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boshu2%2Fagentops","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boshu2%2Fagentops/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boshu2%2Fagentops/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boshu2%2Fagentops/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/boshu2","download_url":"https://codeload.github.com/boshu2/agentops/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boshu2%2Fagentops/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31444702,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T15:22:31.103Z","status":"ssl_error","status_checked_at":"2026-04-05T15:22:00.205Z","response_time":75,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude-code","claude-code-plugins","claude-marketplace","codex","codex-plugin","cursor","devops","opencode-plugin","vibe-coding"],"created_at":"2026-01-16T03:51:24.411Z","updated_at":"2026-04-10T05:59:33.154Z","avatar_url":"https://github.com/boshu2.png","language":"Go","readme":"\u003cdiv align=\"center\"\u003e\n\n# AgentOps\n\n[![Validate](https://github.com/boshu2/agentops/actions/workflows/validate.yml/badge.svg?branch=main)](https://github.com/boshu2/agentops/actions/workflows/validate.yml)\n[![Nightly](https://github.com/boshu2/agentops/actions/workflows/nightly.yml/badge.svg)](https://github.com/boshu2/agentops/actions/workflows/nightly.yml)\n[![GitHub stars](https://img.shields.io/github/stars/boshu2/agentops?style=social)](https://github.com/boshu2/agentops/stargazers)\n\n### Coding agents don't do their own bookkeeping.\n\nThe operational layer for coding agents. AgentOps adds bookkeeping, validation, primitives, and flows so every session starts where the last one left off.\n\n[Install](#install) · [See It Work](#see-it-work) · [Start Here](#start-here) · [Behavior](docs/behavioral-discipline.md) · [What You Get](#what-agentops-gives-you) · [Skills](#skills) · [CLI](#the-ao-cli) · [FAQ](#faq) · [Docs](docs/INDEX.md) · [Newcomer Guide](docs/newcomer-guide.md)\n\n\u003c/div\u003e\n\n---\n\n## Install\n\n```bash\n# Claude Code (recommended): marketplace + plugin install\nclaude plugin marketplace add boshu2/agentops\nclaude plugin install agentops@agentops-marketplace\n\n# Codex CLI (v0.115.0+ native hooks by default)\ncurl -fsSL https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install-codex.sh | bash\n\n# OpenCode\ncurl -fsSL https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install-opencode.sh | bash\n\n# Other Skills-compatible agents (example: Cursor)\nnpx skills@latest add boshu2/agentops --cursor -g\n```\n\nThen type `/quickstart` in your agent chat.\n\nFor Codex, that installer stages the native plugin, installs `~/.codex/hooks.json`,\narchives stale raw mirrors when found, and makes native hooks the default path.\nRestart Codex after install.\n\n| Concern | Answer |\n|---------|--------|\n| 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` |\n| Source code changes | None. AgentOps does not modify your source code during install |\n| Network behavior | Install and update paths fetch from GitHub. Repo artifacts stay local unless you choose external tools, browsing, or remote model runtimes |\n| 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 |\n| Reversible | Remove the installed skill directories, delete `.agents/`, and remove hook entries from `.claude/settings.json` |\n\nNothing modifies your source code.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eInstall `ao` CLI\u003c/b\u003e — optional, unlocks the full repo-native layer\u003c/summary\u003e\n\nSkills work standalone. The `ao` CLI adds bookkeeping automation, retrieval and injection, maturity scoring, goals, and terminal-native flows.\n\n```bash\nbrew tap boshu2/agentops https://github.com/boshu2/homebrew-agentops\nbrew install agentops\nwhich ao\nao version\n```\n\nOr install via [release binaries](https://github.com/boshu2/agentops/releases) or [build from source](cli/README.md).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eOther install notes\u003c/b\u003e — Linux, OpenCode, configuration\u003c/summary\u003e\n\nOn Linux, install system `bubblewrap` so Codex uses it directly:\n\n```bash\nsudo apt-get install -y bubblewrap\n```\n\nOpenCode details: [.opencode/INSTALL.md](.opencode/INSTALL.md)\n\nAll configuration is optional. Full reference: [docs/ENV-VARS.md](docs/ENV-VARS.md)\n\n\u003c/details\u003e\n\nTroubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md)\n\n---\n\n## See It Work\n\n**One command** — validate a PR:\n\n```text\n\u003e /council validate this PR\n\n[council] 3 judges spawned (independent, no anchoring)\n[judge-1] PASS — token bucket implementation correct\n[judge-2] WARN — rate limiting missing on /login endpoint\n[judge-3] PASS — Redis integration follows middleware pattern\nConsensus: WARN — add rate limiting to /login before shipping\n```\n\n**Full pipeline** — research through post-mortem:\n\n```text\n\u003e /rpi \"add retry backoff to rate limiter\"\n\n[research]    Found 3 prior learnings on rate limiting (injected)\n[plan]        2 issues, 1 wave → epic ag-0058\n[pre-mortem]  Council validates plan → PASS (knew about Redis choice)\n[crank]       Parallel agents: Wave 1 ██ 2/2\n[vibe]        Council validates code → PASS\n[post-mortem] 2 new learnings → .agents/\n[flywheel]    Next: /rpi \"add circuit breaker to external API calls\"\n```\n\n**The endgame** — define goals, walk away, come back to a better codebase:\n\n```text\n\u003e /evolve\n\n[evolve] GOALS.md: 18 gates loaded, score 77.0% (14/18 passing)\n\n[cycle-1]     Worst: wiring-closure (weight 6) + 3 more\n              /rpi \"Fix failing goals\" → score 93.3% (25/28) ✓\n\n              ── the agent naturally organizes into phases ──\n\n[cycle-2-35]  Coverage blitz: 17 packages from ~85% → ~97% avg\n[cycle-38-59] Benchmarks added to all 15 internal packages\n[cycle-60-95] Complexity annihilation: zero functions \u003e= 8\n[cycle-96-116] Modernization: sentinel errors, exhaustive switches\n\n[teardown]    203 files changed, 20K+ lines, 116 cycles\n              All tests pass. Go vet clean. Avg coverage 97%.\n              /post-mortem → 33 learnings extracted\n```\n\nThat ran overnight on this repo. Regression gates auto-reverted anything that broke a passing goal.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eMore examples\u003c/b\u003e — swarm, continuity, and intent-based entry points\u003c/summary\u003e\n\n\u003cbr\u003e\n\n**Parallelize anything** with `/swarm`:\n\n```text\n\u003e /swarm \"research auth patterns, brainstorm rate limiting improvements\"\n\n[swarm] 3 agents spawned — each gets fresh context\n[agent-1] /research auth — found JWT + session patterns, 2 prior learnings\n[agent-2] /research rate-limiting — found token bucket, middleware pattern\n[agent-3] /brainstorm improvements — 4 approaches ranked\n[swarm] Complete — artifacts in .agents/\n```\n\n**Session continuity across compaction or restart:**\n\n```text\n\u003e /handoff\n[handoff] Saved: 3 open issues, current branch, next action\n         Continuation prompt written to .agents/handoffs/\n\n--- next session ---\n\n\u003e /recover\n[recover] Found in-progress epic ag-0058 (2/5 issues closed)\n          Branch: feature/rate-limiter\n          Next: /implement ag-0058.3\n```\n\n| Intent | Commands | What happens |\n|--------|----------|--------------|\n| **Review before shipping** | `/council validate this PR` | One command, actionable feedback |\n| **Understand before changing** | `/research` → `/plan` → `/council validate` | Surface prior context, scope the work, then validate the approach |\n| **Ship one change end to end** | `/rpi \"add user auth\"` | Run discovery through post-mortem in one flow |\n| **Parallelize or compound improvements** | `/swarm` + `/evolve` | Fan out work and keep improving the repo over time |\n\n\u003c/details\u003e\n\n---\n\n## Start Here\n\nA few commands, zero methodology. Pick an entry point and go:\n\n```bash\n/council validate this PR          # Multi-model code review — immediate value\n/research \"how does auth work\"     # Explore the codebase and surface prior bookkeeping\n/pre-mortem \"add retry backoff\"    # Pressure-test the plan before you build\n/implement \"fix the login bug\"     # Run one scoped task end to end\n```\n\nWhen you want bigger flows:\n\n```bash\n/plan → /crank                     # Decompose into issues, then parallel-execute\n/validation                        # Review finished work and extract learnings\n/rpi \"add retry backoff\"           # Full pipeline: discovery → build → validation → bookkeeping\n/evolve                            # Fitness-scored improvement loop\n```\n\nIf you want the explicit operator surface instead of individual primitives:\n\n```bash\nao factory start --goal \"fix auth startup\"\n/rpi \"fix auth startup\"           # or: ao rpi phased \"fix auth startup\"\nao codex stop\n```\n\nThat path keeps briefing, runtime startup, delivery, and session closeout on one surface.\n\nFull catalog: [docs/SKILLS.md](docs/SKILLS.md) · Unsure which skill to run? [Skill Router](docs/SKILL-ROUTER.md)\n\n---\n\n## What Good Agent Behavior Looks Like\n\nAgentOps is not only about chaining commands together. It also pushes agents toward better behavior during implementation and review.\n\n```text\nUser: \"Make search faster\"\n\nWithout behavioral discipline:\n- picks one interpretation silently\n- adds caching, async work, and config knobs\n- claims success when the code compiles\n\nWith AgentOps behavioral discipline:\n- clarifies whether \"faster\" means latency, throughput, or perceived speed\n- chooses the smallest change that matches that goal\n- verifies against the metric that actually mattered\n```\n\nThat same discipline shows up in four habits:\n\n- **Think before coding** — surface assumptions and tradeoffs instead of guessing.\n- **Simplicity first** — solve the problem with the smallest change that works.\n- **Surgical changes** — keep the diff tight and avoid drive-by refactors.\n- **Goal-driven execution** — define proof before calling the work done.\n\nSee the full before/after guide: [docs/behavioral-discipline.md](docs/behavioral-discipline.md)\n\n---\n\n## What AgentOps Gives You\n\nAgentOps gives your coding agent four things it does not have by default:\n\n1. **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.\n2. **Validation** — `/pre-mortem`, `/vibe`, and `/council` validate plans and code before they ship, and record what worked, what failed, and why.\n3. **Primitives** — individually invocable skills, hooks, and CLI surfaces you can pull from for almost any interaction.\n4. **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.\n\nSession 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.\n\nPrimitives 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.\n\nUnder the hood, AgentOps acts as a context compiler: raw session signal becomes reusable knowledge, compiled prevention, and better next work.\n\n```mermaid\nflowchart LR\n    P[Primitives\u003cbr/\u003eskills, hooks, ao CLI] --\u003e F[Flows\u003cbr/\u003ediscovery, implementation,\u003cbr/\u003evalidation, knowledge extraction]\n    F --\u003e B[Bookkeeping\u003cbr/\u003elearnings, findings,\u003cbr/\u003ereusable context]\n    F --\u003e V[Validation\u003cbr/\u003ewhat worked,\u003cbr/\u003ewhat failed, and why]\n    B --\u003e FW[(Flywheel\u003cbr/\u003ecapture -\u003e retrieve -\u003e promote)]\n    V --\u003e FW\n    FW --\u003e N[Next session\u003cbr/\u003ebetter context,\u003cbr/\u003estronger gates, faster work]\n    N --\u003e F\n```\n\nLocal and auditable: `.agents/` is plain text you can grep, diff, review in PRs, and open in Obsidian. Stale insights decay. Useful ones promote.\n\n---\n\n## Skills\n\nEvery skill works alone. Primitives are the single skills, hooks, and CLI surfaces. Flows are the named compositions built from them.\n\n| Skill | What it does |\n|-------|--------------|\n| `/council` | Independent judges debate, surface disagreement, and converge. The core validation primitive |\n| `/research` | Discovery primitive — explores the codebase and produces structured findings with prior bookkeeping surfaced at the right time |\n| `/implement` | Single-task flow — research, plan, build, validate, learn |\n| `/rpi` | Full pipeline flow — discovery → implementation → validation → bookkeeping |\n| `/vibe` | Code quality review — complexity + council + domain checklists |\n| `/evolve` | Measure goals, fix the worst gap, regression-gate everything, repeat overnight |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eFull catalog\u003c/b\u003e — validation, flows, bookkeeping, and supporting skills\u003c/summary\u003e\n\n**Validation:** `/council` · `/vibe` · `/pre-mortem` · `/post-mortem`\n\n**Flows:** `/research` · `/plan` · `/implement` · `/crank` · `/swarm` · `/rpi` · `/evolve`\n\n**Bookkeeping:** `/retro` · `/forge` · `/flywheel` · `/compile`\n\n**Session:** `/handoff` · `/recover` · `/status` · `/trace` · `/provenance`\n\n**Product:** `/product` · `/goals` · `/release` · `/readme` · `/doc`\n\n**Utility:** `/brainstorm` · `/bug-hunt` · `/complexity` · `/scaffold` · `/push`\n\nFull reference: [docs/SKILLS.md](docs/SKILLS.md)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCross-runtime orchestration\u003c/b\u003e — mix Claude, Codex, and OpenCode\u003c/summary\u003e\n\nAgentOps orchestrates across runtimes. Claude can lead a team of Codex workers. Codex judges can review Claude's output.\n\n| Backend | How it works | Best for |\n|---------|-------------|----------|\n| **Native teams** | `TeamCreate` + `SendMessage` | Tight coordination, debate |\n| **Codex sub-agents** | `/codex-team` | Cross-vendor validation |\n| **Background tasks** | `Task(run_in_background=true)` | Fallback when no team APIs are available |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eHow It Works\u003c/b\u003e — phases, flywheel, and architecture\u003c/summary\u003e\n\n### Phases\n\n| Phase | Primary skills | What you get |\n|-------|----------------|--------------|\n| Discovery | `/brainstorm` → `/research` → `/plan` → `/pre-mortem` | Surfaces prior context, scopes the work, and pressure-tests the plan before build |\n| Implementation | `/crank` → `/swarm` → `/implement` | Executes scoped work through composable primitives and wave-based coordination |\n| Validation + bookkeeping | `/validation` → `/vibe` → `/post-mortem` → `/retro` → `/forge` | Captures what worked, what failed, and what should feed the next cycle |\n\n`/rpi` orchestrates all three phases. `/evolve` keeps running `/rpi` against `GOALS.md` so the worst fitness gap gets addressed next.\n\nThe explicit operator surface around that line is:\n\n- `ao factory start` for briefing-first startup\n- `/rpi` or `ao rpi phased` for delivery\n- `ao codex stop` for explicit session closeout\n\n### How bookkeeping compounds\n\n`.agents/` is the repo-native bookkeeping layer for what your agents learned, stored as plain files.\n\n```text\n┌──────────────────────────────────────────────────────────────────────────┐\n│   Traditional Cache          .agents/ Knowledge Store                    │\n│  ┌────────────────────┐    ┌──────────────────────────────────────────┐  │\n│  │ Stores results     │    │ Stores extracted lessons                 │  │\n│  │ Hit = skip compute │    │ Hit = skip the 2-hour debugging          │  │\n│  │ Flat key-value     │    │ Hierarchical: learning → pattern → rule  │  │\n│  │ Static after write │    │ Promotes through tiers over time         │  │\n│  │ One consumer       │    │ Any agent, any runtime, any session      │  │\n│  └────────────────────┘    └──────────────────────────────────────────┘  │\n└──────────────────────────────────────────────────────────────────────────┘\n```\n\n```text\n\u003e /research \"retry backoff strategies\"\n\n[lookup] 3 prior learnings found (freshness-weighted):\n  - Token bucket with Redis (established, high confidence)\n  - Rate limit at middleware layer, not per-handler (pattern)\n  - /login endpoint was missing rate limiting (decision)\n[research] Found prior art in your codebase + retrieved context\n           Recommends: exponential backoff with jitter, reuse existing Redis client\n```\n\nIn repeated use, the compounding effect is that the environment gets smarter while the model stays the same.\n\n### Deep dive\n\n| Topic | Where |\n|-------|-------|\n| Five pillars, operational invariants | [Architecture](docs/ARCHITECTURE.md) |\n| Brownian Ratchet, context windowing | [How It Works](docs/how-it-works.md) |\n| Injection philosophy, freshness decay, MemRL | [The Science](docs/the-science.md) |\n| Context lifecycle, three-tier injection | [Context Lifecycle](docs/context-lifecycle.md) |\n| Philosophy and observations | [Philosophy](docs/philosophy.md) |\n\n**Built on:** [Ralph Wiggum](https://ghuntley.com/ralph/) · [Multiclaude](https://github.com/dlorenc/multiclaude) · [beads](https://github.com/steveyegge/beads) · [CASS](https://github.com/Dicklesworthstone/coding_agent_session_search) · [MemRL](https://arxiv.org/abs/2601.03192)\n\n\u003c/details\u003e\n\n---\n\n## The `ao` CLI\n\nThe `ao` CLI adds repo-native bookkeeping automation, retrieval, decay, maturity scoring, and terminal-native flows that run without an active chat session.\n\n```bash\nao seed                                    # Plant AgentOps in any repo\nao rpi loop --supervisor --max-cycles 1    # Canonical autonomous cycle\nao rpi phased --from=implementation ag-058 # Resume a specific phased run\nao search \"query\"                          # Search session history and repo-local bookkeeping\nao lookup --query \"topic\"                  # Retrieve curated learnings, patterns, and findings\nao context assemble                        # Build a task briefing\nao memory sync                             # Sync session history into MEMORY.md bookkeeping notes\nao metrics health                          # Flywheel health dashboard\nao demo                                    # Interactive demo\n```\n\nFull reference: [CLI Commands](cli/docs/COMMANDS.md)\n\n---\n\n## How AgentOps Fits With Other Tools\n\n| Tool | What it does well | What AgentOps adds |\n|------|-------------------|-------------------------------------|\n| **[GSD](https://github.com/glittercowboy/get-shit-done)** | Clean subagent spawning, fights context rot | Cross-session bookkeeping — carries reusable knowledge between sessions |\n| **[Compound Engineer](https://github.com/EveryInc/compound-engineering-plugin)** | Knowledge compounding, structured loop | Multi-model councils and validation gates |\n\n[Detailed comparisons →](docs/comparisons/)\n\n---\n\n## Contributing\n\nSee [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md). Agent contributors should also read [AGENTS.md](AGENTS.md) and use `bd` for issue tracking.\n\n## FAQ\n\n[docs/FAQ.md](docs/FAQ.md)\n\n## License\n\nApache-2.0 · [Docs](docs/INDEX.md) · [CLI Reference](cli/docs/COMMANDS.md)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboshu2%2Fagentops","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fboshu2%2Fagentops","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboshu2%2Fagentops/lists"}