Skip to main content
Implementation Status: The splat squash command documented here represents the intended design from the project README. The CLI integration is currently in development. The core error analysis functionality exists in the Python modules (relational.py, process.py) but needs to be connected to the CLI interface in cli/cli.py.

​
Your First Debug Session

This guide walks you through debugging your first error with Splat using a real example.
1

Verify your installation

Ensure Splat is installed and your virtual environment is activated:
source zapenv/bin/activate
splat --version
2

Create a test file with an error

Let’s create a simple Python file with a syntax error:
test.py
def hello():
    print("hello"

if __name__ == "__main__":
    hello()
Notice the missing closing parenthesis on line 2 - this is intentional!
If you try to run this directly, you’ll get a syntax error:
python3 test.py

File "test.py", line 2
    print("hello"
                 ^
SyntaxError: '(' was never closed
3

Run Splat to debug the error

Instead of running the file directly, use Splat:
splat squash "python3 test.py"
Splat will:
  1. Execute your command and capture the error
  2. Parse the stack trace to identify test.py
  3. Read the file contents
  4. Send the error and code to Groq’s AI for analysis
  5. Return a structured debug response
The first run might take a few seconds as Splat initializes. Subsequent runs are nearly instant.
4

Review the debug response

Splat will provide a structured response:
{
  "path": "/path/to/test.py",
  "file": "test.py",
  "line": 2,
  "what": "SyntaxError: The opening parenthesis in the print() call on line 2 is never closed. Python requires all opening parentheses to have matching closing parentheses.",
  "todo": "Add a closing parenthesis ')' at the end of line 2 after the string 'hello'. The corrected line should read: print('hello')"
}
The response includes:
  • path: Full path to the file with the error
  • file: Filename
  • line: Exact line number
  • what: Clear explanation of what went wrong
  • todo: Step-by-step instructions to fix it
5

Fix the error

Apply the suggested fix:
test.py
def hello():
    print("hello")

if __name__ == "__main__":
    hello()
Run it again through Splat:
splat squash "python3 test.py"
Success! Your code runs without errors.

​
Understanding the Command

The basic Splat command follows this pattern: 
splat squash "<your-command>"
​
squash
command
required
The Splat subcommand that executes your code and captures errors
​
your-command
string
required
The exact command you would normally use to run your application, wrapped in quotes

​
Examples

splat squash "python3 app.py"

​
Using Relational Mode

For complex errors involving multiple files, use the -r flag to enable relational analysis: 
splat squash -r "python3 main.py"
Relational mode builds a dependency graph of your project:
  1. Parses imports - Analyzes import and from statements in error files
  2. Builds adjacency list - Creates a graph of file relationships
  3. Finds related files - Traverses the graph to find all Nth-degree dependencies
  4. Includes context - Sends all related files to the AI for deeper analysis
Use relational mode (-r) when:
  • The error involves multiple files
  • You’re debugging import issues or circular dependencies
  • The error message mentions files outside your main script
  • You need deeper context about how files interact

​
Example: Debugging with Relational Mode

Consider a FastAPI application with this structure: 
project/
├── main.py
├── handlers/
│   └── fastapi_handlers.py
└── utils/
    └── utils.py
If main.py imports from handlers.fastapi_handlers, which imports from utils.utils, and an error occurs: 
splat squash -r "python3 main.py"
Splat will include all three files in the analysis, giving the AI complete context about your application’s structure and dependencies.

​
Real-World Example

Let’s debug a more realistic error using the test FastAPI application from the Splat repository:
1

Navigate to the test directory

cd test/
2

Run the FastAPI app through Splat

splat squash "python3 main.py"
The application intentionally contains several bugs:
  • Random server errors in /users endpoint
  • Type validation errors in /items endpoint
  • Missing key errors in /process endpoint
  • Off-by-one errors in /item/{item_id} update
3

Trigger an error

With the server running, make a request that triggers an error:
curl http://localhost:8000/process -X POST -H "Content-Type: application/json" -d '{"value1": 5}'
This will cause a KeyError because value2 is missing.
4

Get AI debugging assistance

Splat captures the error and provides:
  • The exact line where the KeyError occurred
  • Explanation of why accessing data['value2'] failed
  • Recommendation to use data.get('value2') with a default value or validate input

​
Best Practices

Always use quotes

Wrap your command in quotes to ensure proper parsing:
splat squash "python3 app.py"

Use -r for multi-file errors

Enable relational mode when errors span multiple files:
splat squash -r "python3 main.py"

Check .gitignore

Ensure sensitive files are excluded via .gitignore before using Splat

Review AI suggestions

Always review AI recommendations before applying fixes - understanding the error helps prevent future issues

​
Common Issues

Some issues to check:
  1. Make sure your command is wrapped in quotes
  2. Verify the command works when run directly (without Splat)
  3. Check that your virtual environment is activated
  4. Ensure you’re in the correct directory
If you hit Groq’s rate limits:
  1. Wait a few seconds between requests
  2. Consider upgrading your Groq API plan for higher limits
  3. Use relational mode selectively - it sends more data per request
If the -r flag doesn’t find related files:
  1. Ensure imports use relative or absolute paths correctly
  2. Check that imported modules are in the same project root
  3. Verify your project structure follows standard Python conventions
Known limitations (from README):
  • Splat doesn’t conform to formatting configurations when suggesting code
  • Sub-module entry points not originating in the root directory may have issues
  • Try running from your project root directory

​
Next Steps

Now that you’ve completed your first debug session, explore more:

How Splat Works

Deep dive into Splat’s error tracing and context gathering

Configuration

Customize Splat’s behavior and AI model settings

Advanced Features

Learn about file writer agents and advanced debugging modes

Examples

See real-world debugging scenarios and solutions

Build docs developers (and LLMs) love

Get started for freeTalk to us