Production-oriented AgentOps platform for Claude Code and Codex.
Octopus AgentOps turns repeatable AI coding workflows into installable, versioned, and auditable agent plugins. It focuses on the work that must be dependable in real projects: Git/CI governance, MCP E2E lifecycle validation, real Dashboard user-flow debugging, production lifecycle validation, evidence collection, and cross-OS diagnostics.
The product goal is simple: manage agent operations as reusable product assets, not as one-off prompts and temporary scripts scattered across projects.
octopus-agentops is the source repository for Octopus AgentOps. It is a platform repository, not a set of separate agent projects. The packaged agents share the same contracts, release gates, sandbox, installation flow, and Codex/Claude Code distribution pipeline.
It provides:
- Specialized subagents for Claude Code and Codex.
- Plugin manifests and generated catalogs for search and installation.
- Agent product contracts for inputs, outputs, evidence, confirmation gates, dangerous actions, and native runtime capabilities.
- Runtime-neutral loop contracts with a Codex
/goaladapter for Codex-native release workflows. - A shared Production Representative Sandbox for local release coverage matrix loops when real customer production projects are not available.
- Generated Codex distributions from canonical Markdown agent sources.
- Deterministic validation and eval scripts.
- Release-readiness gates for public beta distribution.
- A lightweight CLI control plane for listing, searching, installing, and checking drift.
| Tool | Install Target | Scope |
|---|---|---|
| Claude Code | ~/.claude/agents/ |
用户级 agents |
| Codex | .codex/agents/ |
项目级 agents |
| Agent | Purpose |
|---|---|
product-evolution-lab |
Generic product evolution lab for authorized materials, product E2E pressure, improvement evidence, review closure, and goal-driven loops. |
scm-sync-governor |
SCM synchronization, commit, push, PR/MR/CI boundaries, and conflict handling. |
mcp-e2e-governor |
MCP intelligent-agent E2E lifecycle governor: discovery, prompt confirmation, execution, diagnosis, controlled code-fix, and evidence-backed self-evolution proposals. |
user-flow-debug |
Real Dashboard user-flow debugging with runtime-flow discovery, screenshots, artifacts, role validation, diagnosis, and controlled fixes. |
| Plugin | Agents |
|---|---|
git-workflow |
scm-sync-governor |
mcp-e2e-governance |
mcp-e2e-governor, user-flow-debug |
product-evolution-lab |
product-evolution-lab |
Octopus AgentOps keeps these agents in one platform repository because they share the same operational substrate:
loopContractand runtime adapters.- Manifest, plugin, catalog, and generated distribution contracts.
- Codex
/goaladapter and Claude Code Markdown distribution. - Release coverage matrix, evidence discipline, confirmation gates, and production release rules.
- Portable sandbox, project profiles, install drift checks, eval, and release-readiness gates.
Agents should graduate to an independent repository only when they have an independent user entrypoint, runtime, install package, issue surface, and release cadence. Until then, each product line should mature as a plugin inside this repository so shared platform behavior does not drift.
| Product Line | Plugin Boundary | Split Readiness |
|---|---|---|
| MCP E2E governance | plugins/mcp-e2e-governance/ |
Candidate only after MCP E2E execution becomes a standalone product surface. |
| SCM workflow governance | plugins/git-workflow/ |
Keep as a platform plugin unless it becomes a dedicated Git/CI agent product. |
| Product evolution lab | plugins/product-evolution-lab/ |
Keep in-platform while it depends on shared profiles, runners, and evidence stores. |
- Teams that reuse the same Claude Code / Codex workflows across multiple repositories.
- Agent product builders who need real MCP E2E validation, not only prompt-level demos.
- Developers who want Git, CI, MR/PR, and deployment-adjacent actions guarded by explicit confirmation and evidence.
- Product teams that require Dashboard-level user-flow proof instead of API-only smoke checks.
- Maintainers who want installed agents to be searchable, versioned, validated, evaluated, and drift-checked.
Canonical agent sources live in agents/*.md. Claude Code installs the Markdown sources directly. Codex installs generated TOML distributions from integrations/codex/agents/*.toml.
Agent product contracts live in manifests/agents/*.json. Every agent declares its source/distribution paths, lifecycle, plugin, category, native capabilities, inputs, outputs, evidence, confirmation gates, dangerous actions, and validation rules.
Plugin contracts live in plugins/<plugin>/plugin.json. scripts/generate-catalog.py generates catalog/agents.json and catalog/plugins.json, enabling search, install, and drift checks by plugin.
scripts/generate-distributions.py renders Codex TOML agents from canonical Markdown sources and manifest-native capability declarations. This keeps the agent body, product contract, and installed Codex distribution aligned.
npm run check validates source files, generated distributions, plugin/catalog consistency, and core scripts. npm run eval runs deterministic quality checks and a temporary Codex install round-trip.
npm run release:check is the public-beta release gate. It checks package metadata, license, agent/plugin lifecycle state, loop contract coverage, Codex goal plans, generated outputs, deterministic eval, project-scoped Codex install drift, and whitespace safety.
The release target is intentionally precise: Octopus AgentOps is a release-ready subagent operations platform and control plane, not a replacement for broad agent frameworks such as LangGraph, CrewAI, AutoGen, or OpenHands. See docs/release-readiness.md and docs/competitive-baseline.md for the release bar and comparison boundary.
Stable GA is a separate hardening target. The public-beta gate may pass while stable GA remains blocked by lifecycle, CI, real-project evidence, distribution, contract, or operability gaps:
npm run release:check:ga
npm run release:check:ga -- --jsonSee docs/ga-release-plan.md, docs/ga-criteria.md, and
docs/support-matrix.md for the stable GA plan and support boundary.
OS-sensitive checks are centralized in bin/octopus-sandbox and sandbox/octopus_sandbox.py, so installed agents avoid project-local temporary scripts and optional command dependencies.
scm-sync-governor separates branch selection, sync, commit, push, pull requests or merge requests, CI diagnosis, and conflict handling so high-risk Git actions are explicit and auditable.
user-flow-debug drives real Dashboard UI paths, captures screenshots, validates artifacts, classifies runtime flow, and follows the selected fix policy.
| Flow Type | 测试策略 |
|---|---|
attachment-driven |
只上传首个可见步骤或启动表单要求的附件,然后按 UI choice/review 推进 |
time-driven |
等待服务端计划触发后的 Agent 消息,再按当前 step 要求上传附件、输入目录路径或提交文本 |
chat-driven |
主要通过可见对话问题和输入框推进,不预设附件流程 |
hybrid |
按每个 step 的可见输入要求组合附件、路径、文本和选择 |
time-driven 测试遵守生产边界:Dashboard UI 不应出现 tick/debug 控件。local-dev 需要加速验证时,优先使用服务端 scheduler、测试时间窗口和隔离的 output root;只有用户明确允许测试内部推进时,才可调用内部 tick API。
user-flow-debug 还会在支持 role profile 的聊天页面中校验每个 step 的显示说话人是否来自该 step 的 owner role;默认 assistant/colleague 只应出现在开场或无 step 消息中。
Every packaged subagent supports a Goal-Driven Loop Mode: the user supplies a goal, loop cadence, stop condition, and policy boundaries; the agent iterates with explicit loopState, per-iteration evidence, blockers, and next actions. Loop mode does not bypass confirmation gates for protected branch pushes, source mutation, publish, rollback, deployment, internal tick APIs, or production-impacting actions.
Loop mode is a product contract, not only prompt text. Each manifests/agents/*.json file declares a loopContract with inputs, state fields, cadence modes, stop policies, and iteration evidence. Runtime-specific execution lives under runtimeAdapters, with Codex /goal as the first release-grade adapter.
Every loop-capable subagent must establish a loop goal window before starting or resuming work. The window can be stated in chat or persisted in loopState, but it must make the long-running objective explicit enough to prevent an open-ended loop.
finalGoal: the end-state the loop is trying to reach.phaseGoals: staged goals for the current release, validation, or evolution phase.acceptanceCriteria: evidence-backed criteria required before completion can be claimed.targetPlan: the proposed loop plan, including final target, phase targets, per-phase acceptance criteria, coverage rows, evidence sources, blocker policy, repair policy, report cadence, and final decision vocabulary.targetPlanConfirmation: the user's explicit confirmation or requested edits before loop execution.reportCadence: when the agent reports progress, blockers, and next actions.finalDecision: the explicit terminal decision, such asDONE,BLOCKED,NO-GO, orNOT_RELEASE_READY.
Agents may infer missing target details from context or product-native discovery, but the inferred plan is not executable by itself. Before starting or resuming any loop, the agent must present the provided or inferred target plan as a confirmation proposal and require explicit user confirmation before entering the loop. If the plan is not confirmed, the agent stops as BLOCKED: pending loop target plan confirmation and does not run loop actions. Agents may iterate through phase goals only after confirmation, and they must not claim loop completion until the final goal and acceptance criteria are proven with evidence.
For release, release-readiness, GA, public-beta, production-grade, or long-running product lifecycle goals, the user should only need to state the target outcome. The selected subagent must turn that goal into a release coverage matrix, iteration plan, evidence map, blocker policy, repair policy, release decision, and per-phase decision chain before it starts or resumes the loop.
The matrix keeps the loop tied to product behavior rather than process keepalive:
coverageMatrix: product capabilities, scenarios, connected projects or systems, required evidence, current status, blocker, and next repair action.evidenceMap: product-native APIs, UI paths, SCM, CI/CD, runtime logs, artifacts, approvals, rollback checks, or release decisions backing each row.repairPolicy: repeated blockers move from rerun into diagnosis, productized repair, verification, escalation, orBLOCKED/NO-GO.decisionChain: every phase report prints the 阶段决策链: evidence, rule, options, decision, rationale, and next action.
Protocol is generic, and execution is generic through a project profile. A target project supplies agent-octopus-project-profile/v1 with its health endpoints, real commands, real SCM/CI/CD/LLM boundaries, release evidence endpoint, release decision endpoint, coverage rows, and confirmed targetPlan. The platform runner consumes that profile without hard-coding project APIs:
npm run release:runner -- --profile project-profiles/examples/evopilot.ga.jsonThe runner enforces targetPlanConfirmation before executing, writes compact loop-state.json, externalizes full iteration evidence under artifacts/, records summary events in loop.jsonl, and prints per-phase decision chains. When the loop exits, it writes final-report.md and final-report.json with a final target summary, every iteration's loop plan/target summary, the confirmed target plan, the latest coverage matrix, the final GA/release decision, blockers, and artifact paths. Project-specific behavior belongs in the profile or an adapter step; platform core owns loop execution, evidence discipline, state compaction, final reporting, and release decision governance.
When a local environment has no real customer production projects, Octopus AgentOps provides a shared Production Representative Sandbox under sandbox/production-representative/. It creates representative projects that can be registered into a target product and used as release coverage matrix rows.
The sandbox is reusable across all packaged subagents. Its source contract is sandbox/production-representative/manifest.json; generated repositories are written under data/production-representative-sandbox/ and are intentionally ignored by git.
npm run sandbox:verify
python3 sandbox/production-representative/scripts/create-projects.py --force
python3 sandbox/production-representative/scripts/verify-sandbox.py --generatedThe included project set covers backend API, Dashboard UI, MCP/tool contract, evidence data pipeline, and quality-gate failure/repair behavior. These projects count as release evidence only after they use real Git repositories, real validation commands, real target-product registration, real SCM, real CI/CD, real LLM/runtime boundaries, and persisted product-native evidence. Template-only, mock-only, fixture-only, smoke-only, or chat-only projects do not count.
For EvoPilot, use sandbox/production-representative/profiles/evopilot.release-matrix.json and register-target.py to register the generated projects through /api/v1/projects. If EvoPilot, Jenkins, GitLab, or GLM cannot verify the representative projects through real product boundaries, the release loop must mark those rows BLOCKED or NO-GO.
All packaged subagents share the same release rule: when a task is product-grade, production-like, release-candidate, GA, or release-readiness work, do not use mock, fake, stub, simulator, fixture-only, demo-only, smoke-only, or chat-only evidence as production release evidence.
- Smoke checks may prove connectivity only; they are not product-grade release validation.
- If a required runtime, model, SCM, CI/CD, data, approval, rollback, observability, or product API boundary is missing or replaced by a non-production substitute, the decision must be
NO-GO,BLOCKED, or not release-ready. - Release claims require real processes, real APIs, real credentials, real SCM, real CI/CD, real product data paths, and product-native release evidence where available.
Octopus AgentOps is Codex-first, not Codex-only. In Codex projects, /goal acts as the outer objective runtime while the installed platform agent remains the inner domain loop protocol.
Codex /goal
-> keeps the outer objective moving
-> resumes or stops at the session/runtime level
Octopus loopContract
-> defines loopCadence, goalWindow, stopPolicies, loopState, evidence, and gates
-> preserves domain rules such as MCP boundary, Git safety, or product-grade blockers
Render a Codex goal plan before starting a long-running loop:
npm run agents:goal-plan -- \
--agent mcp-e2e-governor \
--project-id your-project \
"Prove the MCP onboarding journey"Check project install drift and Codex goal feature availability:
npm run agents:codex-status -- --project-root /path/to/your/projectSee integrations/codex/goal-adapter.md and examples/codex-goal/ for runnable patterns.
The extracted release lifecycle subagent has been extracted into ProofOps. Use ProofOps for demo-to-GA maturity targets, architecture readiness, release coverage matrices, product-native GO/NO-GO decisions, and production lifecycle evidence loops. Octopus AgentOps now keeps reusable engineering agents, packaging, manifests, generated distributions, and install drift governance.
mcp-e2e-governor governs MCP product journeys from code-first discovery to prompt confirmation, execution, assertions, diagnosis, and self-evolution proposal gating.
product-evolution-lab runs external product-evolution pressure through configured product profiles. It does not assume a specific project layout. Configure product-specific readiness, E2E, improvement, and review behavior through product-owned commands or profile data; Octopus AgentOps stores status and run evidence under data/product-evolution-lab/.
readiness
-> 清理旧固定时长脚本 / stale heartbeat / 历史运行数据 / 过期报告 / 临时日志
-> 非 mock 预检
-> 用户指定时长的长稳运行
-> 每 30 分钟汇报
-> 产品缺口阻断与补强
-> release coverage matrix
-> 阶段决策链
-> release evidence
-> GO / CONDITIONAL-GO / NO-GO
Its production rule is strict and inherits the platform-wide release rule: product-grade validation cannot rely on mock/fake/stub/simulator/fixture-only/demo-only/smoke-only/chat-only evidence, chat-agent manual repair is not counted as production runtime capability, and validation duration must come from the user or discovered plan rather than hard-coded 2h/3h/24h scripts.
Codex agents install into the target project's .codex/agents/ directory and do not replace .codex/skills/. Each project can opt in and update explicitly.
scripts/octopus-control.py provides the current control-plane CLI:
npm run agents:list
npm run plugins:list
npm run agents:search -- mcp
npm run agents:goal-plan -- --agent mcp-e2e-governor --project-id your-project "Prove the MCP onboarding journey"
npm run agents:install -- --plugin mcp-e2e-governance --project-root /path/to/your/project
npm run agents:codex-status -- --project-root /path/to/your/project
npm run sandbox:verifyIt reads agent and plugin metadata from manifest/catalog files, then supports search, plugin-scoped installs, proposal listing, and .codex/agents/ drift checks.
| Without Octopus AgentOps | With Octopus AgentOps |
|---|---|
| Agents are copied manually across projects and drift silently. | Agents are installed from versioned plugin/catalog definitions and checked for drift. |
| Agent instructions are edited without a contract. | Each agent has a manifest for inputs, outputs, evidence, gates, dangerous actions, and native capabilities. |
| Codex distributions are maintained by hand. | Codex TOML is generated from canonical Markdown sources and manifests. |
| Local diagnostics depend on OS-specific commands. | The sandbox provides portable HTTP, port, artifact, and Git checks. |
| Git sync, commit, push, PR/MR, and CI actions blur into one risky operation. | scm-sync-governor makes each step explicit and confirmation-bound. |
| User-flow validation bypasses the real UI. | user-flow-debug requires real Dashboard operation and screenshot evidence. |
| Long-running loops prove service health but miss core release scenarios. | Release coverage matrix loop requires scenario rows, evidence mapping, repair policy, and per-phase decision chains. |
| Installed-project edits flow back without review. | Offline proposals are generated and accepted only by the Octopus AgentOps maintainer. |
octopus-agentops
├── agents/ Canonical Claude Code Markdown agents
├── bin/octopus-sandbox Portable diagnostics entrypoint
├── integrations/
│ ├── claude-code/README.md Claude Code integration
│ └── codex/
│ ├── README.md Codex integration
│ └── agents/ Generated Codex TOML agents
├── catalog/ Generated agent/plugin catalogs
├── manifests/agents/ Agent product contracts
├── plugins/ Plugin product contracts
├── sandbox/octopus_sandbox.py Portable diagnostics implementation
├── schemas/ manifest / run / proposal schema
├── scripts/generate-catalog.py Catalog generator
├── scripts/generate-distributions.py Codex distribution generator
├── scripts/install.sh Install/update script
├── scripts/octopus-control.py Control-plane CLI
├── scripts/validate-toolkit.py Contract validator
└── AGENT-LIST.md Agent catalog summary
Sandbox commands:
doctor Inspect OS, Python, and common tool availability
git-inspect Collect standard Git status, remotes, branch, and recent commits
git-commit-check Run pre-commit inspection and flag generated/output candidates
git-conflicts List current Git conflict state
health-check Check HTTP URLs without relying on curl
port-check Check TCP ports without relying on lsof/netstat/ss
find-artifacts Inspect output/runs/<runId>/ artifacts and final/manifest.json
| Not | Meaning |
|---|---|
| Not a general agent framework | It does not own the model runtime or prompt-execution engine. |
| Not an SCM host replacement | It governs local Git collaboration workflows; GitHub, GitLab, or another SCM host remains the system of record. |
| Not a full browser testing framework | user-flow-debug is an evidence-driven debugging workflow, not a replacement for a full test suite. |
| Not a script dump | Reusable diagnostics belong in sandbox/ and are distributed through install/update flows. |
Clone or enter the Octopus AgentOps checkout:
cd /Users/wangyejing/github/octopus-agentopsSet the platform path. AGENT_OCTOPUS_TOOLKIT_HOME remains supported as a compatibility alias for existing installed agents.
export OCTOPUS_AGENTOPS_HOME=/Users/wangyejing/github/octopus-agentops
export AGENT_OCTOPUS_TOOLKIT_HOME="$OCTOPUS_AGENTOPS_HOME"Install into Claude Code:
./scripts/install.sh --tool claude-codeInstall into the current project's Codex agents:
cd /path/to/your/project
/Users/wangyejing/github/octopus-agentops/scripts/install.sh --tool codexPreview install output without writing files:
/Users/wangyejing/github/octopus-agentops/scripts/install.sh --tool codex --dry-runInstall or update one agent:
/Users/wangyejing/github/octopus-agentops/scripts/install.sh --tool codex --agent mcp-e2e-governor --updateAuto-install into detected tools:
/Users/wangyejing/github/octopus-agentops/scripts/install.shValidate the sandbox:
/Users/wangyejing/github/octopus-agentops/bin/octopus-sandbox doctorValidate product contracts:
cd /Users/wangyejing/github/octopus-agentops
npm run validateRun the public-beta release gate:
npm run release:checkReport stable GA blockers:
npm run release:check:gaUse the control plane:
npm run agents:list
npm run plugins:list
npm run agents:search -- production
npm run agents:codex-status -- --project-root /path/to/your/projectSCM 同步:
使用 scm-sync-governor,把本地 dev 和 origin/dev 同步,先检查状态,不要直接 push。
用户流调试:
使用 user-flow-debug,入口 UI 为 index.html,跑 deployed 环境的目标场景,新 run,real JDBC,截图到 /tmp/user-flow,策略 diagnose-only。
通用产品进化实验:
使用 product-evolution-lab,目标是验证当前产品是否能完成从授权材料到产品工作流、证据收集、改进建议和人工 review 的闭环。产品根目录为 /path/to/product,E2E 命令由 PRODUCT_EVOLUTION_LAB_E2E_COMMAND 提供,循环间隔 15 分钟,遇到产品级 blocker 立即停止。
可配置时长常驻进化实验:
使用 product-evolution-lab,在 Codex Desktop 中启动用户指定时长或 always-on 运行。请使用产品 profile 中的 readiness、E2E、improvement 和 review 命令,每 15 分钟反馈一次状态;同时维护 current-status.md、latest-run 和 logs/continuous.log。
通用产品生产生命周期:
time-driven 本地调试示例:
使用 user-flow-debug,入口 UI 为 domain-chat.html,跑 local-dev Dashboard 用户流。请使用独立 output root,启用服务端 scheduler 或测试时间窗口,不要通过 UI 暴露 tick。截图到 /tmp/user-flow,策略 diagnose-only。
最终报告会包含入口 UI、实际打开 URL、runId、截图目录、final 产物、runtime flow type、output 隔离策略,以及每个 step 的输入模式、显示角色、artifact 数量和 pass/fail。
Install/update is copy-based. After octopus-agentops is updated, refresh this checkout first and then rerun the installer from each target location.
If this is a Git checkout:
cd /Users/wangyejing/github/octopus-agentops
git pullUpdate Claude Code agents:
/Users/wangyejing/github/octopus-agentops/scripts/install.sh --tool claude-code --updateUpdate Codex agents in a project:
cd /path/to/your/project
/Users/wangyejing/github/octopus-agentops/scripts/install.sh --tool codex --updateCodex agents are project-scoped. Every project that has installed .codex/agents/ should be updated from that project root.
Installed projects may edit local agents, but those edits do not flow back automatically. Backflow uses offline proposal packages so business projects do not need repository permissions and unreviewed changes cannot enter the source repository.
Flow:
installed project edit
-> propose-changes.py creates an offline proposal
-> Octopus AgentOps maintainer reviews diff
-> apply-proposal.py --accept writes accepted files into the platform repository
-> maintainer commits and pushes Octopus AgentOps
Create a proposal from a project with installed Codex agents:
cd /path/to/your/project
/Users/wangyejing/github/octopus-agentops/scripts/propose-changes.py \
--tool codex \
--title "improve scm-sync-governor for project X"This creates:
.agent-octopus/proposals/proposal-YYYYMMDD-HHMMSS/
├── manifest.json
├── README.md
├── diffs/
└── files/
The target project only needs to hand this directory to the Octopus AgentOps maintainer; it does not need GitLab/GitHub push permissions.
Review from the source repository:
/Users/wangyejing/github/octopus-agentops/scripts/apply-proposal.py \
/path/to/proposal-YYYYMMDD-HHMMSSWrite into the source repository only after acceptance:
/Users/wangyejing/github/octopus-agentops/scripts/apply-proposal.py \
/path/to/proposal-YYYYMMDD-HHMMSS \
--acceptAccept one file only:
/Users/wangyejing/github/octopus-agentops/scripts/apply-proposal.py \
/path/to/proposal-YYYYMMDD-HHMMSS \
--file integrations/codex/agents/scm-sync-governor.toml \
--acceptAfter acceptance, the maintainer reviews git diff, runs validation, commits, pushes, and lets target projects consume the update through install.sh --update.
Run the full product contract check:
npm run checkRegenerate distributions and catalogs:
npm run generateRun deterministic agent eval:
npm run evalRun the release-readiness gate:
npm run release:check
npm run release:check -- --jsonCheck the installer:
bash -n scripts/install.shCheck the sandbox:
python3 -m py_compile sandbox/octopus_sandbox.py
bin/octopus-sandbox --help
bin/octopus-sandbox doctorCheck proposal scripts:
python3 -m py_compile scripts/propose-changes.py scripts/apply-proposal.pyWhen adding or changing an agent, keep these files aligned:
agents/<agent>.md
integrations/codex/agents/<agent>.toml
manifests/agents/<agent>.json
plugins/<plugin>/plugin.json
catalog/agents.json
catalog/plugins.json
AGENT-LIST.md
README.md
Then run:
npm run validate
npm run generate -- --check
npm run eval
npm run release:check
/Users/wangyejing/github/octopus-agentops/scripts/install.sh --tool codex --dry-runWhen adding reusable diagnostics, put them in sandbox/octopus_sandbox.py, then update the related agent instructions, generated Codex TOML, and manifest. Do not duplicate diagnostic scripts inside target projects.
MIT. See LICENSE.