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.