Installation¶

Requirements¶

Git (for version control)
Claude Code (for AI-assisted development)
Either:
uv for uvx usage (recommended), or
Python 3.12+ for traditional installation

Quick Start with uvx (Recommended)¶

No installation required! Use uvx to run Quaestor directly:

# Initialize a project without installing Quaestor
uvx quaestor init

# Team mode
uvx quaestor init --mode team

# Update to latest version
uvx quaestor update

This approach: - ✅ No Python dependencies in your project - ✅ Always uses the latest version - ✅ Hooks work via uvx commands - ✅ Clean project environment

Traditional Installation¶

Install globally with pip:

pip install quaestor

Install from Source¶

For development or latest features:

git clone https://github.com/jeanluciano/quaestor.git
cd quaestor
pip install -e .

Verify Installation¶

quaestor --version

Claude Code Integration¶

Quaestor is designed to work seamlessly with Claude Code. To set up the integration:

Install Claude Code following the official documentation
Initialize Quaestor in your project (see Quick Start)
The slash commands (/plan, /impl, etc.) will be automatically available

Optional Dependencies¶

For enhanced functionality, you may want to install:

# For GitHub integration
pip install gh

# For advanced YAML processing
pip install ruamel.yaml

# For rich console output
pip install rich

Troubleshooting¶

Permission Issues¶

If you encounter permission issues during installation:

pip install --user quaestor

Path Issues¶

Make sure your Python scripts directory is in your PATH:

# Add to your shell profile (.bashrc, .zshrc, etc.)
export PATH="$HOME/.local/bin:$PATH"

Claude Code Integration Issues¶

If slash commands don't work:

Ensure you're in a Quaestor-initialized project
Check that .quaestor/ directory exists
Verify Claude Code is properly configured

Migration for Existing Users¶

If you have an existing Quaestor installation with Python hook files:

From Python Hooks to uvx Commands¶

The new version uses uvx commands instead of Python files in .claude/hooks/:

Remove old hook files (no longer needed):
```
rm -rf .claude/hooks/*.py
```

Update settings.json to use uvx commands:

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "uvx --from quaestor quaestor hook session-context-loader"
      }]
    }],
    "PostToolUse": [{
      "matcher": "TodoWrite",
      "hooks": [{
        "type": "command",
        "command": "uvx --from quaestor quaestor hook todo-spec-progress"
      }]
    }]
  }
}

Or simply re-run init to update everything:
```
uvx quaestor update
```

Benefits of Migration¶

No Python files to maintain in your project
Hooks always use the latest Quaestor version
Cleaner project structure
Works without Python installed locally

Next Steps¶

Once installed, proceed to the Quick Start Guide to initialize your first project.