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; supported on Linux and Windows.

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

• Interactive TUI - Multi-turn conversations with Claude or GPT in an inline viewport at the bottom of your terminal; your emulator owns the scrollback, scrollbar, mouse wheel, and copy-paste
• Keep Typing During AI Turns - Messages queue FIFO while the model works; mid tool-loop messages steer the current turn without interrupting
• Live Status Line - Model, mode, reasoning config, and running token totals shown under the input
• Markdown Formatting - AI responses with syntax highlighting for code blocks
• Image Vision - Analyze local or web images, paste from clipboard with Ctrl+V
• Session History - Auto-save with an in-TUI resume picker (/resume or sofos -r)
• Custom Instructions - Project and personal context files
• File Operations - Read, write, edit, list, glob, create, move, copy, delete (sandboxed; external paths via permission grants)
• Targeted Edits - Diff-based edit_file for precise string replacements
• Ultra-Fast Editing - Optional Morph Apply integration (10,500+ tokens/sec)
• File Search - Find files by glob pattern (**/*.rs)
• Code Search - Fast regex search with ripgrep
• Web Search - Real-time info via Claude's/OpenAI's native search
• Web Fetch - Read documentation and web pages
• Bash Execution - Run tests and builds, sandboxed behind a 3-tier permission system
• MCP Integration - Connect to external tools via Model Context Protocol
• Visual Diffs - Syntax-highlighted diffs with line numbers
• Iterative Tools - Up to 200 tool calls per request
• Context Compaction - Summarizes older messages instead of dropping them
• Cost Tracking - Session token usage and cost estimates
• Safe Mode - Read-only operation mode

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)

Download from GitHub Releases (macOS, Linux, Windows):

# macOS / Linux
tar xzf sofos-*.tar.gz
sudo mv sofos /usr/local/bin/

# Windows — extract the .zip, then add the folder to your PATH

macOS: On first run, macOS may block the binary. Go to System Settings → Privacy & Security and click Allow Anyway.

cargo install sofos

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 AGENTS.md (team-wide instructions).

# 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

• /resume - Resume previous session
• /clear - Clear conversation history
• /think [on|off] - Toggle extended thinking (shows status if no arg)
• /compact - Summarize older messages via the LLM to reclaim context tokens (auto-triggers at 80% usage)
• /s - Safe mode (read-only, prompt: :)
• /n - Normal mode (all tools, prompt: >)
• /exit, /quit, /q, Ctrl+D - Exit with cost summary
• ESC or Ctrl+C (while busy) - Interrupt AI response

Message queueing: Keep typing while the AI is working. Pressing Enter queues the message; queued messages are sent automatically once the current turn finishes. The hint line shows the queue count.

Multi-line input: Shift+Enter inserts a newline; Enter alone submits.

Scrollback: Sofos runs as an inline viewport at the bottom of your terminal — the rest of the terminal is normal scrollback, so use your terminal emulator's own scrollbar, mouse wheel, and text selection / copy-paste.

Status line: Shown below the input box. Updates live as you change state (/s, /n, /think) — model, mode (normal/safe), reasoning config (thinking: <N> tok / effort: high), and running token totals.

Include image paths or URLs directly in your message, or paste images from clipboard:

# Paste from clipboard
Ctrl+V                        # Shows ① marker, paste multiple for ①②③
                               # Delete a marker to remove that image

# 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) | Clipboard: Ctrl+V pastes images on macOS, Linux, and Windows | Spaces: Wrap in quotes "path/with space.png" | Permissions: Outside workspace requires config

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

-p, --prompt <TEXT>          One-shot mode
-s, --safe-mode              Start in read-only mode (native writes and bash disabled)
-r, --resume                 Resume a previous session
    --check-connection       Check API connectivity and exit
    --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-6)
    --morph-model <MODEL>    Morph model (default: morph-v3-fast)
    --max-tokens <N>         Max response tokens (default: 32768)
-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

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.

Two files are loaded at startup and appended to the system prompt:

• AGENTS.md (project root, version controlled) — project context for AI agents: team-wide conventions, architecture, domain vocabulary.
• .sofos/instructions.md (gitignored) — personal preferences that shouldn't be shared with the team.

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

File Operations (accept absolute and ~/ paths with a Read or Write grant as appropriate — see Security and Configuration):

• read_file - Read file contents
• list_directory - List a single directory's contents
• glob_files - Find files recursively by glob pattern (**/*.rs, src/**/test_*.py)
• write_file - Create or overwrite files (append mode for chunked writes)
• edit_file - Targeted string replacement edits (no API key needed)
• morph_edit_file - Ultra-fast code editing (requires MORPH_API_KEY)
• create_directory - Create a directory (and missing parents)
• move_file, copy_file - Move or copy files

Workspace-only file ops (absolute / ~/ paths are rejected, even with grants — destructive ops are deliberately scoped to the workspace):

• delete_file, delete_directory - Delete files or directories (prompt for confirmation)

Code & Search:

• search_code - Fast regex-based code search (requires ripgrep)
• web_search - Real-time web information via Claude's/OpenAI's native search
• web_fetch - Fetch URL content as readable text (documentation, APIs)
• execute_bash - Run bash commands, sandboxed through the 3-tier permission system (safe commands auto-run, destructive ones blocked, unknown ones prompt)

MCP Tools:

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

Image Vision: not a tool — sofos detects image paths (JPEG, PNG, GIF, WebP, up to 20 MB local) in your user messages and loads them automatically as image content blocks. Clipboard paste (Ctrl+V) works the same way. See Image Vision under Usage.

Note: Tools can access paths outside the workspace when allowed via interactive prompt or config. Three independent scopes (Read / Write / Bash) gate this access — see Security for the full model.

Safe mode (--safe-mode or /s) restricts the native tool set to read-only operations: list_directory, read_file, glob_files, web_fetch, web_search (Anthropic + OpenAI provider-native variants), and search_code when ripgrep is available. MCP tools are not filtered by safe mode — if you've configured MCP servers with mutating tools, those remain available.

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

Sandboxing (by default):

• ✅ Full access to workspace files/directories
• ✅ External access via interactive prompts — user is asked to allow/deny, with option to remember in config
• Three separate scopes: Read (read/list), Write (write/create/move/delete), Bash (commands with external paths)
• Each scope is independently granted — Read access does not imply Write or Bash access, and vice versa
• Tools that both read and write a file on external paths (edit_file, morph_edit_file) require both Read and Write grants on the path

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 commands (status, log, diff, show, branch, …).
2. Forbidden (always blocked): file destruction (rm, rmdir, touch, ln); permissions (chmod, chown, chgrp); disk / partition (dd, mkfs, fdisk, parted, mkswap, mount, umount); system control (shutdown, reboot, halt, systemctl, service); user management (useradd, usermod, passwd, …); process signals (kill, killall, pkill); privilege escalation (sudo, su); directory navigation (cd, pushd, popd); destructive git operations (git push, git reset --hard, git clean, git checkout -f, git checkout -b, git switch, git rebase, git commit, …).
3. Ask (prompt user): cp, mv, mkdir, git checkout <branch> / git checkout HEAD~N / git checkout -- <path>, commands referencing paths outside the workspace, and any unknown command. Approvals can be session-scoped or remembered in config.

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 reading/listing files outside workspace
  "Read(~/.zshrc)",           # Specific file
  "Read(~/.config/**)",       # Recursive
  "Read(/etc/hosts)",         # Absolute path
  
  # Write permissions - for writing/editing files outside workspace
  "Write(/tmp/output/**)",    # Allow writes to specific external dir
  
  # Bash path permissions - for commands referencing external paths
  "Bash(/var/log/**)",        # Allow bash commands to access this dir
  
  # Bash command permissions - for command execution
  "Bash(custom_command)",     # Specific command
  "Bash(pattern:*)",          # Wildcard 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)",
]

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

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

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

Rules*:

• Workspace files: allowed by default unless in deny list
• Outside workspace: prompts interactively on first access, or pre-configure in allow list
• Three scopes: Read(path) for reading, Write(path) for writing, Bash(path) for bash access — each independent
• Bash(path) entries with globs (e.g. Bash(/tmp/**)) grant path access; plain entries (e.g. Bash(npm test)) grant command access
• Glob patterns supported: * (single level), ** (recursive)
• Tilde expansion: ~ → $HOME on Unix, %USERPROFILE% on Windows
• ask only works for Bash commands

* These rules do not restrict MCP server command paths

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
├── clipboard.rs         # Clipboard image paste (Ctrl+V)
├── error.rs             # Error types
├── error_ext.rs         # Error extensions
├── config.rs            # Configuration
│
├── api/                 # API clients
│   ├── anthropic.rs     # Claude API client (+ streaming)
│   ├── openai.rs        # OpenAI API client
│   ├── morph.rs         # Morph Apply API client
│   ├── types.rs         # Message types and serialization
│   └── utils.rs         # Retries, error handling
│
├── mcp/                 # MCP (Model Context Protocol)
│   ├── config.rs        # Server configuration loading
│   ├── protocol.rs      # Protocol types (JSON-RPC)
│   ├── client.rs        # Client implementations (stdio, HTTP)
│   └── manager.rs       # Server connection management
│
├── repl/                # REPL components
│   ├── mod.rs           # Core Repl state and process_message
│   ├── conversation.rs  # Message history and compaction
│   ├── request_builder.rs   # API request construction
│   ├── response_handler.rs  # Response and tool iteration
│   └── tui/             # Ratatui front end
│       ├── mod.rs             # Event loop and wiring
│       ├── app.rs             # UI state (log, input, queue, picker)
│       ├── ui.rs              # Rendering
│       ├── event.rs           # Job / UiEvent channel payloads
│       ├── worker.rs          # Background thread that owns the Repl
│       ├── output.rs          # Stdout/stderr capture via dup2
│       ├── inline_terminal.rs # Custom ratatui Terminal (resize-safe)
│       ├── inline_tui.rs      # Frame driver and history log
│       ├── scrollback.rs      # DECSTBM-based insert-above-viewport
│       └── sgr.rs             # SGR escape helpers
│
├── session/             # Session management
│   ├── history.rs       # Session persistence
│   ├── state.rs         # Runtime session state
│   └── selector.rs      # Session selection TUI
│
├── tools/               # Tool implementations
│   ├── filesystem.rs    # File operations (read, write, edit, chunked append)
│   ├── bashexec.rs      # Bash execution + confirmation gate
│   ├── codesearch.rs    # Code search (ripgrep)
│   ├── image.rs         # Image detection + loading for message content
│   ├── permissions.rs   # 3-tier permission system
│   ├── tool_name.rs     # Type-safe tool name enum
│   ├── types.rs         # Tool definitions for the API
│   ├── utils.rs         # Confirmations, truncation, HTML-to-text
│   └── tests.rs         # Tool integration tests
│
├── ui/                  # UI components
│   ├── mod.rs           # UI utilities, markdown renderer
│   ├── syntax.rs        # Syntax highlighting
│   └── diff.rs          # Syntax-highlighted diffs with line numbers
│
└── commands/            # Built-in commands
    └── builtin.rs       # Command implementations

See AGENTS.md for detailed conventions.

This project uses cargo-release for automated versioning and publishing.

Quick commands:

# Preview the release
cargo release patch

# Execute the release
cargo release patch --execute

# Release specific version
cargo release [patch|minor|major] --execute

The release workflow automatically:

1. Bumps version in Cargo.toml
2. Runs tests and formatting checks
3. Updates CHANGELOG.md
4. Publishes to crates.io
5. Creates release commit and Git tag
6. Pushes to remote repository

For detailed instructions, see RELEASE.md.

• API errors: Check connection and API key
• Path errors: Use relative paths for workspace; external paths prompt interactively or can be pre-allowed with Read/Write/Bash entries in config
• Build errors: rustup update && cargo clean && cargo build
• Images with spaces: Wrap path in quotes

MIT License

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.

• GitHub
• Crates.io

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