SkillAgentSearch skills...

Sofos Code

AI coding agent for your terminal, implemented in pure Rust

GenerateConvertImprove

Install / Use

/learn @alexylon/Sofos Code
About this skill

Quality Score

0/100

Supported Platforms

Claude Code
Claude Desktop
Cursor

README

Sofos Code

  Crates.io

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.

<div align="center"><img src="/assets/screenshot.png" style="width: 800px;" alt="Sofos Code"></div>

Table of Contents

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, paste from clipboard with Ctrl+V
  • Session History - Auto-save and resume conversations
  • Custom Instructions - Project and personal context files
  • File Operations - Read, write, edit, list, create (sandboxed)
  • 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 (read-only, sandboxed)
  • 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

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 AGENTS.md (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)
  • /compact - Compress conversation history to free up context (also triggers automatically at 80% token usage)
  • /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, 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

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-6)
    --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/Context

AGENTS.md (project root, version controlled) - Project context for AI agents, 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
  • edit_file - Targeted string replacement edits (no API key needed)
  • morph_edit_file - Ultra-fast code editing (requires MORPH_API_KEY)
  • list_directory - List a single directory's contents
  • glob_files - Find files recursively by glob pattern (**/*.rs, src/**/test_*.py)
  • 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
  • web_fetch - Fetch URL content as readable text (documentation, APIs)
  • 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, glob_files, web_search, web_fetch, 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)",
]

[mcp-servers.company-internal]

alexylon

View profile

View on GitHub
GitHub Stars7
CategoryDevelopment
Updated8h ago
Forks1
alexylon/sofos-code

Languages

Rust

Security Score

90/100

Audited on Mar 24, 2026

No findings