Uninstall Spec Kitty
Who is this for (1)
- Stakeholder Persona: Project Owner — Written for the Project Owner reader.
Remove the spec-kitty CLI and, optionally, the project files it generated. This page also covers rollback from a failed upgrade.
Uninstall the CLI
Pick the section that matches how you installed.
pipx
pipx uninstall spec-kitty-cliTo remove the pipx-managed Python interpreter and venv entirely:
pipx uninstall spec-kitty-clirm -rf ~/.local/share/pipx/venvs/spec-kitty-cli # safety: pipx should already handle thisuv tool
uv tool uninstall spec-kitty-cliTo clear cached wheels and tool data:
uv cache cleanpip in a venv
# Inside the activated venv:pip uninstall spec-kitty-cliIf the venv only existed for spec-kitty, remove the whole venv:
deactivaterm -rf .venvVerify removal
spec-kitty --version# command not foundIf spec-kitty is still on your PATH after uninstall, you likely have a second installation. which -a spec-kitty (POSIX) or where.exe spec-kitty (Windows) shows every match.
Remove generated project files
A project initialized with spec-kitty init contains generated agent and scaffold directories, plus mission history. Decide carefully what to remove.
Safe to remove (generated, no user data)
rm -rf .kittify/ # project scaffold and configrm -rf .claude/ # agent command directory (one per configured agent)rm -rf .codex/ # legacy Codex root (only present on installs that predate Agent Skills)rm -rf .gemini/rm -rf .agents/skills/ # codex/vibe skill packages# ... and any other configured agent directory listed in .kittify/config.yamlSpec Kitty also adds entries to your .gitignore and .claudeignore. Remove the # spec-kitty block if you want a clean ignore file.
Caution: contains your work
kitty-specs/ # mission specs, plans, status events — YOUR workarchitecture/ # ADRs and architectural docsdocs/ # documentation you authoredDo not blindly delete kitty-specs/ — it holds every mission spec, work-package definition, status event log, and merge artifact. If you genuinely want to remove Spec Kitty from a repo but keep history, archive instead of delete:
tar czf kitty-specs-archive-$(date +%Y%m%d).tgz kitty-specs/git rm -r kitty-specs/git commit -m "chore: archive spec-kitty mission history".worktrees/ cleanup
If any execution lanes are still on disk, remove them before deleting the rest:
spec-kitty agent worktrees prune # safe cleanup of finished lanes# fallback for stuck worktrees:git worktree listgit worktree remove .worktrees/<name>Rollback from a failed upgrade
If a CLI upgrade or project migration left you in a bad state, roll back in two steps.
1. Reinstall the previous CLI version
# pipxpipx install --force spec-kitty-cli==<previous-version>
# uv tooluv tool install --force spec-kitty-cli==<previous-version>
# pip in venvpip install --force-reinstall 'spec-kitty-cli==<previous-version>'Verify:
spec-kitty --version2. Restore project files
Most spec-kitty-managed paths are version-controlled, so git is your rollback tool:
cd /path/to/projectgit restore .kittify/ .claude/ .agents/skills/ .gemini/ # whichever changedgit status # confirm cleanIf the failed upgrade was committed already:
git revert <upgrade-commit-sha>kitty-specs/ artifacts are version-controlled and should be left alone during rollback — they belong to your project, not to the spec-kitty install.
Reinstall later
Uninstalling does not lock you out. To reinstall:
pipx install --pip-args=--pre spec-kitty-clicd /path/to/projectspec-kitty init . --ai claude # idempotent; re-creates agent dirs only for configured agentsIf kitty-specs/ is still in the repo, your mission history reappears automatically.
Troubleshooting
spec-kitty is still on PATH after uninstall — A second install exists elsewhere. which -a spec-kitty lists every match.
.kittify/config.yaml still references uninstalled agents — Edit via spec-kitty agent config remove <key> before uninstalling, or simply delete .kittify/ when removing the project.
I deleted kitty-specs/ by mistake — git restore kitty-specs/ if it was version-controlled. If not, check .git/objects or your backups; spec-kitty does not keep a separate copy.