Open Source AI Code Assistant - Design Document

Table of Contents

1. Project Overview
2. System Architecture
3. Hardware Requirements
4. Technology Stack
5. Component Specifications
6. API Specification
7. CLI Interface Specification
8. Shell Integration
9. MCP Integration
10. REPL Requirements
11. Model Training Pipeline
12. Data Processing Requirements
13. Implementation Phases
14. Testing Requirements

Project Overview

Mission Statement

Build “Del the Funky Robosapien” (or “Del” for short) - a completely free, open-source AI code assistant that runs entirely on consumer hardware, providing privacy-first AI assistance for developers without any cloud dependencies.

Core Requirements

• Privacy First: All data processing must happen locally
• Open Source: MIT license, fully auditable code
• Consumer Hardware: Must run on typical developer machines
• Self-Contained: No external API dependencies
• Extensible: Plugin architecture for custom workflows
• Multi-Platform: Support Linux, macOS, and Windows

Target Users

• Individual developers seeking privacy-first AI assistance
• Teams wanting to keep code confidential
• Organizations with strict data governance requirements
• Students learning to code without subscription costs
• Open source projects needing AI assistance

Success Criteria

• Generate useful code suggestions within 3 seconds
• Handle codebases up to 100,000 files
• Support 10+ programming languages
• Process Git histories with 50,000+ commits
• Train custom models on user data in under 4 hours

System Architecture

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│                    User Interfaces                      │
│  ┌─────────────┬─────────────┬─────────────────────────┐ │
│  │ CLI Client  │ Web Client  │ IDE Extensions          │ │
│  │ Commands    │ Dashboard   │ VS Code, Vim, Emacs     │ │
│  │ REPL        │ Chat UI     │ IntelliJ, Sublime       │ │
│  │ Scripts     │ File Upload │ Custom integrations     │ │
│  └─────────────┴─────────────┴─────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
                            │ HTTP/WebSocket API
                            ▼
┌─────────────────────────────────────────────────────────┐
│                    API Gateway                          │
│  • HTTP/HTTPS Server     • Request/Response Logging     │
│  • WebSocket Support     • Rate Limiting                │
│  • Authentication        • Input Validation             │
│  • CORS Handling         • Error Management             │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│                   Business Logic                        │
│  ┌─────────────────┬─────────────────┬─────────────────┐ │
│  │ Context Manager │ Code Analyzer   │ Response Gen    │ │
│  │ • File tracking │ • AST parsing   │ • Prompt eng    │ │
│  │ • Embeddings    │ • Syntax check  │ • Templates     │ │
│  │ • Similarity    │ • Dependencies  │ • Streaming     │ │
│  │ • Ranking       │ • Call graphs   │ • Formatting    │ │
│  └─────────────────┴─────────────────┴─────────────────┘ │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│                   Infrastructure                        │
│  ┌─────────────────┬─────────────────┬─────────────────┐ │
│  │  Model Server   │ Data Pipeline   │ Storage Layer   │ │
│  │ • LLM Inference │ • Git Parser    │ • Vector DB     │ │
│  │ • GPU Support   │ • Email Parser  │ • Context Store │ │
│  │ • Model Cache   │ • Doc Parser    │ • Config Store  │ │
│  │ • Memory Mgmt   │ • Training Prep │ • Session Mgmt  │ │
│  └─────────────────┴─────────────────┴─────────────────┘ │
└─────────────────────────────────────────────────────────┘

Data Flow Architecture

Input Sources → Data Pipeline → Context Store → Model Server → Response
     │              │              │              │            │
     ▼              ▼              ▼              ▼            ▼
• Git repos    • Parse files   • Vector DB    • LLM Inference • Text
• Email boxes  • Extract code  • Embeddings   • GPU Accel     • Code  
• Documents    • Analyze AST   • Similarity   • Memory Mgmt   • Explanations
• Live files   • Generate      • Ranking      • Streaming     • Suggestions
• User input     training data • Search       • Error Handle  • Context

Hardware Requirements

Minimum Configuration (Basic Usage)

Component	Specification	Purpose
CPU	4-core x86_64/ARM64, 2.5GHz+	Model inference, embeddings
RAM	8GB total (4GB model + 4GB system)	Model loading, context storage
Storage	20GB free space, preferably SSD	Models, embeddings, context data
GPU	Optional, any OpenCL/CUDA compatible	Accelerated inference
Network	None (fully offline after setup)	Initial model downloads only
OS	Linux/macOS/Windows 10+	Cross-platform support

Expected Performance: 3B parameter model, 5-10 tokens/second, 4K context, single user

Recommended Configuration (Optimal Experience)

Component	Specification	Purpose
CPU	8-core with AVX2, 3.0GHz+	Faster CPU inference
RAM	16GB total (8GB model + 8GB system)	Larger models, more context
Storage	100GB SSD, NVMe preferred	Multiple models, large context store
GPU	NVIDIA RTX 3060+ (8GB VRAM) or Apple M2	GPU acceleration
Network	Gigabit for initial setup	Faster model downloads

Expected Performance: 7B parameter model, 15-25 tokens/second, 8K context, 2-3 concurrent users

Enterprise Configuration (Heavy Usage)

Component	Specification	Purpose
CPU	16+ cores, server grade	Multiple concurrent requests
RAM	32GB+	Large models (13B+), extensive context
Storage	500GB+ NVMe SSD	Multiple models, large datasets
GPU	RTX 4090 (24GB) or multiple GPUs	Maximum inference speed
Network	Multiple network interfaces	Team sharing, distributed setup

Expected Performance: 13B+ parameter model, 30-100+ tokens/second, 16K+ context, 10+ users

Technology Stack

Core Technologies

• Primary Language: Go 1.21+ (performance, concurrency, simple deployment)
• ML Backend: llama.cpp with Go bindings (GGML/GGUF model support)
• Vector Database: ChromaDB with SQLite backend (embeddings storage)
• Web Framework: Gin framework (HTTP API) + Gorilla WebSocket
• CLI Framework: Cobra (commands) + Viper (configuration)
• Database: SQLite with GORM (metadata, sessions, configuration)
• Containerization: Docker + Docker Compose (easy deployment)

Key Rationale

• Go: Single binary deployment, excellent concurrency, fast compilation
• llama.cpp: Best performance for local LLM inference, active community
• SQLite: Zero-configuration, reliable, perfect for local storage
• ChromaDB: Purpose-built for embeddings, good Go integration

Alternative Technologies Considered

Technology	Pros	Cons	Decision
Python	Rich ML ecosystem	Slower, complex deployment	Rejected
Rust	Maximum performance	Steeper learning curve	Future consideration
PostgreSQL	More features	Requires setup/maintenance	Unnecessary complexity
Weaviate	Advanced vector features	Heavy resource usage	Overkill for local use

Component Specifications

1. Model Server Component

Purpose: Handle LLM inference with optimized performance

Requirements:

• Load GGUF format models (4-bit, 8-bit, 16-bit quantization)
• Support models from 1B to 70B parameters (based on hardware)
• Implement both CPU and GPU inference paths
• Provide streaming and batch inference APIs
• Manage model memory efficiently (load/unload based on usage)
• Support multiple concurrent requests with queueing
• Implement request timeout and cancellation
• Cache frequently used prompts and responses

Interfaces:

• LoadModel(path string, config ModelConfig) error
• GenerateResponse(request InferenceRequest) InferenceResponse
• GenerateStream(request InferenceRequest) <-chan StreamToken
• UnloadModel() error
• GetModelInfo() ModelInfo
• GetPerformanceStats() PerformanceStats

2. Context Manager Component

Purpose: Manage and search through codebase context

Requirements:

• Index files, Git commits, emails, and documents
• Generate embeddings for all content types
• Provide fast similarity search (sub-100ms for 10K documents)
• Rank results by relevance and recency
• Handle real-time file updates
• Support context windows up to 32K tokens
• Implement context compression for large codebases
• Provide context explanations (why something was included)

Interfaces:

• AddContext(item ContextItem) error
• SearchContext(query string, limit int) []ContextResult
• UpdateContext(path string) error
• RemoveContext(path string) error
• GetContextStats() ContextStats
• OptimizeContextStore() error

3. Data Pipeline Component

Purpose: Process various data sources into searchable context

Requirements:

• Git Integration: Parse repositories, extract commits, diffs, messages
• Email Processing: Support mbox/maildir, extract code snippets
• File Processing: Handle 20+ programming languages, extract functions/classes
• Document Processing: Parse markdown, PDFs, text files
• Real-time Monitoring: Watch for file changes, auto-update context
• Batch Processing: Handle large datasets efficiently
• Data Validation: Ensure data quality, detect duplicates
• Format Conversion: Normalize different input formats

Supported File Types:

Programming: .go .py .js .ts .java .cpp .c .rs .rb .php .swift .kt
Markup: .md .html .xml .json .yaml .toml
Documents: .txt .pdf .rtf
Archives: .zip .tar.gz .git
Email: mbox, maildir formats

4. API Gateway Component

Purpose: Provide stable external interfaces

Requirements:

• REST API with OpenAPI 3.0 specification
• WebSocket API for real-time communication
• Request/response logging and metrics
• Rate limiting and abuse prevention
• Input validation and sanitization
• Error handling with meaningful messages
• CORS support for web clients
• Optional authentication/authorization
• API versioning support
• Health check endpoints

5. Storage Layer Component

Purpose: Persist context, configuration, and session data

Requirements:

• Vector Storage: Efficient embedding storage and retrieval
• Metadata Storage: File metadata, timestamps, relationships
• Configuration Storage: User preferences, model settings
• Session Storage: Conversation history, context state
• Cache Storage: Frequently accessed data
• Backup/Restore: Data export/import capabilities
• Migration Support: Schema updates without data loss
• Performance: Sub-10ms queries for common operations

API Specification

Base URL and Versioning

Base URL: http://localhost:8080/api/v1/
WebSocket: ws://localhost:8080/ws/

Authentication

Optional API key authentication:
Header: Authorization: Bearer <api_key>

Core Endpoints

1. Health and Status

GET /health
Response: {
  "status": "healthy",
  "version": "1.0.0", 
  "model_loaded": true,
  "uptime_seconds": 3600,
  "memory_usage_mb": 4096
}

2. Text Generation

POST /generate
Content-Type: application/json

Request Body:
{
  "prompt": "How do I implement a binary search in Go?",
  "max_tokens": 500,
  "temperature": 0.7,
  "top_p": 0.9,
  "top_k": 40,
  "repeat_penalty": 1.1,
  "stop": ["```", "\n\n"],
  "include_context": true,
  "system_prompt": "You are a helpful coding assistant.",
  "stream": false
}

Response:
{
  "id": "gen_123456",
  "text": "Here's how to implement binary search in Go:\n\n```go\nfunc binarySearch(arr []int, target int) int {\n    left, right := 0, len(arr)-1\n    \n    for left <= right {\n        mid := left + (right-left)/2\n        if arr[mid] == target {\n            return mid\n        } else if arr[mid] < target {\n            left = mid + 1\n        } else {\n            right = mid - 1\n        }\n    }\n    return -1\n}\n```",
  "token_count": 87,
  "time_taken_ms": 1250,
  "tokens_per_second": 69.6,
  "context_used": [
    {
      "type": "file",
      "path": "algorithms/search.go", 
      "relevance_score": 0.92,
      "content_preview": "Binary search implementation..."
    }
  ],
  "finished": true
}

3. Streaming Generation

POST /generate/stream
Content-Type: application/json

Same request body as /generate with "stream": true

Response (Server-Sent Events):
data: {"type": "token", "content": "Here's"}
data: {"type": "token", "content": " how"}
data: {"type": "token", "content": " to"}
data: {"type": "context", "items": [...]}
data: {"type": "token", "content": " implement"}
data: {"type": "done", "stats": {"tokens": 87, "time_ms": 1250}}

4. Context Management

POST /context
Content-Type: application/json

Request Body:
{
  "type": "file|git|email|document",
  "path": "/path/to/source",
  "content": "optional content override",
  "metadata": {
    "language": "go",
    "size_bytes": 1024,
    "last_modified": "2024-01-15T10:30:00Z"
  }
}

Response:
{
  "id": "ctx_789",
  "status": "indexed",
  "embedding_id": "emb_456",
  "processing_time_ms": 150
}

5. Context Search

GET /context/search?q=error%20handling&limit=10&type=file

Response:
{
  "query": "error handling",
  "results": [
    {
      "id": "ctx_123",
      "type": "file", 
      "path": "utils/errors.go",
      "content_preview": "Error handling utilities for...",
      "relevance_score": 0.94,
      "metadata": {
        "language": "go",
        "functions": ["HandleError", "WrapError"],
        "last_modified": "2024-01-15T10:30:00Z"
      }
    }
  ],
  "total_results": 25,
  "search_time_ms": 45
}

6. Model Management

GET /models
Response:
{
  "current_model": {
    "name": "codellama-7b-instruct",
    "path": "/models/codellama-7b.gguf", 
    "size_gb": 3.8,
    "parameters": "7B",
    "quantization": "q4_0",
    "context_length": 16384,
    "loaded_at": "2024-01-15T09:00:00Z"
  },
  "available_models": [...]
}

POST /models/load
Request Body: {"model_path": "/path/to/model.gguf"}
Response: {"status": "loading", "estimated_time_seconds": 30}

7. Training Data Management

POST /training/prepare
Request Body:
{
  "sources": [
    {"type": "git", "path": "/path/to/repo"},
    {"type": "email", "path": "/path/to/mailbox"},
    {"type": "files", "path": "/path/to/docs", "pattern": "*.md"}
  ],
  "output_path": "/tmp/training_data.jsonl",
  "format": "instruction_following"
}

Response:
{
  "job_id": "train_prep_001",
  "status": "processing",
  "estimated_examples": 50000,
  "progress_url": "/training/prepare/train_prep_001/status"
}

WebSocket API

// Connection
ws://localhost:8080/ws/chat

// Message format
{
  "type": "chat_message|context_update|model_status",
  "id": "msg_123",
  "content": {...},
  "timestamp": "2024-01-15T10:30:00Z"
}

// Chat message
{
  "type": "chat_message",
  "content": {
    "message": "Explain this function",
    "context": ["file:///path/to/file.go:42-60"],
    "stream": true
  }
}

// Response
{
  "type": "chat_response", 
  "id": "msg_123",
  "content": {
    "text": "This function implements...",
    "partial": false,
    "context_used": [...]
  }
}

Error Responses

Status Codes:
200: Success
400: Bad Request (invalid input)
401: Unauthorized (if auth enabled)
429: Rate Limited
500: Internal Server Error
503: Service Unavailable (model loading)

Error Format:
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Temperature must be between 0 and 2",
    "details": {
      "field": "temperature",
      "provided": 2.5,
      "allowed_range": [0, 2]
    }
  }
}

CLI Interface Specification

Command Structure

del [global-flags] <command> [subcommand] [flags] [arguments]

Global Flags

--config, -c        Config file path (default: ~/.del/config.yaml)
--verbose, -v       Enable verbose logging  
--debug             Enable debug mode
--server, -s        Server URL (default: http://localhost:8080)
--timeout           Request timeout (default: 30s)
--no-color          Disable colored output
--quiet, -q         Suppress non-essential output
--format, -f        Output format: text|json|yaml (default: text)

Server Management Commands

# Start server with various options
del server start [flags]
  --port, -p          Port number (default: 8080)
  --host              Bind address (default: localhost) 
  --model-path        Model file path
  --gpu               Enable GPU acceleration
  --max-memory        Memory limit in GB (default: 8)
  --workers           Number of worker threads (default: auto)
  --cors              Enable CORS (default: true)
  --auth              Enable authentication
  --cert              TLS certificate file
  --key               TLS private key file
  --log-level         Logging level: debug|info|warn|error
  --daemon, -d        Run as daemon
  --pid-file          PID file path (daemon mode)

# Server control
del server stop [--force]
del server restart [start-flags]
del server status [--json]
del server logs [--tail N] [--follow]

Chat and Query Commands

# Single question
del ask "How do I handle errors in Go?" [flags]
  --context           Include context from files/git
  --temperature       Sampling temperature (0.0-2.0)
  --max-tokens        Maximum response tokens
  --system-prompt     Custom system prompt
  --no-stream         Disable streaming output
  --save              Save conversation to file

# Interactive chat mode  
del chat [flags]
  --model             Model to use
  --temperature       Sampling temperature  
  --system-prompt     System prompt file or text
  --context-dir       Directory to use for context
  --load              Load previous conversation
  --save-on-exit      Auto-save on exit

# Code-specific queries
del code [command] [flags]
  explain FILE[:LINES]        Explain code in file/lines
  review FILE                 Review code for issues  
  optimize FILE               Suggest optimizations
  document FUNCTION           Generate documentation
  test FILE                   Generate unit tests
  refactor FILE               Suggest refactoring

  Flags:
  --language, -l      Force language detection
  --context           Include related files
  --output, -o        Output file for generated code
  --diff              Show changes as diff

Context Management Commands

# Add context sources
del context add [type] [path] [flags]
  file PATH                   Add file(s) to context
  git REPO_PATH               Add git repository 
  email MAILBOX_PATH          Add email archive
  url URL                     Add web page/documentation
  
  Flags:
  --recursive, -r     Process directories recursively
  --pattern           File pattern filter (e.g., "*.go")
  --exclude           Exclusion patterns
  --max-size          Maximum file size (default: 1MB)
  --follow-links      Follow symbolic links
  --encoding          Text encoding (default: auto-detect)

# Search and manage context
del context search QUERY [flags]
  --type              Filter by type: file|git|email|url
  --limit, -n         Number of results (default: 10)
  --min-score         Minimum relevance score
  --since             Show items since date/time
  --sort              Sort by: relevance|date|size

del context list [--type TYPE] [--stats]
del context remove PATH [--type TYPE]
del context clear [--type TYPE] [--confirm]
del context rebuild [--force]
del context export FILE [--format json|yaml]
del context import FILE

Model Management Commands

# List and download models
del model list [flags]
  --local             Show only locally available models
  --remote            Show downloadable models
  --size              Include model sizes
  --details           Show detailed information

del model download NAME [flags] 
  --url               Custom download URL
  --quantization      Quantization level: q4_0|q4_1|q5_0|q5_1|q8_0
  --verify            Verify checksum after download
  --resume            Resume interrupted download

# Model operations
del model load PATH [--force]
del model unload
del model info [NAME]
del model test [--prompt "test prompt"]
del model benchmark [--duration 60s]
del model convert INPUT OUTPUT [--quantization q4_0]

Training Commands

# Prepare training data
del train prepare [flags]
  --sources           Source specification file
  --output            Output training file
  --format            Format: alpaca|chatml|instruction
  --max-examples      Maximum training examples
  --validation-split  Validation set percentage
  --shuffle           Shuffle examples
  --deduplicate       Remove duplicate examples

# Run training
del train start CONFIG_FILE [flags]
  --base-model        Base model path
  --output-dir        Training output directory
  --resume            Resume from checkpoint
  --gpu               Enable GPU training
  --wandb             Enable Weights & Biases logging
  --dry-run           Validate config without training

del train status [JOB_ID]
del train stop JOB_ID [--save-checkpoint]
del train logs JOB_ID [--follow]

Configuration Commands

# Configuration management
del config init [--force]
del config show [KEY]
del config set KEY VALUE
del config get KEY  
del config validate
del config reset [--confirm]
del config backup FILE
del config restore FILE

# Common settings
del config set model.default_path ./models/codellama-7b.gguf
del config set server.port 8080
del config set context.max_files 10000
del config set generation.temperature 0.7

Utility Commands

# System information
del info
  --system            Show system capabilities
  --gpu               GPU information
  --models            Installed models
  --context           Context statistics
  --performance       Performance benchmarks

# Maintenance
del doctor                    Check system health
del cleanup [--force]         Clean temporary files
del upgrade [--check-only]    Upgrade to latest version
del export DATA_DIR           Export all data
del import DATA_DIR [--merge] Import data

# Help and documentation
del help [COMMAND]
del version [--full]
del examples [TOPIC]

Shell Integration

Del should provide seamless integration with Unix/Linux shell tools, allowing developers to combine AI assistance with traditional command-line workflows.

Command Execution Modes

1. Direct Shell Commands

# Execute shell commands directly within Del
del exec "ls -la src/"
del exec "grep -r 'TODO' . --include='*.go'"
del exec "find . -name '*.py' | head -10"

# With AI interpretation
del exec "ps aux | grep python" --explain
del exec "netstat -tulpn" --summarize
del exec "docker ps" --analyze

2. AI-Assisted Command Generation

# Generate and optionally execute commands
del suggest "show me all Go files modified in the last week"
# Outputs: find . -name "*.go" -mtime -7
# Prompt: Execute this command? [y/N/e(dit)]

del suggest "find large files over 100MB"
# Outputs: find . -type f -size +100M -exec ls -lh {} \;

del suggest "show git commits from last month with file changes"
# Outputs: git log --since="1 month ago" --stat --oneline

3. Shell Pipeline Integration

# Del as part of Unix pipelines
ls -la | del analyze "what files should I focus on?"
git log --oneline | del summarize
ps aux | del explain "what processes are using most memory?"

# Complex pipelines
find . -name "*.go" | xargs wc -l | del rank "by lines of code"
grep -r "func.*Error" . | del explain "error handling patterns"

4. REPL Shell Integration

# Within Del's interactive mode
> !ls -la src/
drwxr-xr-x  5 user user 4096 Jan 15 10:30 handlers/
-rw-r--r--  1 user user 2048 Jan 15 09:45 main.go
...

> !grep -r "panic" . --include="*.go" | head -5
./handlers/auth.go:45: panic("invalid session")
./utils/db.go:23: // TODO: remove panic for production
...

> explain the last command output
The grep command found 2 instances of "panic" in your Go code:
1. Line 45 in auth.go has an actual panic call - this should be replaced with proper error handling
2. Line 23 in db.go has a TODO comment about removing a panic

Let me suggest safer alternatives for these...

Shell Integration Specifications

Command Execution Component

Purpose: Execute shell commands safely and capture output for AI processing

Requirements:

• Safe Execution: Sandboxed command execution with timeout protection
• Output Capture: Capture stdout, stderr, and exit codes
• Real-time Streaming: Show command output as it executes
• Working Directory: Respect current working directory context
• Environment Variables: Pass through relevant environment variables
• Interactive Commands: Handle commands requiring user input
• Privilege Control: Never execute commands requiring elevated privileges
• Command History: Track executed commands for context

Security Constraints:

Blocked Commands:
  - sudo, su, doas (privilege escalation)
  - rm -rf /, mkfs (destructive operations)  
  - dd, shred (disk operations)
  - chmod 777, chown (permission changes)
  - curl/wget to unknown domains (network security)
  - eval, exec with untrusted input

Restricted Commands:
  - git push (require confirmation)
  - rm (require confirmation for multiple files)
  - mv, cp (confirm overwrite operations)
  - docker run (limit resource usage)

Time Limits:
  - Default timeout: 30 seconds
  - Long-running commands: 5 minutes with confirmation
  - Interactive commands: 2 minutes timeout

Command Suggestion Engine

Purpose: Generate shell commands from natural language descriptions

Requirements:

• Context Awareness: Understand current directory, file types, project structure
• Platform Detection: Generate appropriate commands for Linux/macOS/Windows
• Safety Validation: Never suggest dangerous or destructive commands
• Command Explanation: Explain what generated commands do
• Alternative Options: Provide multiple command options when possible
• Learning: Learn from user corrections and preferences

Training Data Sources:

Command Examples:
  - Common shell command patterns
  - Stack Overflow command snippets  
  - GitHub repository scripts
  - Unix manual pages and examples
  - User's command history (with permission)

Pattern Recognition:
  - "find files" → find, ls, locate commands
  - "search content" → grep, ag, ripgrep commands
  - "git operations" → git command variations
  - "process management" → ps, kill, jobs commands
  - "file operations" → cp, mv, chmod, tar commands

Command Categories and Examples

File and Directory Operations

# Natural language → Generated commands
"show me all Python files in this project"
→ find . -name "*.py" -type f

"find large files taking up space"  
→ find . -type f -size +10M -exec ls -lh {} \; | sort -k5 -hr

"list files modified today"
→ find . -type f -newermt "today" -ls

"count lines of code in each directory"
→ find . -name "*.go" -exec wc -l {} \; | awk '{sum+=$1} END {print sum}'

Text Processing and Search

"find all TODO comments in Go files"
→ grep -rn "TODO\|FIXME\|XXX" --include="*.go" .

"show functions that return errors"
→ grep -rn "func.*error" --include="*.go" .

"find duplicate function names"
→ grep -rh "^func " --include="*.go" . | sort | uniq -d

"extract email addresses from logs"
→ grep -oE '\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b' *.log

Git Operations

"show commits from last week"
→ git log --since="1 week ago" --oneline

"find who changed this line"
→ git blame -L 45,45 src/main.go

"show files changed in last commit"
→ git diff --name-only HEAD~1

"find commits that mention 'bug'"
→ git log --grep="bug" --oneline

System Monitoring

"show processes using most CPU"
→ ps aux --sort=-%cpu | head -10

"check disk usage by directory"
→ du -sh */ | sort -hr

"show network connections"
→ netstat -tuln

"monitor log file for errors"
→ tail -f /var/log/app.log | grep -i error

Development Tools

"run tests and show coverage"
→ go test -coverprofile=coverage.out ./... && go tool cover -html=coverage.out

"format all Go code"
→ find . -name "*.go" -exec gofmt -w {} \;

"check for security vulnerabilities"
→ gosec ./...

"build for multiple platforms"
→ GOOS=linux GOARCH=amd64 go build -o myapp-linux ./cmd/

REPL Shell Integration

Shell Command Syntax in REPL

# Prefix commands with ! for execution
> !ls -la
> !grep -r "func main" .
> !git status

# Multi-line shell commands
> !for file in *.go; do
... echo "Processing $file"
... go fmt "$file"
... done

# Combine with AI analysis
> !docker ps
> explain what these containers do

# Store command output for analysis
> $output = !ps aux
> analyze $output for memory usage patterns

Interactive Command Building

# Step-by-step command construction
> build command to find large files
Del: I'll help you build a command to find large files. Let me ask a few questions:

1. What size threshold? (e.g., >100MB)
> 50MB

2. Which directory to search?
> current directory and subdirectories

3. Should I show file sizes?
> yes

Generated command: find . -type f -size +50M -exec ls -lh {} \;
Execute this command? [y/N/e(dit)/s(ave)]
> y

[Command executes and shows results]

Would you like me to explain what each part does?

Command History and Favorites

# Show recent shell commands
> :history shell
1. ls -la src/
2. grep -r "TODO" . --include="*.go"  
3. git log --oneline | head -10
4. docker ps

# Save frequently used commands
> :save-command "show-todos" "grep -r 'TODO\|FIXME' --include='*.go' ."
> :run show-todos

# Command aliases for complex operations
> :alias disk-usage "du -sh */ | sort -hr"
> !disk-usage

API Endpoints for Shell Integration

Execute Shell Command

POST /api/v1/shell/execute
Content-Type: application/json

Request:
{
  "command": "ls -la src/",
  "working_directory": "/path/to/project",
  "timeout_seconds": 30,
  "capture_output": true,
  "environment": {
    "GOPATH": "/go",
    "PATH": "/usr/local/bin:/usr/bin:/bin"
  }
}

Response:
{
  "command": "ls -la src/",
  "exit_code": 0,
  "stdout": "drwxr-xr-x 5 user user 4096 Jan 15 10:30 handlers/\n-rw-r--r-- 1 user user 2048 Jan 15 09:45 main.go\n",
  "stderr": "",
  "execution_time_ms": 45,
  "working_directory": "/path/to/project"
}

Generate Shell Command

POST /api/v1/shell/suggest
Content-Type: application/json

Request:
{
  "description": "find all Go files modified in the last 24 hours",
  "context": {
    "operating_system": "linux",
    "current_directory": "/path/to/project",
    "available_tools": ["find", "grep", "git"],
    "project_type": "go"
  }
}

Response:
{
  "suggestions": [
    {
      "command": "find . -name '*.go' -mtime -1",
      "explanation": "Find all .go files modified in the last 24 hours",
      "confidence": 0.95,
      "safety_level": "safe"
    },
    {
      "command": "git log --since='24 hours ago' --name-only --pretty=format: | grep '\\.go

### Command Examples
```bash
# Quick start
del model download codellama-7b-instruct
del server start --port 8080 --gpu
del context add git .
del ask "How does the authentication work in this codebase?"

# Development workflow
del chat --context-dir ./src --save-on-exit
> How can I optimize the database queries in user.go?
> Generate unit tests for the UserService class
> Explain the dependency injection pattern used here

# Code review workflow  
del context add git . --since "24 hours ago"
del code review src/handlers/auth.go
del code explain src/models/user.go:45-67
del code test src/services/email.go --output tests/

# Training custom model
del train prepare --sources training_sources.yaml --output training.jsonl
del train start training_config.yaml --gpu --wandb
del model load ./fine_tuned_model/model.gguf

REPL Requirements

Interactive Mode Features

The REPL (Read-Eval-Print Loop) should provide an interactive chat interface with the following capabilities:

Core REPL Commands

# Enter interactive mode
del chat

# REPL-specific commands (prefixed with : or /)
:help, :h                   Show available commands
:quit, :q, :exit           Exit REPL  
:clear, :cls               Clear screen
:history                   Show command history
:save [filename]           Save conversation
:load filename             Load conversation
:context                   Show current context
:model                     Show current model info
:stats                     Show session statistics
:reset                     Reset conversation
:set key=value             Change settings
:get key                   Show setting value
:debug                     Toggle debug mode

Multi-line Input Support

# Automatic multi-line detection
> def fibonacci(n):
... if n <= 1:
...     return n
... return fibonacci(n-1) + fibonacci(n-2)
... 
[Generated response]

# Explicit multi-line mode
> ```
... This is a multi-line
... input that continues
... until I type ```

Context Integration

# File reference
> @file:src/main.go explain this function

# Line range reference  
> @src/auth.go:42-58 how can I improve this?

# Git commit reference
> @commit:abc123 what changed in this commit?

# Auto-complete suggestions
> @src/[TAB]
src/main.go  src/auth.go  src/utils.go

# Context shortcuts
> /explain              # Explain current file/selection
> /review               # Review current file  
> /optimize             # Suggest optimizations
> /document             # Generate documentation
> /test                 # Generate tests

Advanced Features

# Code mode - specialized for code questions
> /code
Code mode enabled. Ask about code, get code responses.
code> implement binary search in rust

# Conversation modes
> /mode explain         # Explanation-focused responses
> /mode debug           # Debugging assistance  
> /mode review          # Code review mode
> /mode teach           # Educational responses

# Session management
> /save important_discussion
Saved conversation to important_discussion.chat

> /load important_discussion  
Loaded conversation from important_discussion.chat

Visual Enhancements

• Syntax Highlighting: Color-coded code in responses
• Progress Indicators: Show when model is thinking
• Token Streaming: Display responses as they generate
• Context Previews: Show what context is being used
• Error Formatting: Clear error messages with suggestions

Example REPL Session

$ del chat --context-dir ./myproject
Del the Funky Robosapien v1.0.0 (codellama-7b-instruct)
Context: 1,247 files indexed from ./myproject
Type :help for commands or start chatting!

> I'm getting a panic in my Go code, can you help debug it?

I'd be happy to help debug your Go panic! Could you share the panic 
message and the relevant code? You can reference files directly like 
@file:path/to/file.go or paste the error message.

> @file:src/handlers/user.go the panic happens around line 45

[Loading src/handlers/user.go...]

Looking at your user.go file around line 45, I can see the issue. You have:

```go
user := users[id]  // Line 45
return user.Name   // This panics if user is nil

The panic occurs because you’re not checking if the user exists in the map before accessing its fields. Here’s the fix:

user, exists := users[id]
if !exists {
    return "", fmt.Errorf("user with id %s not found", id)
}
return user.Name, nil

This uses the two-value assignment to check if the key exists in the map.

That makes sense! Are there other similar patterns in my codebase?

Let me search for similar patterns in your codebase…

[Context: Searching 1,247 files for map access patterns]

I found 3 other locations with similar unsafe map access:

1. src/handlers/auth.go:23 - sessions[sessionID].UserID
2. src/models/cache.go:67 - cache[key].Data
3. src/utils/config.go:12 - settings[param].Value

Would you like me to show you how to fix each of these?

:save debugging_session Saved conversation to debugging_session.chat

:quit Goodbye! Your conversation was saved.

      "explanation": "Use git to find Go files changed in last 24 hours (only if files are tracked)",
      "confidence": 0.87,
      "safety_level": "safe"
    }
  ]
}

Configuration Options

Shell Integration Settings

# ~/.del/config.yaml
shell:
  # Enable/disable shell integration
  enabled: true
  
  # Default shell to use
  default_shell: "/bin/bash"
  
  # Command timeout settings
  timeouts:
    default: 30s
    interactive: 120s
    long_running: 300s
  
  # Safety settings
  safety:
    require_confirmation:
      - "rm *"
      - "git push"
      - "docker run"
    
    blocked_commands:
      - "sudo"
      - "rm -rf /"
      - "mkfs"
      - "dd if="
    
    blocked_patterns:
      - "curl.*|.*sh"  # Prevent pipe to shell
      - "wget.*|.*bash"
  
  # Command suggestion settings
  suggestions:
    enabled: true
    max_suggestions: 3
    learn_from_usage: true
    
  # History settings  
  history:
    enabled: true
    max_entries: 1000
    file: "~/.del/shell_history"

This shell integration makes Del incredibly powerful by combining AI assistance with the full Unix toolchain that developers already know and love!

Command Examples

# Quick start
del model download codellama-7b-instruct
del server start --port 8080 --gpu
del context add git .
del ask "How does the authentication work in this codebase?"

# Development workflow
del chat --context-dir ./src --save-on-exit
> How can I optimize the database queries in user.go?
> Generate unit tests for the UserService class
> Explain the dependency injection pattern used here

# Code review workflow  
del context add git . --since "24 hours ago"
del code review src/handlers/auth.go
del code explain src/models/user.go:45-67
del code test src/services/email.go --output tests/

# Training custom model
del train prepare --sources training_sources.yaml --output training.jsonl
del train start training_config.yaml --gpu --wandb
del model load ./fine_tuned_model/model.gguf

REPL Requirements

Interactive Mode Features

The REPL (Read-Eval-Print Loop) should provide an interactive chat interface with the following capabilities:

Core REPL Commands

# Enter interactive mode
del chat

# REPL-specific commands (prefixed with : or /)
:help, :h                   Show available commands
:quit, :q, :exit           Exit REPL  
:clear, :cls               Clear screen
:history                   Show command history
:save [filename]           Save conversation
:load filename             Load conversation
:context                   Show current context
:model                     Show current model info
:stats                     Show session statistics
:reset                     Reset conversation
:set key=value             Change settings
:get key                   Show setting value
:debug                     Toggle debug mode

Multi-line Input Support

# Automatic multi-line detection
> def fibonacci(n):
... if n <= 1:
...     return n
... return fibonacci(n-1) + fibonacci(n-2)
... 
[Generated response]

# Explicit multi-line mode
> ```
... This is a multi-line
... input that continues
... until I type ```

Context Integration

# File reference
> @file:src/main.go explain this function

# Line range reference  
> @src/auth.go:42-58 how can I improve this?

# Git commit reference
> @commit:abc123 what changed in this commit?

# Auto-complete suggestions
> @src/[TAB]
src/main.go  src/auth.go  src/utils.go

# Context shortcuts
> /explain              # Explain current file/selection
> /review               # Review current file  
> /optimize             # Suggest optimizations
> /document             # Generate documentation
> /test                 # Generate tests

Advanced Features

# Code mode - specialized for code questions
> /code
Code mode enabled. Ask about code, get code responses.
code> implement binary search in rust

# Conversation modes
> /mode explain         # Explanation-focused responses
> /mode debug           # Debugging assistance  
> /mode review          # Code review mode
> /mode teach           # Educational responses

# Session management
> /save important_discussion
Saved conversation to important_discussion.chat

> /load important_discussion  
Loaded conversation from important_discussion.chat

Visual Enhancements

• Syntax Highlighting: Color-coded code in responses
• Progress Indicators: Show when model is thinking
• Token Streaming: Display responses as they generate
• Context Previews: Show what context is being used
• Error Formatting: Clear error messages with suggestions

Example REPL Session

$ del chat --context-dir ./myproject
Del the Funky Robosapien v1.0.0 (codellama-7b-instruct)
Context: 1,247 files indexed from ./myproject
Type :help for commands or start chatting!

> I'm getting a panic in my Go code, can you help debug it?

I'd be happy to help debug your Go panic! Could you share the panic 
message and the relevant code? You can reference files directly like 
@file:path/to/file.go or paste the error message.

> @file:src/handlers/user.go the panic happens around line 45

[Loading src/handlers/user.go...]

Looking at your user.go file around line 45, I can see the issue. You have:

```go
user := users[id]  // Line 45
return user.Name   // This panics if user is nil

The panic occurs because you’re not checking if the user exists in the map before accessing its fields. Here’s the fix:

user, exists := users[id]
if !exists {
    return "", fmt.Errorf("user with id %s not found", id)
}
return user.Name, nil

This uses the two-value assignment to check if the key exists in the map.

That makes sense! Are there other similar patterns in my codebase?

Let me search for similar patterns in your codebase…

[Context: Searching 1,247 files for map access patterns]

I found 3 other locations with similar unsafe map access:

1. src/handlers/auth.go:23 - sessions[sessionID].UserID
2. src/models/cache.go:67 - cache[key].Data
3. src/utils/config.go:12 - settings[param].Value

Would you like me to show you how to fix each of these?

:save debugging_session Saved conversation to debugging_session.chat

:quit Goodbye! Your conversation was saved.