Sofos Code MCP server

Sofos Code

 

Sofos Code is a terminal-based AI coding assistant for software projects. It connects Claude or OpenAI models to local tools for reading code, editing files, running approved commands, searching the web, viewing images, and using external tools through the Model Context Protocol (MCP).

Sofos is written in Rust and runs in your terminal. Its access model is explicit: project files are available by default, while external paths and higher-risk actions require approval or configuration.

Sofos runs on macOS, Linux, and Windows. On macOS and Linux, the default shell mode uses an operating-system sandbox when the required platform support is available. On Windows, command confinement is disabled in this release. The bash executor still runs commands through the sh.exe provided by Git for Windows, which Sofos can find at the standard install path even when an integrated terminal does not expose Git on PATH.

---

Table of contents

• What Sofos does
• Key features
• Installation
  • Requirements
  • Prebuilt binary
  • Install with Cargo
  • Install from source
• Quick start
• Usage
  • Interactive commands
  • Input behaviour
  • One-shot prompts
  • Image vision
• CLI reference
• Models and reasoning effort
• Tools
  • Native tools
  • Read-only mode tools
  • MCP tools
• Security model
  • Workspace and external paths
  • Access modes
  • Sandboxing: reads vs. writes
  • Bash command permissions
  • Destructive operations
• Configuration
  • Custom instructions
  • Permissions
  • MCP servers
• Sessions and cost tracking
• Development
  • Project structure
  • Release process
• Troubleshooting
• License
• Acknowledgments
• Links

---

What Sofos does

Sofos provides an AI assistant with controlled access to your project from inside the terminal. It can:

• inspect files and directories;
• search code with ripgrep;
• edit files with exact replacements or Morph Apply;
• create, move, copy, and delete files with permission checks;
• run approved build, test, and inspection commands;
• fetch documentation and use provider-native web search;
• open local image files or remote image URLs;
• accept image pastes from the clipboard;
• keep a visible task plan during multi-step work;
• save and resume conversations;
• connect to external tools through MCP servers.

The assistant acts through visible tool calls. Dangerous commands are blocked, deletion prompts for confirmation, and access outside the workspace is controlled by separate permission scopes.

---

Key features

• Terminal interface — Inline viewport at the bottom of your terminal while normal scrollback remains available.
• Claude and OpenAI support — Shared provider layer with provider-specific streaming, reasoning, web search, and cache handling.
• Streaming Markdown — Responses render as they arrive, including code blocks, headings, lists, tables, blockquotes, and links.
• Iterative tool use — The model can use tools across multiple steps, with a hard limit to prevent endless loops.
• Safe file editing — Exact edits, chunked writes, visual diffs, atomic writes, and optional Morph Apply.
• Explicit permissions — Separate Read, Write, and Bash grants for paths outside the workspace.
• Bash safety checks — Command tiers and structural checks for parent traversal, hidden subcommands, ANSI-C quoting, unconfined redirection, and dangerous Git operations.
• Access presets — Five permission modes: read-only, sandboxed-ask, sandboxed-retry, sandboxed-strict, and unsandboxed.
• Image vision — Local image files, remote image URLs, and pasted clipboard images.
• MCP integration — Tools from stdio or streamable HTTP MCP servers.
• Session persistence — Saved conversations with compatible model, permission preset, and cost counters restored.
• Cost visibility — Token totals, cache usage, and cost estimates priced per response at the rates of the model that answered it.
• Context compaction — Local and provider-supported compaction for older conversation context.

---

Installation

Requirements

Set at least one provider API key:

• ANTHROPIC_API_KEY for Claude models; or
• OPENAI_API_KEY for OpenAI models.

Optional tools and keys:

• ripgrep, recommended for fast code search through search_code;
• MORPH_API_KEY, required for the morph_edit_file tool.

On Linux, the sandboxed-* presets need Bubblewrap (bwrap) for operating-system command confinement. Without it, Sofos starts unsandboxed and the sandboxed presets are disabled. Install it with your distribution's package manager:

# Debian / Ubuntu
sudo apt update
sudo apt install bubblewrap

# Fedora / RHEL
sudo dnf install bubblewrap

# Arch
sudo pacman -S bubblewrap

Bubblewrap also relies on kernel support for user namespaces, which is enabled by default on most modern distributions.

Prebuilt binary

Download the latest binary from GitHub Releases.

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

# Windows
# Extract the .zip archive and add the extracted folder to PATH.

On macOS, Gatekeeper may block the first run. Open System Settings → Privacy & Security, then choose Allow Anyway for the Sofos binary.

Install with Cargo

cargo install sofos

Install from source

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

Keep .sofos/ out of version control. It stores sessions, local permissions, and personal settings. AGENTS.md is project-level context and is intended to be version controlled.

---

Quick start

Set a provider key:

export ANTHROPIC_API_KEY='your-anthropic-key'
# or
export OPENAI_API_KEY='your-openai-key'

Optionally enable Morph Apply edits:

export MORPH_API_KEY='your-morph-key'

Start the interactive assistant:

sofos

Use a different model:

sofos --model gpt-sol
sofos --model claude-opus -e high
sofos --model gpt          # OpenAI's default model

Run one prompt and exit:

sofos -p "Review the error handling in src/error.rs"

Start with inspection tools only:

sofos --readonly

Resume a saved session:

sofos --resume

---

Usage

Interactive commands

Command	Description
/resume	Open the session picker and resume a saved conversation.
/clear	Clear the current conversation history and start a new session id.
/compact	Compact older context to reduce token usage.
/effort	Open the reasoning-effort picker. The picker lists only the levels supported by the active model. Use Up / Down to select, Enter to switch, and Esc to cancel.
/effort low|medium|high|xhigh|max	Switch directly to a reasoning level. Unsupported levels print a clear error.
/mode	Open the reasoning-mode picker. standard and pro; pro is disabled on the Anthropic models. Use Up / Down to select, Enter to switch, and Esc to cancel.
/mode standard|pro	Switch reasoning mode. pro is accepted only on the OpenAI models; other models print a clear error.
/model	Open the model picker. Use Up / Down to select, Enter to switch, and Esc to cancel. Models this session cannot switch to are greyed out and skipped: the other provider's models, because the API client is fixed at startup, and any model that rejects the active reasoning effort, reasoning mode, or output-token ceiling. Type /model <name> to see the reason a particular model is unavailable.
/model <name>	Switch directly to a model on the active provider. To switch provider, restart Sofos with --model <name>.
/permissions	Open the permission preset picker. The presets are read-only, sandboxed-ask, sandboxed-retry, sandboxed-strict, and unsandboxed. Use Up / Down to select, Enter to switch, and Esc to cancel. Where sandboxing is unavailable, such as Windows, the sandboxed-* presets are shown but disabled.
/permissions <preset>	Switch directly to a permission preset.
/exit, /quit, /q, Ctrl+D	Save the session and exit with a cost summary.
Esc or Ctrl+C while busy	Interrupt the current AI turn.

Input behaviour

• Enter submits the current message.
• Shift+Enter inserts a newline when the terminal supports it.
• Alt+Enter and Ctrl+Enter are newline fallbacks.
• Ctrl+U deletes from the cursor to the start of the line.
• Ctrl+W deletes the previous word.
• Ctrl+K deletes from the cursor to the end of the line.
• These editing shortcuts match common readline behaviour used by bash, zsh, and fish.
• Alt+Up and Alt+Down move through previously submitted prompts. Sofos preserves the current draft and restores it when you move past the newest entry.
• Typing / at the start of the input opens command suggestions. Use Up / Down to select, Enter to run the selected command, Tab to insert it into the input, and Esc or Ctrl+C to dismiss the list.
• You can keep typing while the model is working. New messages are queued and processed in order.
• If the model is inside a tool loop, a queued message is delivered at the next tool-result boundary. This lets you steer the current turn without interrupting it.
• The status line shows the model, permission mode, reasoning setting, running token totals, and cache token counters when available.

One-shot prompts

One-shot mode sends a prompt, runs the assistant turn, saves the session, prints a summary, and exits.

sofos -p "Find the likely cause of the failing tests"
sofos -p "Create a high-level summary of this crate" --readonly

Redirecting the output to a file or another program produces plain text: colour and other terminal escape sequences are written only when the output is going to a terminal.

Image vision

Ask about an image by mentioning the file path or URL in your message. Sofos will call view_image to open it.

What is wrong in ./screenshots/error.png?
Describe ./docs/architecture-diagram.webp.
Review https://example.com/chart.png
What do you see in the images in ./assets/?

For a folder, Sofos lists the directory first, then opens each image one by one.

Clipboard paste:

Ctrl+V    # Inserts a numbered marker such as ①.

Supported formats are JPEG, PNG, GIF, and WebP. Local images are limited to 20 MB. Images larger than 2048 pixels on the long side are scaled down proportionally before being sent to the model, so large screenshots do not inflate token usage unnecessarily. Images outside the workspace require Read permission the first time, like any other external file.

---

CLI reference

-p, --prompt <TEXT>          Run one prompt and exit.
    --readonly               Start in read-only mode with inspection tools only.
    --no-sandbox             Start unsandboxed: run shell commands without operating-system confinement.
-r, --resume                 Resume a previous session.
    --check-connection       Check provider connectivity and exit.
    --api-key <KEY>          Anthropic API key. Overrides ANTHROPIC_API_KEY.
    --openai-api-key <KEY>   OpenAI API key. Overrides OPENAI_API_KEY.
    --morph-api-key <KEY>    Morph API key. Overrides MORPH_API_KEY.
    --model <MODEL>          Model to use. Default: claude-opus.
    --morph-model <MODEL>    Morph model to use. Default: morph-v3-fast.
    --max-tokens <N>         Maximum output tokens per response. Default: 64000.
-e, --reasoning-effort <LV>  low, medium, high, xhigh, or max. Default: medium.
    --reasoning-mode <MODE>  standard or pro (OpenAI only). Default: standard.

--max-tokens must be at least 16 and must not exceed the chosen model's own output limit — 128000 tokens on every supported model. The limit is checked at startup and when switching model with /model. The hidden, deprecated --thinking-budget flag still parses for backwards compatibility, but it has no effect and is intentionally omitted from the CLI help.

---

Models and reasoning effort

Sofos supports these models, shown in /model picker order. You choose a model by its short name; Sofos sends the current version to the provider.

Name	Current version	Provider
claude-fable	claude-fable-5-1	Anthropic
claude-opus (default)	claude-opus-5-5	Anthropic
claude-sonnet	claude-sonnet-5-5	Anthropic
claude-haiku	claude-haiku-5-5	Anthropic
gpt-astra	gpt-6-astra	OpenAI
gpt-sol	gpt-6.1-sol	OpenAI
gpt-terra	gpt-5.6-terra	OpenAI
gpt-luna	gpt-6-luna	OpenAI

--model and /model accept only the short names above, plus claude (picks claude-opus) and gpt (picks gpt-sol). A versioned name or any other value is refused, and Sofos prints the supported list.

Sofos exposes five reasoning levels:

low, medium, high, xhigh, max

The active model determines which levels are valid. Sofos validates the level at startup and when /effort is used, so unsupported combinations fail before a provider request is sent.

Examples:

sofos -e medium                       # Default balance.
sofos -e high                         # More reasoning for hard tasks.
sofos -e max --model claude-opus      # Highest Anthropic level.
sofos -e max --model gpt-sol          # Highest OpenAI level.

Every supported model currently accepts all five levels.

Provider mapping:

• OpenAI sends reasoning.effort directly. On the OpenAI models, --reasoning-mode pro (or /mode pro) additionally sends reasoning.mode: "pro" — the model does extra work before answering, trading latency and tokens for quality. standard is the default and omits the field. Mode is independent of effort.
• Claude models all use adaptive thinking. The provider chooses the token budget from the effort level.

Claude Fable 5.1, Claude Opus 5.5, and Claude Sonnet 5.5 run safety classifiers that can decline a request. On those models Sofos asks Anthropic to answer a declined request on a substitute model rather than returning the refusal, and prints a bright notice naming the model that answered. If the substitute declines too, the turn ends with the reason shown.

On the Anthropic models, Sofos asks for a readable summary of the model's reasoning and prints it under a dimmed Thinking: heading while the answer is being prepared. Asking for the summary does not change what a conversation costs: these models carry their reasoning between turns either way, and Anthropic bills it the same whether the summary is returned or withheld.

---

Tools

Native tools

Tool	Purpose
list_directory	List one directory. Use glob_files for recursive discovery.
read_file	Read a file. External paths require Read permission.
glob_files	Find files recursively with glob patterns. Build and vendor directories are skipped by default.
search_code	Search code with ripgrep when rg is installed.
write_file	Create, overwrite, or append to a file. External paths require Write permission.
edit_file	Replace exact text in an existing file. Non-global edits require one unique match. Use replace_all only for intentional global replacement. External paths require Read and Write permission.
morph_edit_file	Apply fast Morph edits when MORPH_API_KEY is configured. External paths require Read and Write permission.
create_directory	Create directories. External paths require Write permission.
move_file	Move or rename files or directories. External paths require Write permission.
copy_file	Copy files. External sources require Read permission, and external destinations require Write permission.
delete_file	Delete a file after confirmation. External paths require Write permission.
delete_directory	Delete a directory after confirmation. External paths require Write permission.
execute_bash	Run approved shell commands through the bash permission system.
update_plan	Show the current task plan with pending, in_progress, and completed statuses.
view_image	Attach a local image file or an http(s):// URL to the conversation so the model can see it.
web_fetch	Fetch a URL and return readable text.
web_search	Use provider-native web search.

Clipboard pastes are not routed through a tool. Pressing Ctrl+V in the prompt attaches the image directly to the message.

Read-only mode tools

Read-only mode is enabled with --readonly or the read-only preset in /permissions. It limits the native tool set to:

• list_directory;
• read_file;
• glob_files;
• search_code when ripgrep is installed;
• update_plan;
• view_image;
• web_fetch;
• web_search.

MCP tools are filtered out in read-only mode by default. To make a server's tools available in read-only mode, add one of these values to that server entry in ~/.sofos/config.toml or .sofos/config.local.toml:

• readonly = "read_only" when the server is known to expose only read operations;
• readonly = "allow" when you explicitly want to allow the server even if it may mutate data.

When read-only mode is enabled, the startup banner lists which MCP servers were filtered out and which were opted in.

MCP tools

Configured MCP servers can add tools dynamically. Sofos prefixes each MCP tool with the server name and a triple underscore separator so different (server, tool) pairs cannot collide:

filesystem___read_file
github___create_issue

Server names and tool names that contain the reserved separator are rejected at startup with a warning. If two servers expose the same tool name, the second registration is skipped and the first tool keeps its identifier. Tool listings are cached at startup for the session.

---

Security model

Sofos is built around explicit access boundaries. The assistant can work with a project without receiving unrestricted access to the host system.

Workspace and external paths

• Files inside the current workspace are available by default unless blocked by a deny rule.
• External paths use three independent scopes:
  • Read(path) for reading files and listing directories;
  • Write(path) for writing, editing, creating, moving, copying, and deleting;
  • Bash(path) for bash commands that reference external paths.
• Read access does not imply Write or Bash access.
• Write access does not imply Read or Bash access.
• Tools that both read and write external files, such as edit_file and morph_edit_file, require both Read and Write grants.
• External access can be allowed for the current session or remembered in configuration.

A fourth scope, WebFetch(domain:example.com), controls the web_fetch tool. The first time the assistant fetches a URL from a host you have not allowed, Sofos shows the host and asks whether to allow it. You can allow it for the current session or remember it for future sessions. Allowing a host also covers its subdomains, so allowing example.com also allows docs.example.com. Redirects are followed only after the same check on the destination host. In non-interactive runs, a host that is not already allowed is refused.

A fifth scope, Mcp(servername), controls tools from MCP servers. MCP servers run outside the Sofos sandbox with open network access, so the first time the assistant calls a tool from a server you have not allowed, Sofos shows the server and tool and asks whether to allow it. You can allow it for the current session or remember it as Mcp(servername), which covers every tool from that server. A matching deny rule blocks the server outright. In non-interactive runs, a server that is not already allowed is refused.