Sofos Code

 

A blazingly fast, interactive AI coding assistant powered by Claude or GPT, implemented in pure Rust, that can generate code, edit files, and search the web - all from your terminal.

Tested on macOS but should work on Linux and Windows as well.

Table of Contents

• Features
• Installation
• Usage
  • Quick Start
  • Commands
  • Image Vision
  • Cost Tracking
  • CLI Options
  • Extended Thinking
• Custom Instructions
• Session History
• Available Tools
• MCP Servers
• Security
  • Configuration
• Development
• Troubleshooting
• Morph Integration
• License
• Acknowledgments
• Links & Resources

Features

• Interactive REPL - Multi-turn conversations with Claude or GPT
• Markdown Formatting - AI responses with syntax highlighting for code blocks
• Image Vision - Analyze local or web images
• Session History - Auto-save and resume conversations
• Custom Instructions - Project and personal context files
• File Operations - Read, write, list, create (sandboxed)
• Ultra-Fast Editing - Optional Morph Apply integration (10,500+ tokens/sec)
• Code Search - Fast regex search with ripgrep
• Web Search - Real-time info via Claude's/OpenAI's native search
• Bash Execution - Run tests and builds (read-only, sandboxed)
• Visual Diffs - Colored change display
• Iterative Tools - Up to 200 tool calls per request
• Cost Tracking - Session token usage and cost estimates
• Safe Mode - Read-only operation mode

Installation

Requirements: Anthropic API key (get one) or OpenAI API key (get one)

Optional (but highly recommended): ripgrep for code search (install), Morph API key for ultra-fast editing (get one)

Install:

# Homebrew (could be behind `cargo install`)
brew tap alexylon/tap && brew install sofos

# Cargo (requires Rust 1.70+)
cargo install sofos

# From source
git clone https://github.com/alexylon/sofos-code.git
cd sofos-code && cargo install --path .

Important: Add .sofos/ to .gitignore (contains session history and personal settings). Keep .sofosrc (team-wide instructions).

Usage

Quick Start

# Set your API key (choose one)
export ANTHROPIC_API_KEY='your-anthropic-key'
# or
export OPENAI_API_KEY='your-openai-key'

# Optional: Enable ultra-fast editing
export MORPH_API_KEY='your-morph-key'

# Start Sofos
sofos

Commands

• /resume - Resume previous session
• /clear - Clear conversation history
• /think [on|off] - Toggle extended thinking (shows status if no arg)
• /s - Safe mode (read-only, prompt: λ:, blinking underscore (_) cursor)
• /n - Normal mode (all tools, prompt: λ>, default cursor)
• /exit, /quit, /q, Ctrl+D - Exit with cost summary
• ESC - Interrupt AI response

Tab completion: Press Tab for command suggestions, Shift+Tab to navigate backwards.

Image Vision

Include image paths or URLs directly in your message:

# Local images
What's in this screenshot.png?
Describe ./images/diagram.jpg

# Paths with spaces - use quotes
What do you see in "/Users/alex/Documents/my image.png"?

# Web images
Analyze https://example.com/chart.png

Formats: JPEG, PNG, GIF, WebP (max 20MB local) | Spaces: Wrap in quotes "path/with space.png" | Permissions: Outside workspace requires config

Cost Tracking

Exit summary shows token usage and estimated cost (based on official API pricing).

CLI Options

-p, --prompt <TEXT>          One-shot mode
-s, --safe-mode              Start in read-only mode (only read/list/web-search/image tools; no writes or bash commands)
-r, --resume                 Resume a previous session
    --api-key <KEY>          Anthropic API key (overrides env var)
    --openai-api-key <KEY>   OpenAI API key (overrides env var)
    --morph-api-key <KEY>    Morph API key (overrides env var)
    --model <MODEL>          Model to use (default: claude-sonnet-4-5)
    --morph-model <MODEL>    Morph model (default: morph-v3-fast)
    --max-tokens <N>         Max response tokens (default: 8192)
-t, --enable-thinking        Enable extended thinking (default: false)
    --thinking-budget <N>    Token budget for thinking (Claude only, default: 5120, must be < max-tokens)
-v, --verbose                Verbose logging

Extended Thinking

Enable for complex reasoning tasks (disabled by default):

sofos -t                                             # Default 5120 token budget (Claude only)
sofos -t --thinking-budget 10000 --max-tokens 16000  # Custom budget (Claude only)

Note: Extended thinking works with both Claude and OpenAI models. For Claude, it enables the thinking protocol and --thinking-budget controls token allocation. For OpenAI (gpt-5 models), /think on sets high reasoning effort and /think off sets low reasoning effort. The --thinking-budget parameter only applies to Claude models.

Custom Instructions

.sofosrc (project root, version controlled) - Team-wide conventions, architecture
.sofos/instructions.md (gitignored) - Personal preferences

Both loaded at startup and appended to system prompt.

Session History

Conversations auto-saved to .sofos/sessions/. Resume with sofos -r or /resume.

Available Tools

File Operations:

• read_file - Read file contents
• write_file - Create or overwrite files
• morph_edit_file - Ultra-fast code editing (requires MORPH_API_KEY)
• list_directory - List directory contents
• create_directory, delete_file, delete_directory, move_file, copy_file - Standard file ops

Code & Search:

• search_code - Fast regex-based code search (requires ripgrep)
• web_search - Real-time web information via Claude's/OpenAI's native search
• execute_bash - Run tests and build commands (read-only, sandboxed)

Image Vision:

• image - View and analyze images (JPEG, PNG, GIF, WebP)

MCP Tools:

• Tools from configured MCP servers (prefixed with server name, e.g., filesystem_read_file)

Note: Only read_file, list_directory, and image can access paths outside workspace when explicitly allowed in config. All other operations are workspace-only.

Safe mode (--safe-mode or /s) restricts to: list_directory, read_file, web_search, image.

MCP Servers

Connect to external tools via MCP (Model Context Protocol). Configure in ~/.sofos/config.toml or .sofos/config.local.toml (see the example in the "Configuration" section).

Tools auto-discovered, prefixed with server name (e.g., filesystem_read_file). See examples/mcp_quickstart.md.

Popular servers: https://github.com/modelcontextprotocol/servers

Security

Sandboxing (by default):

• ✅ Full access to workspace files/directories
• ✅ Read-only access to outside workspace (requires explicit config)
• ❌ No writes, moves, or deletes outside workspace
• ❌ Bash always sandboxed to workspace

Bash Permissions (3-Tier System):

1. Allowed (auto-execute): Build tools (cargo, npm, go), read-only commands (ls, cat, grep), system info (pwd, date), git read-only
2. Forbidden (always blocked): rm, mv, cp, chmod, sudo, mkdir, cd, kill, shutdown
3. Ask (prompt user): Unknown commands require approval; can be remembered in config

Configuration

Permissions are stored in .sofos/config.local.toml (workspace-specific, gitignored) or ~/.sofos/config.toml (global, optional). Local config overrides global.

Example:

[permissions]
allow = [
  # Read permissions - for accessing files/directories outside workspace
  "Read(~/.zshrc)",           # Specific file
  "Read(~/.config/**)",       # Recursive
  "Read(/etc/hosts)",         # Absolute path
  
  # Bash permissions - for command execution
  "Bash(custom_command)",
  "Bash(pattern:*)",
]

deny = [
  # Read denials
  "Read(./.env)",
  "Read(./.env.*)",
  "Read(./secrets/**)",
  
  # Bash denials
  "Bash(dangerous_command)",
]

ask = [
  # Only for Bash commands (prompts for approval)
  "Bash(unknown_tool)",
]

[mcpServers.company-internal]
command = "/usr/local/bin/company-mcp-server"
args = ["--config", "/etc/company/mcp-config.json"]
env = { "COMPANY_API_URL" = "https://internal.company.com" }

[mcpServers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]

[mcpServers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { "GITHUB_TOKEN" = "ghp_YOUR_TOKEN" }

[mcpServers.api]
url = "https://api.example.com/mcp"
headers = { "Authorization" = "Bearer token123" }

Rules:

• Workspace files: allowed by default unless in deny list
• Outside workspace: denied by default unless in allow list
• Glob patterns supported: * (single level), ** (recursive)
• Tilde expansion: ~ → home directory
• ask only works for Bash commands, not Read permissions

Development

cargo test                    # Run tests
cargo build --release         # Build release
RUST_LOG=debug sofos          # Debug logging

Structure:

src/
├── main.rs              # Entry point
├── cli.rs               # CLI argument parsing
├── error.rs             # Error types
├── error_ext.rs         # Error extensions
├── config.rs            # Configuration (SofosConfig, ModelConfig)
│
├── api/                 # API clients
│   ├── anthropic.rs     # Claude API client
│   ├── openai.rs        # OpenAI API client
│   ├── morph.rs         # Morph Apply API client
│   ├── types.rs         # Message types and serialization
│   └── utils.rs         # API utilities
│
├── mcp/                 # MCP (Model Context Protocol) integration
│   ├── mod.rs           # MCP module exports
│   ├── config.rs        # MCP server configuration loading
│   ├── protocol.rs      # MCP protocol types (JSON-RPC, tools)
│   ├── client.rs        # MCP client implementations (stdio, HTTP)
│   └── manager.rs       # MCP server connection management
│
├── repl/                # REPL components
│   ├── mod.rs           # Main REPL loop
│   ├── conversation.rs  # Message history management
│   ├── prompt.rs        # Prompt rendering
│   ├── request_builder.rs   # API request construction
│   └── response_handler.rs  # Response processing
│
├── session/             # Session management
│   ├── history.rs       # Session persistence
│   ├── state.rs         # Runtime session state
│   └── selector.rs      # Session selection TUI
│
├── tools/               # Tool implementations
│   ├── filesystem.rs    # File operations
│   ├── bashexec.rs      # Bash execution
│   ├── codesearch.rs    # Code search (ripgrep)
│   ├── image.rs         # Image handling
│   ├── permissions.rs   # Permission system
│   ├── types.rs         # Tool definitions
│   └── utils.rs         # Tool utilities
│
├── ui/                  # UI components
│   ├── mod.rs           # Main UI utilities
│   ├── syntax.rs        # Syntax highlighting
│   └── diff.rs          # Diff generation
│
└── commands/            # Built-in commands
    └── builtin.rs       # Command implementations

See .sofosrc for detailed conventions.

Troubleshooting

• API errors: Check connection and API key
• Path errors: Use relative paths for workspace, or add Read(path) to config for outside access
• Build errors: rustup update && cargo clean && cargo build
• Images with spaces: Wrap path in quotes

Morph Integration

Optional ultra-fast code editing via Morph Apply API (10,500+ tokens/sec, 96-98% accuracy). Enable with MORPH_API_KEY.

License

MIT License

Acknowledgments

Built with Rust and powered by Anthropic's Claude or OpenAI's GPT. Morph Apply integration for fast edits. Inspired by Aider and similar tools.

Links & Resources

• GitHub
• Crates.io

---

Disclaimer: Sofos Code may make mistakes. Always review generated code before use.