A sandboxed coding agent that automatically creates pull requests based on natural language prompts. Built with FastAPI, Modal, and Claude AI.

• Streaming API: Real-time updates via Server-Sent Events
• AI-Powered Code Generation: Uses Claude to analyze codebases and generate intelligent changes
• Secure Sandboxing: Runs in isolated Modal environments
• Automatic PR Creation: Creates GitHub pull requests with detailed descriptions
• Multi-language Support: Works with Python, JavaScript, TypeScript, Go, Rust, and more
• Real-time Observability: Comprehensive logging and streaming updates

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   FastAPI App   │───▶│  Coding Agent    │───▶│  Claude AI      │
│   (Streaming)   │    │  (Analysis)      │    │  (Code Gen)     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Git Service   │    │  Modal Sandbox   │    │  GitHub API     │
│   (Repo Ops)    │    │  (Isolation)     │    │  (PR Creation)  │
└─────────────────┘    └──────────────────┘    └─────────────────┘

• Python 3.8+
• GitHub Personal Access Token (with repo permissions)
• Anthropic API Key (for Claude)
• Modal account (for sandboxing)

1. Clone the repository

   git clone <your-repo-url>
   cd tiny-backspace

2. Install dependencies

   pip install -r requirements.txt

3. Set up environment variables

   # Create .env file
   cp .env.example .env
   
   # Edit .env with your credentials
   GITHUB_TOKEN=your_github_personal_access_token
   ANTHROPIC_API_KEY=your_anthropic_api_key

4. Set up Modal (optional for local development)

   modal token new

1. Start the API server

   python -m app.main

2. Test the API

   python test_client.py

Main endpoint for coding agent requests.

Request:

{
  "repoUrl": "https://github.com/username/repo",
  "prompt": "Add input validation to all POST endpoints"
}

Response (Server-Sent Events):

data: {"type": "Status", "message": "Starting Tiny Backspace coding agent..."}
data: {"type": "Tool", "action": "git_clone", "repo": "https://github.com/username/repo"}
data: {"type": "Analysis", "data": {"languages": ["Python"], "frameworks": ["FastAPI"]}}
data: {"type": "AI Message", "message": "Analyzing codebase structure..."}
data: {"type": "Tool", "action": "edit", "filepath": "app.py", "type": "edit"}
data: {"type": "Success", "pr_url": "https://github.com/username/repo/pull/123"}

Health check endpoint.

API information and status.

import asyncio
import aiohttp
import json

async def create_pr():
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "http://localhost:8000/code",
            json={
                "repoUrl": "https://github.com/example/simple-api",
                "prompt": "Add error handling and logging to all endpoints"
            }
        ) as response:
            async for line in response.content:
                if line.startswith(b'data: '):
                    data = json.loads(line[6:].decode())
                    print(f"{data['type']}: {data.get('data', {}).get('message', '')}")

asyncio.run(create_pr())

Your GitHub token needs the following permissions:

• repo (Full control of private repositories)
• workflow (Update GitHub Action workflows)

I chose Claude 3 Sonnet as the coding agent for several reasons:

1. Code Understanding: Claude excels at understanding codebases and generating contextually appropriate changes
2. Multi-language Support: Handles Python, JavaScript, TypeScript, Go, Rust, and more
3. Structured Output: Can generate JSON responses for structured implementation plans
4. Safety: Built-in safety measures and ethical considerations
5. Reliability: Consistent and high-quality code generation

1. Codebase Analysis: Scans repository structure and identifies key files
2. Implementation Planning: Generates detailed plan using Claude
3. Code Generation: Creates specific file changes based on the plan
4. Git Operations: Creates branch, commits changes, and pushes
5. PR Creation: Automatically creates pull request with detailed description

• Modal Sandbox: All code execution happens in isolated Modal environments
• Temporary Directories: Repository cloning uses temporary directories that are cleaned up
• GitHub Token Scoping: Uses minimal required permissions
• Input Validation: Validates all inputs and repository URLs
• Error Handling: Comprehensive error handling and logging

The API provides real-time observability through:

• Streaming Events: Real-time updates on all operations
• Structured Logging: Comprehensive logging with different levels
• Progress Tracking: Detailed progress updates for each step
• Error Reporting: Clear error messages and debugging information

Run the test client to see the API in action:

python test_client.py

This will:

1. Test the health check endpoint
2. Send a sample coding request
3. Display real-time streaming updates
4. Show the final PR creation result

python -m app.main

modal deploy app.main

docker build -t tiny-backspace .
docker run -p 8000:8000 tiny-backspace

🧪 Tiny Backspace API Test
==================================================
🏥 Health Check: healthy

🚀 Starting Tiny Backspace Test
Repository: https://github.com/octocat/Hello-World
Prompt: Add a simple README section about contributing
--------------------------------------------------
📡 Streaming response:
--------------------------------------------------
📊 Starting Tiny Backspace coding agent...
🔧 Cloning repository...
📊 Analyzing codebase with AI...
🔍 Analysis: 1 languages, 0 frameworks, 3 files
🤖 AI: Implementation plan: Add contributing section to README...
📋 Plan: 1 files to modify
   Add contributing section to README with guidelines...
✏️  Editing: README.md
📊 Applying code changes...
💻 Running: git checkout -b feature/backspace-1234
💻 Running: git add .
💻 Running: git commit -m 'Implement: Add a simple README section...'
💻 Running: git push origin feature/backspace-1234
📊 Creating pull request...
💻 Running: gh pr create --title 'Implement: Add a simple README...'
✅ Success! Successfully implemented 'Add a simple README section about contributing' with 1 changes
🔗 PR URL: https://github.com/octocat/Hello-World/pull/123

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

MIT License - see LICENSE file for details.

1. GitHub Token Issues

   • Ensure your token has the required permissions
   • Check that the repository is accessible

2. Claude API Issues

   • Verify your Anthropic API key is correct
   • Check your API usage limits

3. Modal Sandbox Issues

   • Ensure Modal is properly configured
   • Check Modal account status and quotas

Enable debug logging:

export LOG_LEVEL=DEBUG
python -m app.main

• Support for private repositories
• Integration with more AI models
• Advanced code review capabilities
• Support for more git platforms (GitLab, Bitbucket)
• Web UI for easier interaction
• Batch processing of multiple requests
• Advanced sandboxing with E2B or Daytona