Ferrum is a small Rust-native coding agent for Linux.

It provides a simple CLI, local file and shell tools, image input, JSONL sessions, AGENTS.md context loading, OpenAI-compatible providers, ChatGPT/Codex OAuth, and a minimal MCP stdio bridge.

Ferrum is inspired by Pi's agent-harness ideas, but it is a separate Rust project. It does not aim to support Pi extensions, packages, themes, or SDK compatibility.

Status: early MVP. Useful for real work, still evolving.

• Linux-native CLI
• Print mode and interactive mode
• JSONL sessions with resume
• AGENTS.md context loading
• Configurable context budget and thinking level
• Image input with optional terminal previews
• Minimal MCP stdio tool bridge
• OpenAI Codex / ChatGPT OAuth provider
• OpenAI-compatible Chat Completions provider
• OpenCode Go preset
• MiniMax provider preset
• Built-in tools:
  • read
  • write
  • edit
  • bash
  • grep
  • find
  • ls

Download the latest release asset from GitHub:

curl -L https://github.com/ominiverdi/ferrum/releases/download/v0.3.0/ferrum-v0.3.0-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv ferrum-v0.3.0-x86_64-unknown-linux-gnu/ferrum /usr/local/bin/
ferrum --help

Optional checksum verification:

curl -LO https://github.com/ominiverdi/ferrum/releases/download/v0.3.0/ferrum-v0.3.0-x86_64-unknown-linux-gnu.tar.gz
curl -LO https://github.com/ominiverdi/ferrum/releases/download/v0.3.0/ferrum-v0.3.0-x86_64-unknown-linux-gnu.tar.gz.sha256
sha256sum -c ferrum-v0.3.0-x86_64-unknown-linux-gnu.tar.gz.sha256

git clone https://github.com/ominiverdi/ferrum.git
cd ferrum
cargo install --path .
ferrum --help

Run a one-shot prompt:

ferrum -p "summarize this repo"

Pipe input:

cat src/main.rs | ferrum -p "review this file"

Attach an image:

ferrum --image ./screenshot.png -p "describe this image"

Start an interactive session:

ferrum

Resume the latest session:

ferrum --resume

Default config path:

~/.config/ferrum/config.toml

Example:

provider = "openai-codex"
model = "gpt-5.3-codex"
max_context_tokens = 256000
thinking = "off"

[[mcp.servers]]
name = "filesystem"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/me/projects"]
enabled = true

Thinking levels:

off|minimal|low|medium|high|xhigh

CLI overrides:

ferrum --provider opencode-go --model kimi-k2.6 --thinking minimal -p "hello"

Login:

ferrum login openai

Config:

provider = "openai-codex"
model = "gpt-5.3-codex"

Set an API key:

export OPENCODE_API_KEY=...

Run:

ferrum --provider opencode-go --model kimi-k2.6 -p "hello"

Default endpoint:

https://opencode.ai/zen/go/v1

Optional overrides:

export OPENCODE_GO_BASE_URL=...
export OPENCODE_GO_API_KEY_ENV=MY_KEY_ENV_NAME

export OPENAI_API_KEY=...
export OPENAI_BASE_URL=https://api.openai.com/v1
ferrum --provider openai --model gpt-4.1 -p "hello"

Ferrum reads a MiniMax API key from MINIMAX_API_KEY. The default base URL is https://api.minimax.io/v1; override it with MINIMAX_BASE_URL if needed.

export MINIMAX_API_KEY=...
ferrum --provider minimax --model <model> -p "hello"

/help
/session
/model [name]
/provider [name]
/thinking [level]
/image <path>
/compact
/quit

Ferrum supports local PNG, JPEG, and WebP attachments:

ferrum --image ./screenshot.png -p "describe this image"

In interactive mode, attach an image to the next message:

/image ./screenshot.png

Ferrum can also detect pasted image file paths and data:image/...;base64,... blocks. If chafa is installed, Ferrum renders a terminal preview; otherwise it prints image metadata.

See docs/images.md for details.

Ferrum supports local MCP stdio servers configured in config.toml.

Example:

[[mcp.servers]]
name = "filesystem"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/me/projects"]
enabled = true

Discovered MCP tools are exposed as:

mcp__<server>__<tool>

See docs/mcp.md for details.

Ferrum loads AGENTS.md files in this order:

1. ~/.config/ferrum/AGENTS.md
2. parent directories from filesystem root to cwd
3. cwd AGENTS.md

Files are deduplicated, bounded, and included in the system prompt.

Sessions are JSONL files under:

~/.config/ferrum/sessions/

Use /session to view the current session path, message count, approximate token count, and file size.

• API keys are read from environment variables or provider OAuth storage.
• Tools run with your local user permissions.
• bash, write, and edit can mutate files.
• Print mode does not ask for mutation confirmations.

cargo fmt --check
cargo test
cargo build --release

Docs:

• docs/spec.md
• docs/roadmap.md
• docs/providers.md
• docs/config.md
• docs/tools.md
• docs/sessions.md
• docs/images.md
• docs/mcp.md

MIT. See LICENSE.