Installation

Development Note: Splat’s CLI is under active development. The core error analysis modules are functional, but the splat squash command interface is not yet fully wired up in the codebase. This guide documents the intended installation and usage pattern.

Prerequisites

Before installing Splat, ensure you have the following:

Python 3.7+

Splat requires Python 3.7 or higher

pip or setuptools

Python package manager for installation

tmux

Terminal multiplexer for session management

npm (optional)

Required for repomix dependency

Installation Methods

Automated Setup (Recommended)
Manual Installation
Using pip (Coming Soon)

The easiest way to install Splat is using the provided setup script:

Clone the repository

git clone https://github.com/ehcaw/splat.git
cd splat

Run the setup script

chmod +x setup.sh
./setup.sh

This script will:

Install tmux (on macOS via Homebrew)
Create a virtual environment named zapenv
Install all Python dependencies
Install repomix globally via npm

The setup script uses Homebrew on macOS. For Linux, install tmux manually using your package manager:

# Ubuntu/Debian
sudo apt-get install tmux

# Fedora
sudo dnf install tmux

# Arch
sudo pacman -S tmux

Activate the virtual environment

source zapenv/bin/activate

Verify installation

splat --version

Install system dependencies

Install tmux using your system package manager:

brew install tmux

Create a virtual environment

python3 -m venv zapenv
source zapenv/bin/activate

Install Python dependencies

pip install -r requirements.txt

This installs:

click - CLI framework
groq - AI inference API client
fastapi & uvicorn - API framework (for advanced features)
python-dotenv - Environment variable management
pydantic & pydantic_ai - Data validation and AI agents
repopack - Repository context packaging
Other utilities

Install Splat

pip install -e .

This installs Splat in editable mode, making the splat command available globally.

Install repomix (optional but recommended)

npm install -g repomix

Repomix helps package repository context for AI analysis.

PyPI distribution is not yet available. Use the automated setup or manual installation methods for now.

Once available, you’ll be able to install with:

pip install splat-debug

Environment Configuration

Set up your API key

Splat uses Groq for AI inference. Create a .env file in your project or Splat installation directory:

.env

API=your_groq_api_key_here
API_KEY=your_groq_api_key_here
MODEL=llama3-70b-8192

Get your free Groq API key at console.groq.com

Verify .gitignore support

Splat automatically respects .gitignore files in your project to exclude sensitive information. Ensure your .env file is in .gitignore:

.gitignore

.env
__pycache__/
*.pyc

Troubleshooting

Command not found: splat

If the splat command is not recognized after installation:

Ensure your virtual environment is activated:
```
source zapenv/bin/activate
```
Reinstall Splat:
```
pip install -e .
```
Check if the installation directory is in your PATH:
```
echo $PATH
```

tmux not found

Install tmux using your system package manager:

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt-get install tmux

# Fedora
sudo dnf install tmux

ModuleNotFoundError after installation

Make sure you’ve installed all dependencies:

pip install -r requirements.txt

If issues persist, try recreating your virtual environment:

deactivate
rm -rf zapenv
python3 -m venv zapenv
source zapenv/bin/activate
pip install -r requirements.txt
pip install -e .

API key errors

If you see API authentication errors:

Verify your .env file exists and contains your Groq API key
Check that the MODEL and API_KEY variables are set correctly
Ensure your API key is valid at console.groq.com

Next Steps

Now that Splat is installed, let’s run your first debug session:

Quick Start Guide

Learn how to use Splat to debug your first error

Get Started

Core Concepts

Commands

Configuration

Examples

Installation

Prerequisites

Python 3.7+

pip or setuptools

tmux

npm (optional)

Installation Methods

Environment Configuration

Troubleshooting

Next Steps

Quick Start Guide

Build docs developers (and LLMs) love

Get Started

Core Concepts

Commands

Configuration

Examples

​Prerequisites

Python 3.7+

pip or setuptools

tmux

npm (optional)

​Installation Methods

​Environment Configuration

​Troubleshooting

​Next Steps

Quick Start Guide

Build docs developers (and LLMs) love

Prerequisites

Installation Methods

Environment Configuration

Troubleshooting

Next Steps