AgentKrew

Troubleshooting

Start with doctor

Almost every AgentKrew problem begins and ends with:

bash
npx @agentkrew/cli doctor

It checks the runtime, the manifest, every installed artifact, broken references, and AGENTKREW.md, printing one line per check:

text
✓ Claude detected (2.1.128)
✗ Runtime configuration invalid
  .claude/agents/tech-lead.md: file not found
...
AgentKrew found 1 problem.

Exit codes: 0 healthy, 1 problems found — safe for CI. Fix what it names, run it again, and only then dig deeper.

Error reference

You see What it means Fix
no .agentkrew.json in <dir> (run agentkrew init first) Not an installed project (or you ran from a subdirectory). cd to the project root and agentkrew init.
✗ AgentKrew manifest missing Same as above, reported by doctor. Run agentkrew init.
✗ AgentKrew manifest invalid … invalid JSON .agentkrew.json is corrupted. Restore it from Git, or remove it and re-run init.
✗ Claude not installed / claude --version did not succeed The manifest's runtime is not on your PATH. Install the runtime, or reinstall with a runtime you have (init --runtime … after agentkrew remove).
agentkrew init: already installed in <dir> There is nothing to do; init will not modify an existing installation. Use agentkrew update to refresh, or agentkrew remove first for a clean reinstall.
AGENTKREW_LICENSE_KEY environment variable is required for license-based kit download You chose the default license kit source without a key. Export AGENTKREW_LICENSE_KEY, or use --kit-source local --kit-path <dir> from a source checkout.
unknown kit "bogus" (available: cross-kit, engineer, marketing) The --kit name does not exist. Use one of the listed names.
--kit-path is required when --kit-source=local Local mode needs the kit directory. Add --kit-path ./kits (or your checkout's kits/ directory).
unknown kit "engineer" (available: none): kit sources are not on disk during update The npm package does not bundle kit sources and none are on disk. Export AGENTKREW_LICENSE_KEY (kits download from the registry), or set AGENTKREW_KIT_ROOT — see updates.
agentkrew update: refusing to overwrite user-owned files A safety net tripped: the renderer would have written outside generated paths. Do not proceed manually; this is a bug worth reporting — your files are untouched.
✗ Runtime configuration invalid / <file>: file not found A generated file the manifest expects was deleted or moved. Restore it (Git) or re-render with agentkrew update.
Installed version X is newer than Y — nothing to do. The CLI you ran is older than your installation. Run the newer CLI: npx @agentkrew/cli@latest update.
AgentKrew is already up to date (X) Nothing to do. —

Symptoms without an error message

/create-feature (or any command) is not found in my runtime

  1. agentkrew doctor — did init run in this project root?
  2. Check the rendered files exist (.claude/commands/, .opencode/commands/, or .agents/skills/cmd-* on Codex).
  3. Restart the runtime session — commands are discovered at startup.
  4. Confirm the runtime matches the manifest (doctor shows which runtime it validated).

Agents exist but nothing delegates to them

  • The routing happens through each agent's description; rephrase the request so it matches one, or invoke the agent explicitly (@tech-lead on Claude Code and OpenCode).
  • Codex: project .codex/ files load only in trusted projects — mark the project trusted if generated agents are invisible (skills under .agents/ are unaffected).

list / info shows nothing, or Unknown kit without options

The published npm package does not bundle kit sources. Add --installed to read your project's installation:

bash
agentkrew list agents --installed
agentkrew info tech-lead --installed

--installed resolves kits exactly like update does: with AGENTKREW_LICENSE_KEY exported they download from the registry automatically, and AGENTKREW_KIT_ROOT works offline.

agentkrew validate reports errors or warnings

  • Errors exit 1; warnings exit 0 unless you pass --strict (use --strict in CI).
  • Findings name the file and the rule (description quality, required sections, prompt size, duplicate responsibility, broken references, circular dependencies).
  • Validate an installed project with --installed, source kits with --kit <name>.

An update failed and I am worried about my files

You did not lose anything: a failed update restores every touched file and the old manifest byte-for-byte, then exits 1. The validation issues printed above the rollback are what to fix — re-run agentkrew doctor to confirm the project is back in its pre-update state.

Getting help

Include in a report:

bash
agentkrew --version
agentkrew doctor          # full output
agentkrew validate --installed --strict   # if relevant

plus your runtime and its version (claude --version, codex --version, opencode --version) and the exact command you ran.