The Problem
Developers often need an on‑call AI that can read, edit, and run code in a repo without interrupting the workflow. Existing tooling forces an external prompt, manual approvals, or a separate daemon, which slows CI pipelines and increases the chance of unsafe changes.
What This Does
octomind is a single‑binary Rust harness that turns any LLM into a coding agent. It uses the Model Context Protocol (MCP) to expose a set of tools that can read files, execute shells, search code, and delegate to sub‑agents. The agent runs in three modes: an interactive CLI (src/main.rs), a daemon (src/commands/server.rs), or a WebSocket/ACP server (src/commands/acp.rs). Guardrails are defined in TOML (config-templates/agents/developer/rust.toml), so policy is version‑controlled, not ad‑hoc prompts.
How It Is Wired
Entry point – src/main.rs parses CLI arguments, loads configuration (src/config/loading.rs), and dispatches to the chosen command. Command routing – src/commands/mod.rs contains a match on sub‑commands (run, server, acp, workflow, etc.). Tool loop – src/agent/mod.rs constructs the MCP server, launches required taps (src/agent/tap_scaffold.rs), and processes the tool‑loop defined in src/agent/resolver.rs. Guardrails – guard logic lives in config-templates/agents/developer/rust.toml; the validator engine (src/commands/complete.rs) checks tool outputs against these before returning to the model. Supervisor – a second model, configured via src/config/agents.rs, reviews the plan (src/agent/registry.rs) and can veto actions. The fewest hops from user input to filesystem change are: CLI → command handler → agent resolver → tap scaffold → OS file system. Each hop is a single function call; the largest blast radius is the tap_scaffold module, which can spawn arbitrary subprocesses.
How To Use It
# Clone
git clone https://github.com/moses-y/octomind
cd octomind
# Build the binary
cargo build --release
# Run a quick task
./target/release/octomind run --task examples/fix-a-bug/task.txt
Setup – cargo is the sole dependency; install.sh wraps the build and places the binary in /usr/local/bin. Configuration – copy config-templates/default.toml to octomind.toml, edit guardrail sections, and set OPENAI_API_KEY in the environment. Running – the CLI (octomind run) accepts a task file, while octomind server starts a WebSocket server (src/commands/server.rs) and octomind acp registers an ACP agent for editor integration.
Real‑World Use
A CI pipeline can invoke octomind run on a PR diff file. The agent reads the diff, runs cargo test, and writes back a patch. Example workflow:
steps:
- uses: actions/checkout@v4
- run: ./install.sh
- run: octomind run --task pr_diff.txt
The agent’s guardrails prevent destructive commands, and the supervisor model verifies the patch against the repository history.
Code Health & Issues
- Tests – 331 test files (
tests/), all passing in the CI workflow (.github/workflows/ci.yml). - CI – GitHub Actions build (
.github/workflows/install.yml) and Docker build (.github/workflows/docker.yml) are active. - Coverage – reported via the badge but the coverage data file (
bench/compare_to_baseline.py) is not auto‑generated; manual measurement would be required. - Licensing – Apache 2.0 (
LICENSE). - Documentation – 65 Markdown docs covering architecture, usage, and troubleshooting.
No critical bugs or missing modules were detected in the static analysis.
The Bottom Line
octomind delivers a tightly‑integrated, Rust‑based AI coding agent that can run in CI, as a daemon, or inside an editor. Its single binary, deterministic guardrails, and MCP‑native design make it easy to embed in existing toolchains. The project is mature, well‑tested, and documented, but users must provide a valid LLM API key and configure guardrails for production safety. Ideal for teams needing an automated, policy‑driven code assistant within their existing pipelines.