Troubleshooting

Common issues and quick fixes for AgentOps.

---

Hooks aren't running

Hooks are runtime-specific: Claude uses ~/.claude/settings.json, while Codex v0.115.0+ uses ~/.codex/hooks.json installed by the native plugin path.

Diagnosis:

Bash

ao doctor

Look for the "Hooks installed" check. If it shows ✗, hooks are not configured.

Fixes:

1. Verify hooks are configured in ~/.claude/settings.json:

   JSON

   {
     "hooks": {
       "PostToolUse": [...],
       "UserPromptSubmit": [...]
     }
   }
   

   The ao doctor check counts all hooks across event types. If it reports "no hooks configured", hooks are missing from settings.json entirely.

2. Check that hooks are not disabled via environment variable:

   Bash

   echo $AGENTOPS_HOOKS_DISABLED
   

   If set to 1, all hooks are bypassed. Unset it:
   Bash

   unset AGENTOPS_HOOKS_DISABLED
   

3. Verify hook scripts exist and are executable:

   Bash

   ls -la hooks/
   

   All .sh files in the hooks directory should have execute permissions.

4. For Codex native-plugin installs, verify the native hooks file exists:

   Bash

   cat ~/.codex/hooks.json | jq '.hooks'
   

   If it is missing, reinstall with:
   Bash

   curl -fsSL https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install-codex.sh | bash
   

---

Skills not showing up

Skills must be installed as a Claude Code plugin.

Diagnosis:

Bash

claude plugin list
claude plugin marketplace list
ao doctor

The ao doctor "Plugin" check scans the skills/ directory for subdirectories containing a SKILL.md file. If it reports "no skills found" or "skills directory not found", the plugin is not installed correctly.

Fixes:

1. Install or reinstall the AgentOps skills:

   Bash

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

2. Update existing skills:

   Bash

   claude plugin marketplace update agentops-marketplace
   claude plugin update agentops
   

3. If updates seem stale, clear the cache and reinstall:

   Bash

   # The skills cache lives here:
   ls ~/.claude/plugins/marketplaces/agentops-marketplace/
   # Pull latest directly if marketplace update lags:
   cd ~/.claude/plugins/marketplaces/agentops-marketplace/ && git pull
   

4. Verify the plugin loads:

   Bash

   claude --plugin ./
   

5. If skills load but automation hooks are missing, install hooks from repo root:

   Bash

   ao init --hooks
   ao hooks test
   

---

bd says a column is missing or RPI falls back to tasklist mode

If bd ready --json fails with an error such as:

Text Only

column "crystallizes" could not be found in any table in scope

you likely have a beads CLI / beads DB schema mismatch.

Diagnosis:

Bash

bd version
bd migrate --inspect --json

If bd migrate --inspect --json shows the database state is newer than the installed bd version, the local CLI is too old for the repo's tracker data.

Fixes:

1. Upgrade beads to the matching or newer version:
   Bash

   brew upgrade beads
   

2. Re-run tracker probes:
   Bash

   bd ready --json
   bd list --type epic --status open --json
   

3. If you cannot repair beads immediately, Codex phased RPI now degrades honestly to tasklist mode instead of silently assuming beads is healthy. That fallback is for continuity, not a substitute for repairing the tracker.

For Codex, use curl -fsSL https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install-codex.sh | bash. The installer enables plugins and suppresses the unstable-plugins warning in ~/.codex/config.toml. On Linux, install system bubblewrap as well so Codex does not warn that it is using the vendored fallback. For OpenCode, use curl -fsSL https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install-opencode.sh | bash. For other agents, use the platform-specific scripts in scripts/.

Bash

sudo apt-get install -y bubblewrap

Symptoms:

• Running npx update installs an unrelated npm package and does not update skills.
• bash <(curl -fsSL https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install.sh) reports failed skills without actionable detail.

Fixes:

1. Use the correct updater command:
   Bash

   bash <(curl -fsSL https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install.sh)
   

2. If specific skills still fail, reinstall each failed skill directly:
   Bash

   bash <(curl -fsSL https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install.sh)
   

3. Re-run update to verify a clean state:
   Bash

   bash <(curl -fsSL https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install.sh)
   

If reinstalling one-by-one works but bulk update previously failed, the local skills lock state was stale; per-skill reinstall refreshes it.

---

Skills show up twice in Codex

This usually means Codex is seeing AgentOps skills from more than one location. For native-plugin installs, the active source of truth is the plugin cache under ~/.codex/plugins/cache/.../skills-codex. Stale copies in ~/.codex/skills or ~/.agents/skills can still create duplicates if your local Codex build scans more than one of those locations.

Diagnosis:

Bash

ao doctor

If the "Plugin" check warns about duplicate installs, inspect the active homes:

Bash

find ~/.codex/plugins/cache/agentops-marketplace/agentops/local/skills-codex -maxdepth 1 -mindepth 1 -type d | sort
find ~/.codex/skills -maxdepth 1 -mindepth 1 -type d | sort
find ~/.agents/skills -maxdepth 1 -mindepth 1 -type d | sort

Fix:

1. Reinstall so the native plugin cache is refreshed and stale raw mirrors are archived:
   Bash

   curl -fsSL https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install-codex.sh | bash
   

2. If duplicates persist, archive the stale ~/.agents/skills copy:
   Bash

   mv ~/.agents/skills ~/.agents/skills.backup.$(date +%Y%m%d-%H%M%S)
   

3. If duplicates still persist, archive the stale ~/.codex/skills copy:
   Bash

   mv ~/.codex/skills ~/.codex/skills.backup.$(date +%Y%m%d-%H%M%S)
   

4. If duplicates still persist after that, remove the compatibility plugin cache:
   Bash

   rm -rf ~/.codex/plugins/cache/agentops-marketplace/agentops/local
   

5. Validate the runtime in a fresh session:
   Bash

   bash scripts/validate-codex-cli-skills.sh
   

6. Restart Codex so interactive sessions reload the current skill list.
7. Re-run ao doctor to confirm the warning is gone.

Keep the native plugin cache as the source of truth for native-plugin installs. Only restore ~/.agents/skills or ~/.codex/skills if you intentionally want raw-skill mode for a specific Codex build.

---

Push blocked by vibe gate

The push gate hook blocks git push unless a recent /vibe check has passed. This enforces quality validation before code reaches the remote.

Why it exists: The vibe gate prevents untested or unreviewed code from being pushed. It is part of the AgentOps quality enforcement workflow.

Quick bypass (use sparingly):

Bash

AGENTOPS_HOOKS_DISABLED=1 git push

Proper resolution:

1. Run /vibe on your changes:

   Text Only

   /vibe
   

2. Address any findings until you get a PASS verdict.

3. Push normally:

   Bash

   git push
   

---

Worker tried to commit

This is expected behavior in the lead-only commit pattern used by /crank and /swarm.

How it works:

• Workers write files but NEVER run git add, git commit, or git push.
• The team lead validates all worker output, then commits once per wave.
• This prevents merge conflicts when multiple workers run in parallel.

If a worker accidentally committed:

1. The lead should review the commit before pushing.
2. Amend or squash if needed to maintain clean history.

For workers: If you are a worker agent, your only job is to write files. The lead handles all git operations.

---

Phantom command error

If you see errors for commands like bd mol, gt convoy, or bd cook, these are planned future features that do not exist yet.

How to identify: Look for FUTURE markers in skill documentation. These indicate commands or features that are designed but not yet implemented.

What to do:

• Do not retry the command. It will not work.
• Check the skill's SKILL.md for current supported commands.
• Use bd --help or gt --help to see available subcommands.

---

ao doctor shows failures

ao doctor runs 9 health checks. Here is how to fix each one.

Required checks (failures make the result UNHEALTHY)

Check	What it verifies	How to fix
ao CLI	The ao binary is running and reports its version.	Reinstall via Homebrew, or build from cli/ (see cli/README.md).
Knowledge Base	The .agents/ao/ directory exists in the current working directory.	Run ao init from your project root, or verify you are in the correct directory.
Plugin	The skills/ directory exists and contains at least one subdirectory with a SKILL.md file.	See Skills not showing up above.

Optional checks (warnings, result stays HEALTHY)

Check	What it verifies	How to fix
CLI Dependencies	gt and bd are on your PATH (nice-to-have for multi-repo ops + beads issue tracking).	Install missing tools (e.g., brew install gastown, brew install beads).
Hook Coverage	Claude Code: hooks configured via ~/.claude/settings.json. Codex v0.115.0+: native hooks configured via ~/.codex/hooks.json; older Codex versions fall back to ao codex start/stop.	Claude: ao hooks install. Codex: scripts/install-codex-plugin.sh or curl -fsSL https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install-codex.sh | bash. See docs/contracts/hook-runtime-contract.md.
Knowledge Freshness	At least one recent session exists under .agents/ao/sessions/.	After a session, run ao forge transcript <path> to ingest it.
Search Index	A non-empty .agents/ao/index.jsonl exists for faster repo-local searches.	Run ao store rebuild.
Flywheel Health	At least one learning exists under .agents/ao/learnings/ (or legacy .agents/learnings/).	Run /retro or /forge to extract learnings; empty is normal early on.
Codex CLI	The codex binary is on your PATH (optional, used for --mixed validation modes).	Install Codex CLI and ensure it is on PATH.

Reading the output

Text Only

ao doctor
─────────
 ✓ ao CLI              vX.Y.Z
 ! Hook Coverage       No hooks found — run 'ao hooks install'
 ✓ Knowledge Base      .agents/ao initialized
 ✓ Plugin              skills found
 ! Codex CLI           not found (optional — needed for --mixed council)

 7/9 checks passed, 2 warnings

• ✓ = pass
• ! = warning (optional component missing or degraded)
• ✗ = failure (required component missing or broken)

Use ao doctor --json for machine-readable output.

---

Getting help

• New to AgentOps? Run /quickstart for an interactive onboarding walkthrough.
• Run diagnostics: ao doctor checks your installation health.
• Report issues: github.com/boshu2/agentops/issues
• Full workflow guide: Run /using-agentops for the complete RPI workflow reference.