Skip to content

troubleshooting.md

Latest commit

 

History

History
373 lines (270 loc) · 12.8 KB

troubleshooting.md

File metadata and controls

373 lines (270 loc) · 12.8 KB

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:

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:

    {
  "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:

    echo $AGENTOPS_HOOKS_DISABLED

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

    unset AGENTOPS_HOOKS_DISABLED

  3. Verify hook scripts exist and are executable:

    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:

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

    If it is missing, reinstall with:

    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:

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:

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

  2. Update existing skills:

    claude plugin marketplace update agentops-marketplace
claude plugin update agentops

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

    # 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:

    claude --plugin ./

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

    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:

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

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

Diagnosis:

bd version
bd upgrade status --json
bd status --json
bd migrate --inspect

If the JSON version/status probes or the human-readable migration inspection show 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: 
    brew upgrade beads
  2. Re-run tracker probes: 
    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/.

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 <(curl -fsSL https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install.sh)
  2. If specific skills still fail, reinstall each failed skill directly: 
    bash <(curl -fsSL https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install.sh)
  3. Re-run update to verify a clean state: 
    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:

ao doctor

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

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: 
    curl -fsSL https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install-codex.sh | bash
  2. If duplicates persist, archive the stale ~/.agents/skills copy: 
    mv ~/.agents/skills ~/.agents/skills.backup.$(date +%Y%m%d-%H%M%S)
  3. If duplicates still persist, archive the stale ~/.codex/skills copy: 
    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: 
    rm -rf ~/.codex/plugins/cache/agentops-marketplace/agentops/local
  5. Validate the runtime in a fresh session: 
    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):

AGENTOPS_HOOKS_DISABLED=1 git push

Proper resolution:

  1. Run /vibe on your changes:

    /vibe

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

  3. Push normally:

    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
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

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.

Pre-mortem gate blocks /crank

The pre-mortem gate denies ambiguous state by default (as of 2.37.2). If /crank exits immediately with a pre-mortem error, it is telling you there is no pre-mortem artifact or the artifact is stale for the current epic.

Fixes:

  1. Run /pre-mortem against the epic before invoking /crank.
  2. For exploratory runs where a pre-mortem is not worth the cost: 
    AGENTOPS_PREMORTEM_MODE=advisory /crank ...
    This downgrades the gate to a warning.

go-test-precommit blocks commits

The go-test-precommit.sh hook runs relevant Go tests before tool calls that would mutate Go code. If it fails, look for the test output above the block message. Common causes:

  • Tests that depend on network (go test -short typically skips these).
  • A package import that fails to compile — fix compilation first, tests second.

Bypass (not recommended): set AGENTOPS_SKIP_GO_TEST_PRECOMMIT=1 for a single session. Prefer fixing the underlying test.

Context window compacted and lost work

If a session compacts and drops critical context, check whether precompact-snapshot.sh ran. Artifacts land in .agents/compact/<timestamp>/:

ls -lt .agents/compact/ | head

Restore needed state with ao inject --from .agents/compact/<timestamp>/ or manually re-seed the session with MEMORY.md.

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.