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.

Prerequisites

Linux/macOS (or Windows; PowerShell scripts now supported without WSL)
AI coding agent (any supported): Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Qwen, opencode, Windsurf, Kilocode, Auggie, Roo, or Amazon Q
uv for package management
Python 3.11+
Git

Installation

Release Tracks

Recommended (main / PyPI 1.x stable): pip install spec-kitty-cli
Forward track (2.x): GitHub releases only (v2.*.*), install from source/release artifacts

Install Spec Kitty CLI

From PyPI (Recommended - Stable Releases)

Using pip:

pip install spec-kitty-cli

Using uv:

uv tool install spec-kitty-cli

From GitHub (Latest Development)

Using pip:

pip install git+https://github.com/Priivacy-ai/spec-kitty.git

Using uv:

uv tool install spec-kitty-cli --from git+https://github.com/Priivacy-ai/spec-kitty.git

Initialize a New Project

After installation, initialize a new project:

If installed globally:

spec-kitty init <PROJECT_NAME>

One-time usage (without installing):

Using pipx:

pipx run spec-kitty-cli init <PROJECT_NAME>

Using uvx:

uvx spec-kitty-cli init <PROJECT_NAME>

Add to Existing Project

To add Spec Kitty to an existing project, use the --here flag:

# Navigate to your existing project directory
cd /path/to/existing-project

# Initialize Spec Kitty in the current directory
spec-kitty init .
# or use the --here flag
spec-kitty init --here

When adding to an existing project:

Spec Kitty will merge its templates with your existing files
You'll be prompted to confirm if the directory is not empty
Use --force to skip confirmation: spec-kitty init --here --force
Agent configurations, mission system, and dashboard will be added
Your existing source code and dependencies are preserved

Best Practices for Existing Projects:

Backup first: Commit your current work to git before adding Spec Kitty
Review .gitignore: Spec Kitty automatically protects agent directories in .gitignore
Team alignment: Add Spec Kitty to a feature branch before merging to main if you're in a team
Follow the workflow: After init, run /spec-kitty.specify to begin your first feature

Choose AI Agent

You can proactively specify your AI agent during initialization:

spec-kitty init <project_name> --ai claude
spec-kitty init <project_name> --ai gemini
spec-kitty init <project_name> --ai copilot

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

Script Type Selection

Spec Kitty can generate shell wrappers in either format:

--script sh for POSIX shells (default)
--script ps for PowerShell-oriented environments

The underlying workflow is Python CLI-based (spec-kitty agent *), and wrappers are generated for your selected script type.

Ignore Agent Tools Check

If you prefer to get the templates without checking for the right tools:

spec-kitty init <project_name> --ai claude --ignore-agent-tools

Verification

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 - Scaffold mission-specific research artifacts (Phase 0)
/spec-kitty.tasks - Break down into actionable tasks

When you run /spec-kitty.specify or /spec-kitty.plan, expect the assistant to pause with WAITING_FOR_DISCOVERY_INPUT or WAITING_FOR_PLANNING_INPUT until you answer its question tables.

Troubleshooting

Git Credential Manager on Linux

If you're having issues with Git authentication on Linux, you can install Git Credential Manager:

#!/usr/bin/env bash
set -e
echo "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.deb
echo "Installing Git Credential Manager..."
sudo dpkg -i gcm-linux_amd64.2.6.1.deb
echo "Configuring Git to use GCM..."
git config --global credential.helper manager
echo "Cleaning up..."
rm gcm-linux_amd64.2.6.1.deb

Table of Contents