Skip to content

Installation

Get codebrief up and running on your system in just a few minutes!

Prerequisites

System Requirements

  • Python: 3.9 or higher
  • Git: For cloning the repository
  • Poetry: For dependency management (recommended)

Installing Prerequisites

macOS

# Install Python via Homebrew
brew install python@3.11

# Install Poetry
curl -sSL https://install.python-poetry.org | python3 -

Ubuntu/Debian

# Update package list
sudo apt update

# Install Python and pip
sudo apt install python3.11 python3.11-pip python3.11-venv

# Install Poetry
curl -sSL https://install.python-poetry.org | python3 -

Windows

# Install Python from Microsoft Store or python.org
# Then install Poetry
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

Other Systems

Visit Python.org for Python installation and Poetry's documentation for Poetry setup.

Installation Methods

The fastest way to get started with codebrief:

# Clone the repository
git clone https://github.com/Shorzinator/codebrief.git
cd codebrief

# Install with Poetry
poetry install

# Activate the virtual environment
poetry shell

# Verify installation
codebrief --version

📦 PyPI Installation

pip install codebrief

🛠️ Development Installation

For contributors and developers who want to work on codebrief itself:

# Clone the repository
git clone https://github.com/YOUR_USERNAME/codebrief.git
cd codebrief

# Install with development dependencies
poetry install --with dev

# Install pre-commit hooks
poetry run pre-commit install

# Run tests to verify everything works
poetry run pytest

# Activate the virtual environment
poetry shell

Verification

After installation, verify that codebrief is working correctly:

Basic Verification

# Check version
codebrief --version

# View help
codebrief --help

# Test tree generation
codebrief tree --help

Comprehensive Test

# Create a test directory
mkdir codebrief-test
cd codebrief-test

# Create some test files
echo "print('Hello, World!')" > hello.py
echo "# Test Project" > README.md
mkdir src
echo "def main(): pass" > src/main.py

# Test all commands
codebrief tree
codebrief flatten . --include "*.py"
codebrief deps

# Clean up
cd ..
rm -rf codebrief-test

Environment Variables

Configure codebrief behavior with environment variables:

# Set default output directory
export codebrief_OUTPUT_DIR=~/context-outputs

# Enable debug mode
export codebrief_DEBUG=1

# Set default config file location
export codebrief_CONFIG=~/.codebrief.toml

Troubleshooting

Common Issues

Python Version Issues

Problem: codebrief: command not found after installation

Solution: Ensure you're in the Poetry virtual environment: 

poetry shell
# or use
poetry run codebrief --version

Permission Errors

Problem: Permission denied when installing Poetry or running commands

Solution: Don't use sudo with Poetry. Install Poetry for your user only: 

curl -sSL https://install.python-poetry.org | python3 -

Import Errors

Problem: ModuleNotFoundError when running codebrief

Solution: Reinstall dependencies: 

poetry install --sync

Getting Help

If you encounter issues:

  1. Check the Troubleshooting Guide
  2. Search existing issues
  3. Create a new issue if needed

Next Steps

Now that codebrief is installed:

Installation issues? We're here to help! Check our Support page for assistance.