Ripperdoc (quantmew/ripperdoc)

Ripperdoc

https://github.com/quantmew/ripperdoc
Admin
Ripperdoc is an AI-powered terminal assistant for coding tasks that provides interactive AI-assisted...

Tokens:8,306
Snippets:61
Trust Score:5.3
Update:4 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# Ripperdoc - AI-Powered Terminal Assistant

## Introduction

Ripperdoc is an AI-powered terminal assistant for coding tasks that provides an interactive interface for AI-assisted development, file management, and command execution. It serves as a bridge between developers and AI models (Anthropic Claude, OpenAI, and others) to enable intelligent code analysis, generation, and project navigation through both an interactive CLI and a headless Python SDK. The project implements an extensible tool system that allows AI models to perform file operations, execute commands, manage tasks, and integrate with external services through the Model Context Protocol (MCP).

The platform combines multiple AI model providers with a rich set of specialized tools including file editing, code search, bash execution, Jupyter notebook support, and background process management. It features a permission system for safe operations, session management with persistent history, skill bundles for extending agent capabilities, and subagent delegation for complex multi-step tasks. Ripperdoc supports both real-time interactive sessions and programmatic headless usage, making it suitable for both manual development workflows and automated code generation pipelines.

## APIs and Key Functions

### Python SDK - One-Shot Query

Quick helper for single AI queries without maintaining session state.

```python
import asyncio
from ripperdoc.sdk import query, RipperdocOptions
from ripperdoc.utils.messages import AssistantMessage, ProgressMessage

async def main():
    options = RipperdocOptions(
        safe_mode=False,
        allowed_tools=["Bash", "View", "Glob", "Grep"],
        cwd="/home/user/my-project",
        model="main",
        max_thinking_tokens=0
    )

    async for msg in query("List all Python files and count lines of code", options=options):
        if isinstance(msg, AssistantMessage):
            print(f"Assistant: {msg.message.content}")
        elif isinstance(msg, ProgressMessage):
            print(f"[Progress] {msg.content}")

asyncio.run(main())
```

### Python SDK - Persistent Session Client

Session-based client for multi-turn conversations with maintained context.

```python
import asyncio
from ripperdoc.sdk import RipperdocClient, RipperdocOptions
from ripperdoc.utils.messages import AssistantMessage, ProgressMessage

async def main():
    options = RipperdocOptions(
        safe_mode=False,
        verbose=True,
        model="main",
        context={"project_type": "Python Web API", "framework": "FastAPI"}
    )

    async with RipperdocClient(options) as client:
        # First query
        await client.query("Summarize the project structure")
        async for msg in client.receive_response():
            if isinstance(msg, AssistantMessage):
                print(msg.message.content)

        # Follow-up query with context maintained
        await client.query("Find the main API endpoint definitions")
        async for msg in client.receive_response():
            if isinstance(msg, AssistantMessage):
                print(msg.message.content)

        # Context from both queries is preserved

asyncio.run(main())
```

### Direct Tool Usage - Bash Execution

Execute shell commands programmatically with timeout and output handling.

```python
import asyncio
from ripperdoc.tools.bash_tool import BashTool, BashToolInput
from ripperdoc.core.tool import ToolUseContext

async def run_command():
    tool = BashTool()
    context = ToolUseContext()

    input_data = BashToolInput(
        command="pytest tests/ -v --cov=src",
        timeout=30000  # 30 seconds
    )

    async for result in tool.call(input_data, context):
        if hasattr(result, 'data'):
            print(f"Command: {result.data.command}")
            print(f"Output:\n{result.data.stdout}")
            print(f"Error:\n{result.data.stderr}")
            print(f"Exit code: {result.data.exit_code}")
            if result.data.exit_code == 0:
                print("Tests passed successfully")
            else:
                print("Tests failed")

asyncio.run(run_command())
```

### Direct Tool Usage - File Reading

Read file contents with optional line range specification.

```python
import asyncio
from ripperdoc.tools.file_read_tool import FileReadTool, FileReadToolInput
from ripperdoc.core.tool import ToolUseContext

async def read_file():
    tool = FileReadTool()
    context = ToolUseContext()

    # Read specific line range
    input_data = FileReadToolInput(
        file_path="/home/user/project/src/main.py",
        offset=0,    # Start from line 0
        limit=50     # Read 50 lines
    )

    async for result in tool.call(input_data, context):
        print(f"File: {result.data.file_path}")
        print(f"Lines read: {result.data.line_count}")
        print(f"Content:\n{result.data.content}")

asyncio.run(read_file())
```

### Direct Tool Usage - File Pattern Matching

Search for files using glob patterns.

```python
import asyncio
from ripperdoc.tools.glob_tool import GlobTool, GlobToolInput
from ripperdoc.core.tool import ToolUseContext

async def find_files():
    tool = GlobTool()
    context = ToolUseContext()

    # Find all Python test files
    input_data = GlobToolInput(
        pattern="**/test_*.py",
        path="/home/user/project"
    )

    async for result in tool.call(input_data, context):
        print(f"Pattern: {result.data.pattern}")
        print(f"Found {result.data.count} files")
        for match in result.data.matches:
            print(f"  - {match}")

asyncio.run(find_files())
```

### Direct Tool Usage - Content Search

Search file contents using regex patterns with ripgrep.

```python
import asyncio
from ripperdoc.tools.grep_tool import GrepTool, GrepToolInput
from ripperdoc.core.tool import ToolUseContext

async def search_content():
    tool = GrepTool()
    context = ToolUseContext()

    input_data = GrepToolInput(
        pattern=r"async def \w+",  # Find async function definitions
        path="/home/user/project/src",
        output_mode="content",
        case_insensitive=False,
        show_line_numbers=True,
        context_before=2,
        context_after=2,
        glob="*.py"
    )

    async for result in tool.call(input_data, context):
        print(f"Found matches in {result.data.files_with_matches} files")
        print(f"Results:\n{result.data.output}")

asyncio.run(search_content())
```

### Configuration - Model Profiles

Configure multiple AI model providers and select models for different task types.

```python
import json
from pathlib import Path

config = {
    "model_profiles": {
        "sonnet": {
            "provider": "anthropic",
            "model": "claude-3-5-sonnet-20241022",
            "api_key": "sk-ant-...",
            "max_tokens": 8192,
            "temperature": 0.7,
            "context_window": 200000
        },
        "haiku": {
            "provider": "anthropic",
            "model": "claude-3-haiku-20240307",
            "api_key": "sk-ant-...",
            "max_tokens": 4096,
            "temperature": 0.7,
            "context_window": 200000
        },
        "gpt4": {
            "provider": "openai",
            "model": "gpt-4-turbo-preview",
            "api_key": "sk-proj-...",
            "max_tokens": 4096,
            "temperature": 0.7,
            "context_window": 128000
        }
    },
    "model_pointers": {
        "main": "sonnet",      # Primary assistant
        "task": "haiku",       # Sub-tasks and quick operations
        "reasoning": "sonnet", # Complex reasoning
        "quick": "haiku"       # Fast operations
    },
    "theme": "dark",
    "verbose": False,
    "safe_mode": True
}

config_path = Path("~/.ripperdoc.json").expanduser()
config_path.write_text(json.dumps(config, indent=2))
print(f"Configuration saved to {config_path}")
```

### Configuration - Environment Variables

Set up API keys and provider credentials via environment variables.

```bash
# Anthropic Claude
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# OpenAI
export OPENAI_API_KEY="sk-proj-..."

# Alternative providers
export DEEPSEEK_API_KEY="your-deepseek-key"
export QWEN_API_KEY="your-qwen-key"
export GLM_API_KEY="your-glm-key"

# Optional: Configure timeouts and retries
export RIPPERDOC_API_TIMEOUT="120"
export RIPPERDOC_MAX_RETRIES="10"

# Launch interactive session
ripperdoc

# Or with specific options
ripperdoc --unsafe --verbose
```

### CLI - Interactive Session

Launch interactive terminal session for conversational AI assistance.

```bash
# Basic usage
ripperdoc

# Skip permission prompts (unsafe mode)
ripperdoc --unsafe

# Verbose output showing all operations
ripperdoc --verbose

# Specify working directory
ripperdoc --cwd /path/to/project

# Example session:
# > Analyze the authentication module
# > Find all TODO comments in Python files
# > Create a new API endpoint for user profile
# > Run the test suite and fix any failures
```

### SDK Options - Advanced Configuration

Customize SDK behavior with comprehensive options for tools, permissions, and prompts.

```python
from ripperdoc.sdk import RipperdocClient, RipperdocOptions

# Advanced configuration
options = RipperdocOptions(
    # Tool filtering
    allowed_tools=["Bash", "View", "Edit", "Glob", "Grep"],
    disallowed_tools=["FileWrite"],  # Prevent file creation

    # Safety and permissions
    safe_mode=True,
    permission_checker=custom_permission_function,

    # Model configuration
    model="main",
    max_thinking_tokens=4096,  # Enable reasoning mode

    # Context and instructions
    context={
        "project_type": "FastAPI Application",
        "database": "PostgreSQL",
        "deployment": "Docker"
    },
    additional_instructions=[
        "Follow PEP 8 style guidelines",
        "Include type hints in all functions",
        "Write docstrings for public APIs"
    ],

    # Working directory
    cwd="/home/user/my-project",

    # Output verbosity
    verbose=True
)

async with RipperdocClient(options) as client:
    await client.query("Refactor the database access layer")
    async for msg in client.receive_response():
        print(msg)
```

### Workflow - Complete Multi-Tool Pipeline

Combine multiple tools in a coordinated workflow for complex tasks.

```python
import asyncio
from ripperdoc.tools.glob_tool import GlobTool, GlobToolInput
from ripperdoc.tools.file_read_tool import FileReadTool, FileReadToolInput
from ripperdoc.tools.grep_tool import GrepTool, GrepToolInput
from ripperdoc.tools.bash_tool import BashTool, BashToolInput
from ripperdoc.core.tool import ToolUseContext

async def analyze_codebase():
    context = ToolUseContext()

    # Step 1: Find all Python source files
    print("Step 1: Finding Python files...")
    glob_tool = GlobTool()
    glob_input = GlobToolInput(pattern="**/*.py", path="./src")

    files = []
    async for result in glob_tool.call(glob_input, context):
        files = result.data.matches
        print(f"Found {len(files)} Python files")

    # Step 2: Search for TODO comments
    print("\nStep 2: Searching for TODO comments...")
    grep_tool = GrepTool()
    grep_input = GrepToolInput(
        pattern=r"#\s*TODO:",
        path="./src",
        output_mode="content",
        show_line_numbers=True
    )

    async for result in grep_tool.call(grep_input, context):
        print(f"Found TODOs:\n{result.data.output}")

    # Step 3: Read main entry point
    print("\nStep 3: Reading main.py...")
    read_tool = FileReadTool()
    read_input = FileReadToolInput(file_path="./src/main.py", limit=30)

    async for result in read_tool.call(read_input, context):
        print(f"Main entry point:\n{result.data.content}")

    # Step 4: Run linting
    print("\nStep 4: Running linter...")
    bash_tool = BashTool()
    bash_input = BashToolInput(command="ruff check src/", timeout=15000)

    async for result in bash_tool.call(bash_input, context):
        if result.data.exit_code == 0:
            print("Linting passed!")
        else:
            print(f"Linting issues:\n{result.data.stdout}")

asyncio.run(analyze_codebase())
```

### Skills - Custom Agent Extensions

Create reusable skill bundles to extend agent capabilities with domain-specific knowledge.

```bash
# Create project skill structure
mkdir -p .ripperdoc/skills/api-review
cd .ripperdoc/skills/api-review

# Create SKILL.md with YAML frontmatter
cat > SKILL.md << 'EOF'
---
name: api-review
description: Reviews API endpoints for security and best practices
allowed-tools: ["View", "Grep", "Bash"]
model: main
max-thinking-tokens: 2048
---

# API Review Skill

Review API endpoints for:
1. Authentication and authorization
2. Input validation
3. Error handling
4. Rate limiting
5. SQL injection vulnerabilities
6. XSS protection
7. CORS configuration

Check route definitions, middleware, and handler implementations.
EOF

# Use in session
ripperdoc
# > Use the api-review skill to analyze src/api/
```

### MCP Integration - External Tool Servers

Integrate Model Context Protocol servers for extended capabilities.

```bash
# Install MCP server
npm install -g @modelcontextprotocol/server-filesystem

# Configure in project
cat > .ripperdoc/mcp.json << EOF
{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
      "env": {}
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git"],
      "env": {}
    }
  }
}
EOF

# MCP tools are automatically loaded in sessions
ripperdoc
# > List available MCP servers
# > Use MCP tools to interact with git repository
```

## Summary

Ripperdoc serves as a comprehensive AI coding assistant that bridges the gap between developers and large language models through both interactive CLI and programmatic SDK interfaces. The platform's main use cases include automated code analysis and refactoring, intelligent file navigation and search, test execution and debugging, project documentation generation, and multi-step development workflows. Developers can use it for pair programming sessions where the AI suggests improvements, generates boilerplate code, explains complex algorithms, and performs routine maintenance tasks. The headless SDK enables integration into CI/CD pipelines, automated code review systems, and custom development tools that require AI-powered code understanding.

The architecture emphasizes extensibility and safety through its permission system, tool filtering, and skill bundles that encapsulate domain expertise. Integration patterns include embedding Ripperdoc as a library in existing Python applications, using it as a command-line code assistant in development workflows, creating custom tools that extend the agent's capabilities, configuring multiple model profiles for different task complexities, and connecting to external services via MCP servers. The platform supports both local development and team environments through project-level configuration files, making it suitable for individual developers seeking productivity gains and teams establishing consistent AI-assisted development practices. With support for multiple AI providers and reasoning modes, Ripperdoc adapts to various project requirements from quick code fixes to complex architectural planning.