Install Spec Kitty — macOS, Linux, and Windows Installation Guide
Who is this for (1)
- Stakeholder Persona: Project Owner — Written for the Project Owner reader.
Installation Guide
Spec Kitty is inspired by GitHub’s Spec Kit. Installation commands below target the spec-kitty distribution while crediting the original project.
📖 Looking for the complete workflow? See the README: Getting Started guide for the full lifecycle from CLI installation through feature development and merging.

Stylized splash — decorative only. Platform install paths and CLI steps are in the text below.
Prerequisites
- Linux/macOS (or Windows; PowerShell scripts now supported without WSL)
- AI coding agent: Claude Code, GitHub Copilot, or Gemini CLI
- Python 3.11+
- Git
- pipx for the recommended CLI install path
- Optional: uv if your team standardizes on uv-managed tools
Installation
Install Spec Kitty CLI
From PyPI (Recommended)
4.x is in release candidate. Until 4.0.0 is released, a plain install gets the latest stable 3.x release, which has no
consolidatecommand. The pre-release flag in each install command on this page (--pip-args=--prefor pipx,--prerelease=allowfor uv,--prefor pip) installs the latest 4.x release candidate.
Using pipx (preferred):
pipx install --pip-args=--pre spec-kitty-clipipx installs Spec Kitty as an application in an isolated virtual environment
and places the spec-kitty command on your PATH. This is the safest default on
modern Python installations because many Linux distributions now block direct
system-wide pip install commands with PEP 668
externally-managed-environment errors.
If this is your first pipx install, make sure its binary directory is on your
PATH:
pipx ensurepathThen open a new shell and verify:
spec-kitty --versionUsing uv:
uv tool install --prerelease=allow spec-kitty-cliUsing pip in an activated virtual environment or managed CI Python image:
python -m pip install --pre spec-kitty-cliUse pip when you are already inside a project-specific virtual environment,
CI image, or other Python environment you intentionally manage. Avoid direct
system-wide pip install spec-kitty-cli on distro-managed Python installs.
From GitHub (Latest Development)
Use the GitHub install path when you need the latest unreleased code from
main.
Using pipx (preferred):
pipx install git+https://github.com/spec-kitty/spec-kitty.gitUsing uv:
uv tool install spec-kitty-cli --from git+https://github.com/spec-kitty/spec-kitty.gitUsing pip in an activated virtual environment or managed CI Python image:
python -m pip install git+https://github.com/spec-kitty/spec-kitty.gitInitialize a New Project
After installation, initialize a new project:
If installed with pipx, uv, or an active virtual environment:
spec-kitty init <PROJECT_NAME>One-time usage (without installing):
Using pipx:
pipx run --pip-args=--pre --spec spec-kitty-cli spec-kitty init <PROJECT_NAME>Using uvx:
uvx --prerelease=allow --from spec-kitty-cli spec-kitty init <PROJECT_NAME>uvx runs the executable named after the distribution, and this distribution
ships spec-kitty, so the short form uvx spec-kitty-cli … fails with An executable named 'spec-kitty-cli' is not provided by package 'spec-kitty-cli'.
Add a version to pin one (uvx --from "spec-kitty-cli==4.0.0rc8" spec-kitty …);
without a pin or --prerelease=allow, uvx resolves to the latest stable release.
Add to an Existing Project
To add Spec Kitty to an existing repository, run init from that repository root:
cd /path/to/existing-projectspec-kitty init . --ai claudeWhat this does today:
- Creates the
.kittify/scaffold in the current directory - Adds the selected agent command directories
- Updates ignore files such as
.gitignore/.claudeignore - Leaves your Git history untouched;
initdoes not initialize Git or create commits
Best practices for existing projects:
- Commit or stash your current work before adding Spec Kitty.
- Review
.gitignoreafter init: Spec Kitty ignores only the files it generates in agent folders (the# >>> Spec Kitty agent filesblock), so team files such as.claude/settings.jsonstay committable. - Use
spec-kitty doctor skills --jsonif you want a post-install skill health check. - Start the workflow with
/spec-kitty.specify; mission selection happens there, not duringinit.
Choose AI Agent
You can proactively specify your AI agent during initialization:
spec-kitty init <project_name> --ai claudespec-kitty init <project_name> --ai geminispec-kitty init <project_name> --ai codexspec-kitty init <project_name> --ai claude,codexManaging Agents After Initialization
After running spec-kitty init, you can add or remove agents at any time using the spec-kitty agent config command family.
To manage agents post-init:
- Add agents:
spec-kitty agent config add <agents> - Remove agents:
spec-kitty agent config remove <agents> - Check status:
spec-kitty agent config status
See Managing AI Agents for complete documentation on agent management workflows.
Non-Interactive Setup
For CI or scripts, use the non-interactive mode documented by spec-kitty init --help:
spec-kitty init <project_name> --ai claude --non-interactiveVerification
After initialization, you should see the following commands available in your AI agent:
/spec-kitty.specify- Create specifications/spec-kitty.plan- Generate implementation plans/spec-kitty.research- Record discovery findings inresearch.md(research-type missions can also scaffold their research templates after planning)/spec-kitty.tasks- Break down into actionable tasks
Those four cover the start of a mission. For everything your agent can now run —
including /spec-kitty.implement, /spec-kitty.review, /spec-kitty.accept, and
/spec-kitty.merge — with syntax and prerequisites for each, see the
slash command reference.
Run spec-kitty agent tasks status at any time to see where each work package stands.
Troubleshooting
pip install fails with externally-managed-environment
On Ubuntu 24.04, Debian 12, Fedora, and other modern distributions, Python may
refuse direct system-wide pip install spec-kitty-cli commands because the OS
owns the system Python environment. Install the CLI with pipx instead:
pipx install --pip-args=--pre spec-kitty-clipipx ensurepathIf you must use pip, create and activate a virtual environment first:
python -m venv .venvsource .venv/bin/activatepython -m pip install --pre spec-kitty-cliGit Credential Manager on Linux
If you’re having issues with Git authentication on Linux, you can install Git Credential Manager:
#!/usr/bin/env bashset -eecho "Downloading Git Credential Manager v2.6.1..."wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.debecho "Installing Git Credential Manager..."sudo dpkg -i gcm-linux_amd64.2.6.1.debecho "Configuring Git to use GCM..."git config --global credential.helper managerecho "Cleaning up..."rm gcm-linux_amd64.2.6.1.deb