12-Factor AgentOps

Install AgentOps, then try one useful task.

Three steps. The first task is read-only and needs no ao CLI, so it is safe in a repository you already work on.

v3.9.0 README ↗Release notes ↗Inspect AgentOps ↗

Which agent do you use?

Use one install method to avoid duplicate copies.

Install in your terminal

Needs plugin support.

terminal · Claude Code
claude plugin marketplace add boshu2/agentops
claude plugin install agentops@agentops-marketplace
claude plugin details agentops@agentops-marketplace

The plugin should appear as agentops, with its skills and four agents. Then start a new session in a project you already work on.

Paste one Research task into your agent

Into the agent session, not your terminal. Claude Code uses the slash-command prefix.

agent prompt · Claude Code
/agentops:research Find how this repository validates user input. Trace one path from the input through validation and its tests. Cite the relevant files and line numbers, explain one edge case, and identify any missing coverage. Answer in this conversation without changing files. Name the Research skill file you loaded.
Expect
A trace you can inspect: where input enters, which checks accept or reject it, and what the tests cover.
If a step can’t be established
The answer should say what is missing. The skill file it names shows which copy loaded.

Research itself does not authorize a code change.

Choose the next useful task

Test should return the tests, commands and results. Refactor should check its change against existing behavior. Independent choices, not required steps. Ordinary language also works: “Use AgentOps Test to cover the missing edge case we just traced.”

Add coverage for an edge case/agentops:test
Simplify code while preserving behavior/agentops:refactor
A worked example from AgentOps

How does ao skills link validate skill names before creating links?

Finding
validateSelection checks every requested name before LinkAllDests enters its destination loop. One missing name rejects the selection before any links are created, including in dry-run mode.
Change
PR #1129 added repeatable --skill selection with this preflight check, preserving existing and unselected entries.
Checks
Two regression tests cover invalid selections in real and dry-run modes, duplicate names, and preserved foreign and unselected entries. Both passed when checked for this example.
terminal · from the AgentOps checkout's cli directory
go test ./internal/skillsapp -run '^TestSelectedLink(DryRunPreflightsAllNamesAcrossDestinations|PreservesForeignAndUnselectedEntries)$' -count=1

Later, when you need it

UpdateClaude Code, Codex, the ao CLI

Version 3.9 removes ten bundled external tool skills, retires three delivery workflows and makes the Codex plugin read skills/ directly. Run only the commands for your runtime, then start a new session. Upgrade ao before using an updated source checkout. A new install does not remove obsolete copies.

terminal · Claude Code
claude plugin marketplace update agentops-marketplace
claude plugin update agentops@agentops-marketplace
terminal · Codex
codex plugin marketplace upgrade agentops-marketplace
codex plugin add agentops@agentops-marketplace
terminal · ao CLI, if installed with Homebrew
brew update && brew upgrade agentops

For local marketplaces, copied skills, source links, or separately installed hooks and roles, follow the install and update guide. When upgrading from 3.6 or earlier, read the migration guide for removed commands and former skill names.

RemoveClaude Code, Codex
terminal
# Remove the Claude Code bundle
claude plugin uninstall agentops@agentops-marketplace

# Or remove the Codex bundle
codex plugin remove agentops@agentops-marketplace
Add the ao CLIoptional · Homebrew

Install ao for deterministic repository checks and evidence commands, or when a selected skill requires it. Validate requires ao; some paths in Plan, RPI, and other skills also need it. Review the skill dependencies and CLI install instructions first.

terminal
brew tap boshu2/agentops
brew trust --tap boshu2/agentops
brew install agentops
ao version
Other install pathsuser-level · source checkout

For a user-level skill install, pick the agents and skills you use. Choose one source per skill to avoid duplicate copies.

terminal
npx skills@latest add boshu2/agentops -g

If you edit skills or want to link a selected subset, follow the source checkout instructions.

Permissions and hookswhat the plugin installs

Skills use your coding agent’s normal permissions. The Claude plugin also installs its policy dispatcher. Optional source-read limits and Codex’s additional agent roles require separate setup.

The doctrine explains independent review. Your coding agent and repository keep their existing workflow. Read the 12 factors →