Skip to content

Installation

project-guide can be installed using pip, pipx, or from source.

Requirements

  • Python 3.11 or higher
  • pip or pipx package manager

project-guide depends on Jinja2 for its mode-driven templating system. This is installed automatically as a dependency.

Install via pip

The simplest way to install project-guide is using pip:

pip install project-guide

This installs project-guide and its dependencies (including Jinja2) in your current Python environment.

For system-wide CLI access without affecting your project's dependencies, use pipx:

pipx install project-guide

pipx installs the tool in an isolated environment while making the CLI command globally available.

If you don't have pipx installed:

# On macOS/Linux
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# On Windows
py -m pip install --user pipx
py -m pipx ensurepath

Install from Source

To install the latest development version from GitHub:

git clone https://github.com/pointmatic/project-guide.git
cd project-guide
pip install -e .

For development with all optional dependencies:

pip install -e ".[dev,docs]"

Verify Installation

After installation, verify that project-guide is available:

project-guide --version

You should see the version number displayed.

Shell Completion (Optional)

Enable Tab completion for project-guide commands, flags, and mode names. Add the appropriate line to your shell's startup file.

Bash

Add to ~/.bashrc:

eval "$(_PROJECT_GUIDE_COMPLETE=bash_source project-guide)"

Zsh

Add to ~/.zshrc:

eval "$(_PROJECT_GUIDE_COMPLETE=zsh_source project-guide)"

Fish

Add to ~/.config/fish/completions/project-guide.fish:

_PROJECT_GUIDE_COMPLETE=fish_source project-guide | source

After updating your shell config, restart your shell (or source the file). Now you can:

  • project-guide <TAB> — complete command names (init, mode, status, etc.)
  • project-guide mode <TAB> — complete mode names (default, plan_concept, code_velocity, etc.) — reads .metadata.yml from your current project
  • project-guide --<TAB> — complete flags

Mode name completion is dynamic and reads the active project's .metadata.yml, so it works correctly even if you have custom modes.

Next Steps