Installation Guide¶

Goal Kit installation instructions for different platforms and use cases.

System Requirements¶

Python: 3.8 or higher
Git: Required for goal branch management
OS: Linux, macOS, or Windows

Installation Methods¶

Method 1: Using uv (Recommended)¶

The fastest and most reliable method using the uv package manager.

Install uv First¶

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Install Goal Kit¶

From GitHub (recommended):

uv tool install --from git+https://github.com/Nom-nom-hub/goal-kit.git goalkit

Or from local repository:

cd /path/to/goal-kit
uv tool install --from . goalkit

After installation, verify:

goalkit --version

Method 2: Global Installation via pip¶

Install Goal Kit globally on your system.

From GitHub:

pip install --upgrade pip
pip install git+https://github.com/Nom-nom-hub/goal-kit.git

Or from local repository:

cd /path/to/goal-kit
pip install --upgrade pip
pip install -e .

Verify installation:

goalkit --version

Method 3: One-Time Usage (No Installation)¶

Run Goal Kit without installing to your system.

uv run --from git+https://github.com/Nom-nom-hub/goal-kit.git goalkit init my-project
uv run --from git+https://github.com/Nom-nom-hub/goal-kit.git goalkit check

This is useful for: - Testing Goal Kit before installing - CI/CD pipelines - Containerized environments

Method 4: Local Development Installation¶

Install from source for contributing or customizing.

git clone https://github.com/Nom-nom-hub/goal-kit.git
cd goal-kit
pip install -e ".[dev]"

Post-Installation Setup¶

1. Verify Installation¶

# Check version
goalkit --version

# Check available agents
goalkit check

2. Initialize Your First Project¶

# Create and initialize a new project
goalkit init my-first-project
cd my-first-project

# Check project setup
ls -la

This creates: - .goalkit/ - Configuration directory - .goalkit/vision.md - Project vision template - .goalkit/goals/ - Goals directory - Agent context files (CLAUDE.md, etc.)

3. Configure Your Agent¶

Goal Kit detects and configures for these agents: - Claude (Claude Code) - GitHub Copilot - Google Gemini - Cursor - Qwen Code - Windsurf - Kilo Code - Amazon Q - And others

Configuration happens automatically on goalkit init.

To manually configure for a specific agent:

# Initialize with specific agent
goalkit init my-project --agent claude

Platform-Specific Instructions¶

macOS¶

Using Homebrew (Optional)¶

# Install uv via Homebrew
brew install uv

# Then install Goal Kit
uv tool install --from . goalkit

Using Native Python¶

# Install Python 3.8+
brew install python@3.11

# Install Goal Kit
pip install -e .

Verify Git¶

Git comes pre-installed on macOS. Verify:

git --version

Linux (Ubuntu/Debian)¶

Using Package Manager¶

# Update package manager
sudo apt update
sudo apt install python3.11 python3.11-venv git

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Goal Kit
uv tool install --from . goalkit

Verify Installation¶

python3 --version
git --version
goalkit --version

Windows¶

Prerequisites¶

Install Python:
Download from python.org
Check "Add Python to PATH" during installation
Choose Python 3.8 or higher
Install Git:
Download from git-scm.com
Use default installation settings

Install uv:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Install Goal Kit¶

uv tool install --from . goalkit

Verify Installation¶

Open PowerShell and run:

goalkit --version

Docker¶

Run Goal Kit in a Docker container:

FROM python:3.11-slim

# Install git and required tools
RUN apt-get update && apt-get install -y git

# Install Goal Kit
RUN pip install git+https://github.com/Nom-nom-hub/goal-kit.git

WORKDIR /workspace

Build and run:

docker build -t goal-kit .
docker run -it -v $(pwd):/workspace goal-kit goalkit init my-project

Troubleshooting Installation¶

"command not found: goalkit"¶

Solution 1: Verify installation path

# Find where goalkit was installed
which goalkit  # macOS/Linux
where goalkit  # Windows

# Add to PATH if needed
export PATH="$HOME/.cargo/bin:$PATH"  # Add to ~/.bashrc or ~/.zshrc

Solution 2: Use full path

~/.cargo/bin/goalkit --version

Solution 3: Reinstall with uv

uv tool install --force --from . goalkit

"No module named 'goalkit'"¶

Solution: Ensure you're in the Goal Kit project directory

cd /path/to/goal-kit
pip install -e .

Python Version Issues¶

Solution: Install Python 3.8 or higher

# Check current version
python --version

# Install specific version (macOS with Homebrew)
brew install python@3.11
python3.11 -m pip install -e .

# On Windows, use Python installer or:
choco install python --version=3.11.0

Git Not Found¶

Solution: Install git

# macOS
brew install git

# Linux
sudo apt install git

# Windows
# Download from: https://git-scm.com/download/win

Verify:

git --version

Permission Denied on Unix¶

Solution: Use user installation

# Install for current user only
pip install --user -e .

# Or use uv (recommended)
uv tool install --from . goalkit

Virtual Environment Issues¶

Solution: Use uv which handles environments automatically

uv tool install --from . goalkit

Or manually with venv:

# Create virtual environment
python -m venv venv

# Activate it
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows

# Install
pip install -e .

Verification Checklist¶

After installation, verify everything works:

goalkit --version shows a version number
goalkit check lists detected agents
goalkit init test-project creates a project
.goalkit/ directory exists in the project
git init works in the project directory

Updating Goal Kit¶

Using uv¶

uv tool upgrade goalkit

Using pip¶

pip install --upgrade goal-kit

From Source¶

cd /path/to/goal-kit
git pull
pip install --upgrade -e .

Uninstalling Goal Kit¶

Using uv¶

uv tool uninstall goalkit

Using pip¶

pip uninstall goal-kit

Next Steps¶

After successful installation:

Quick Start: Read Quick Start Guide
First Project: Run goalkit init my-project
Learn Methodology: Read Goal-Driven Development
See Examples: Check Practical Examples

Getting Help¶

Issues: Check GitHub Issues
Troubleshooting: Read Troubleshooting Guide
Documentation: Visit Goal Kit Docs

Ready to install? Start with Method 1 (uv) for the smoothest experience.