octomind README

项目的 README,来自 github.com/Muvon/octomind。合并为一个 markdown 文件:README.md。

Octomind — open-source coding agent harness

Open-source coding agent harness. One Rust binary, any model, every surface.

Interactive, stdin, daemon, WebSocket, or ACP — one binary, one config.
A supervising model plans and checks the work.
Policy lives in TOML guardrails, not approval prompts.

CI Crates.io Coverage License Stars

Website · Docs · Tap Registry · Benchmarks · Issues


Octomind is an open-source coding agent harness. It gives any LLM the tools to work in a repository — read and edit files, run shells, search code, delegate to sub-agents — through MCP, and runs the result as an interactive CLI, a stdin pipe, a daemon, a WebSocket server, or an ACP agent in your editor. Most agents stop and ask a human before each risky step, which works at a keyboard and blocks everything in CI. Octomind writes that policy down as TOML guardrails and adds a supervising model that plans and checks the work, so the same session can run with nobody watching. On 25 tasks taken from merged pull requests it solved 24; OpenCode solved 19 with the same model at about twice the cost (benchmarks).

How It Works

One diagram, the whole turn: what is assembled before the model sees the request, the tool loop, how a turn is allowed to end, and what carries over to the next session.

Octomind turn flow: request, context assembly (AGENTS.md and skills, lesson recall, supervisor notes, compression), model, tool loop (guards, MCP tools, hooks, condense, detectors), verify gate, validators, response; lessons extracted after /done feed later sessions and, with evolution enabled, skill and guardrail candidates on trial

Why Octomind?

Built for the work that keeps going after you leave:

# Interactive
octomind run developer

# Non-interactive — CI, scripts, automation
echo "Explain the auth module" | octomind run developer --format plain

# Daemon — keep it alive, talk to it from another terminal
echo "watch the build" | octomind run --name watcher --daemon --format jsonl
octomind send --name watcher "run the test suite"

Quick Start

1. Install (macOS, Linux):

curl -fsSL https://raw.githubusercontent.com/muvon/octomind/master/install.sh | bash

On Windows, in PowerShell:

irm https://raw.githubusercontent.com/muvon/octomind/master/install.ps1 | iex

On macOS, you can also install with Homebrew:

brew install muvon/tap/octomind

2. Choose where models come from. Start octomind once in a terminal:

octomind

Before it writes a config, the first interactive run asks where to get models:

Run octomind configure to change this later. Scripts, piped input, and --format runs never see the screen; they use the default config.

3. Run a specialist in your project:

cd ~/your/project
octomind run developer

You're now in a session with the developer domain's lead agent. It reads your code and runs commands itself, and hands code changes to the domain's specialists. The interface is a plain line prompt with markdown rendering — no TUI to learn, so it works over SSH, in tmux, and in CI logs. The first time you run a specialist, it may install its tools and ask for credentials.

developer:chief comes from the default tap muvon/tap, not your local config. Plain octomind run starts the config's default role, assistant:chief, the global assistant. A name without a :, such as octomind run developer, starts that domain's orchestrator (developer:chief), unless your config defines a role with that name; the local role wins.

Try the recorded bug-fix demo: two failing tests, an agent fix, and an independent test rerun.

Benchmarks

Measured on octobench against 25 tasks harvested from merged pull requests across Python, PHP, Rust, C++, and JavaScript. Each agent works in the pre-fix repo; held-out tests from the merged fix decide pass or fail. These are the published July 30, 2026 results, not a measurement of this checkout.

solved judge Σ / 2500 cost wall time
octomind + glm-5.2 24/25 2264 $63.43 3.6h
claude code + claude-opus-5 23/25 2262 $81.79 6.7h
codex + gpt-5.6-sol 21/25 2127 $14.86 1.0h
opencode + glm-5.2 19/25 2093 $129.54 3.3h

Guardrails: Policy as Code

Drop a .agents/guardrails.toml in your repo. Octomind enforces it deterministically, with no code to compile and no plugin to install.

# Pre-call deny — block a class of calls before they execute
[[guard]]
match   = "shell(command=^rm\\s+-rf?)"
message = "rm -rf blocked."

# Conditional rule — only fires after the agent ran git status this session
[[guard]]
match   = "shell(command=git push)"
when    = ["+shell(command=git status)"]
message = "Review changes before pushing."
Layer When it runs What it does
Guards Before a tool call Deny by capability, argument regex, and session history. A match returns a denial instead of executing the call.
Hooks After a tool result A non-zero exit injects stdout into the agent's inbox — lint and format failures become automatic corrections without restarting the turn.
Validators After a turn Scripts the agent reads on its next turn. This replaces "approve this change?" prompts in autonomous loops.

If you know Claude Code hooks: guards are PreToolUse denies declared in TOML, hooks are PostToolUse, validators are Stop — no scripts required for the common cases.

Hook and validator script examples: Guardrails guide.

One Harness, Five Surfaces

The same harness, exposed wherever your workflow needs it.

Surface Use it for Docs
Interactive CLI Daily work, any domain Sessions
Non-interactive (--format plain / jsonl) CI, scripts, scheduled jobs CLI reference
Daemon + send Background agents, continuous monitoring Daemon & hooks
WebSocket (octomind server) IDE plugins, dashboards, integrations WebSocket server
ACP (octomind acp) Agent inside Zed, JetBrains, VS Code, Neovim, or any ACP editor ACP protocol

Need machine-readable results? Pass --schema schema.json to constrain the final response to a JSON Schema (requires a model with structured-output support). See Structured output.

Features

Feature What you get Learn more
Specialists & taps Packaged agents with model, prompt, MCP servers, and permissions; installs their tool dependencies on first use Tap system
Roles Per-role model, temperature, system prompt, tools Roles
Workflows Multi-step pipelines, each step with its own model and toolset Workflows
MCP client stdio and Streamable HTTP servers, with OAuth; enable/disable servers mid-session MCP tools
Agent Skills Standard SKILL.md skills from .agents/skills/, ~/.config/agents/skills/, and taps; they activate on demand, so your context stays small Skills
Local project tools Executable scripts in .agents/tools/ auto-register as tools Local tools
Plugins & AGENTS.md Agent Plugins (plugin.json + skills + mcp.json) from taps, .agents/plugins/, or ~/.config/agents/plugins/; project AGENTS.md loads at session start Configuration
Supervisor & learning A second model plans, checks completion, and condenses tool output; lessons persist as files per project and role Supervisor, Learning
Sandbox --sandbox locks writes to the working directory via Landlock (Linux) or Seatbelt (macOS), inherited by every shell, MCP server, and sub-agent Config reference
Token efficiency Cache-aware cost accounting and adaptive compression Token efficiency

Specialists

octomind run developer            # developer domain: its lead agent hands larger work to the specialists
octomind run doctor               # doctor domain: health questions, routed to the right specialist
octomind run lawyer               # lawyer domain: legal questions, by jurisdiction
octomind run doctor:blood         # one exact specialist: blood-test interpretation

Running a specialist fetches its manifest from the tap registry, installs any required binaries, resolves credentials, starts the right MCP servers, and then opens the session.

Build and register your own:

octomind tap init yourteam/my-tap   # scaffold, validate, git-init, and register locally
octomind tap yourteam/my-tap        # on another machine, after publishing to GitHub

The octomind- prefix is added automatically: yourteam/my-tap maps to the repository yourteam/octomind-my-tap.

Installation

Method Command
Install script (recommended) curl -fsSL https://raw.githubusercontent.com/muvon/octomind/master/install.sh | bash
Install script (Windows PowerShell) irm https://raw.githubusercontent.com/muvon/octomind/master/install.ps1 | iex
Homebrew (macOS) brew install muvon/tap/octomind
Scoop (Windows) scoop bucket add muvon https://github.com/Muvon/scoop-bucket then scoop install muvon/octomind
Cargo (Rust 1.95+) cargo install octomind
Docker docker run --rm ghcr.io/muvon/octomind --help
From source git clone https://github.com/muvon/octomind.git && cd octomind && cargo build --release

The install script detects your OS and architecture (Linux and macOS on x86_64/aarch64) and installs to ~/.local/bin/. Pass --install-dir <DIR> or set OCTOMIND_INSTALL_DIR to override. On Windows (x86_64/aarch64), install.ps1 installs to %LOCALAPPDATA%\octomind\bin and adds it to your user PATH; it honors OCTOMIND_INSTALL_DIR and OCTOMIND_VERSION too. install.sh still works from Git Bash or MSYS2.

Command not found? Add the install directory to your PATH:

export PATH="$HOME/.local/bin:$PATH"

Building from source requires protoc; see Building from source for per-OS prerequisites.

Verify:

octomind --version
octomind config      # generate the default config
octomind run         # start your first session

Shell completions: octomind completion <bash|zsh|fish|elvish|powershell>.

Model access

Run octomind configure any time to switch between the hub and your own provider. It changes only the three model names (main, supervisor, compression) and keeps the rest of your config and its comments.

Octomind Cloud — choose the hub in octomind configure, or run octomind login (device-code sign-in, like gh auth login). Either stores a gateway key locally. The default config already uses octohub:auto. Learn more.

Bring your own key — choose your provider in octomind configure. To set it up by hand instead, set the provider's environment variable (OPENROUTER_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, DEEPSEEK_API_KEY, …) and point the model tables at it. The supervisor and compression profiles also default to octohub:auto, so update all three:

[model]
name = "anthropic:claude-sonnet-5-5"

[supervisor.model]
name = "anthropic:claude-haiku-5-5"

[compression.model]
name = "anthropic:claude-haiku-5-5"

Provider details and per-role overrides: Providers & models.

Configuration

Config lives at ~/.local/share/octomind/config/config.toml on macOS and Linux, and under %LOCALAPPDATA%/octomind/config/ on Windows. Set OCTOMIND_DATA_DIR to override the data root.

octomind config --show       # view current config
octomind config --validate   # validate config

Override any value for a single run with -c:

octomind run -c supervisor.enabled=false

Full reference: Configuration reference · Environment variables.

Session commands

Command Description
/help Show all commands
/info Token usage and costs
/model anthropic:claude-sonnet-5-5 Switch model mid-session
/role developer:general Switch to a configured role or tap tag
/new Review auth Start a fresh session (title optional)
/done Force context compression and start background learning extraction when enabled
/exit Exit the session

Full list: Session commands.

Telemetry

Octomind reports anonymous usage: which commands, tools, and models are used, plus timings, token counts, and error kinds. It never sends your code, prompts, file paths, tool arguments, or environment values. Opt out in any of three ways:

export DO_NOT_TRACK=1          # the cross-tool standard, honored first
export OCTOMIND_TELEMETRY=0    # for subsequent commands in this shell
# or set `telemetry = false` in config.toml

Exact field list: Telemetry.

Documentation

Start here Go deeper Integrate Reference
Installation Roles WebSocket server CLI
Quickstart Workflows ACP protocol Config
Configuration Compression Daemon & hooks Session commands
Providers & models Guardrails Editor integration Environment variables

Full index: doc/README.md · Hosted: octomind.run/docs.

Contributing

The most impactful contribution isn't code — it's specialist agents. A cardiologist publishing doctor:medications. A tax attorney publishing lawyer:us. A security researcher publishing security:owasp. One TOML file, and everyone with that problem gets an agent that knows the domain.

Code contributions are welcome too. Set up the hooks and run the gate before you push:

pip install pre-commit && pre-commit install
make dev    # fmt + clippy + test

Commits follow Conventional Commits. Full guide, architecture overview, and code conventions: CONTRIBUTING.md · internals: Architecture.

Community participation follows our Code of Conduct. Report vulnerabilities privately using the security policy.

License

Apache License 2.0 — see LICENSE.


Octomind by Muvon · Website · Documentation

octomind (Muvon/octomind)

正在搜索数据库…

这是什么?Octomind 是一个开源的编程智能体运行框架。它通过 MCP 工具让大语言模型真正接触你的代码仓库:读写文件、运行 shell 命令、搜索代码,并把任务委派给子智能体。
它是 IDE 插件,还是在终端里运行的程序?它是一个独立的 Rust 二进制程序。你可以把它作为交互式终端会话运行,也可以在 CI 或脚本中通过 stdin 以非交互方式运行,还可以作为后台守护进程运行,通过 WebSocket 连接,或在 Zed、JetBrains、VS Code、Neovim 等编辑器中作为 ACP 智能体使用。
我该怎么让它运行起来?在 macOS 上可以用 Homebrew 安装,也可以执行 cargo install octomind,或运行安装脚本(Windows 上使用 PowerShell)。然后执行 'octomind login' 来使用内置的云端模型,或导出你自己的服务商密钥;再用 'octomind run developer:general' 在项目中启动一个专家智能体。
要先注册什么服务,才能让它调用模型?如果你使用自己的服务商密钥,则不需要注册。内置选项是 Octomind Cloud:执行 'octomind login' 会进行设备码登录,并在本地保存一个网关密钥,默认配置已经使用它。
每次编辑都需要我批准吗?不需要。策略写在 TOML 护栏配置中:护栏会在工具调用执行前将其拒绝,钩子会把 lint 失败结果反馈给智能体,验证器则在自主循环中替代批准提示。超出预算时,终端会话会询问 y/N,而非交互式运行会以退出码 75 停止。
我能用本地模型完全离线运行吗?README 没有描述完整的离线部署方式。Ollama 被列为受支持的服务商,通常意味着可以使用本地模型,但 README 中并没有记录离线工作流本身。
它会把我的代码发送到作者的服务器吗?README 称,内置遥测只收集匿名使用数据(命令、工具、模型、耗时、token 数量、错误类型),绝不包含代码、提示词、文件路径、工具参数或环境变量值。你可以选择退出。你的提示词仍会发送给你所配置的任何模型服务商。
有没有第二个模型来检查智能体的工作?有。一个监督模型负责规划工作、判断任务何时算完成,并压缩过长的工具输出,使主智能体的上下文保持精简。
作者为什么要自己开发,而不直接用现成的智能体?README 写道,大多数编程智能体都假设有人在盯着屏幕。Octomind 则面向你离开之后仍会继续进行的工作,比如 CI 运行、守护进程和定时任务,并用确定性的策略取代弹窗审批。
它能在后台或按计划无人值守地运行吗?可以。使用 --format plain 或 jsonl 的非交互式运行适合 CI 和类 cron 的定时任务,而配合 send 使用的守护进程可用于持续监控。传入 --schema 可以把最终答案限定为 JSON Schema 格式。
有哪些类似的项目?Baize, maki, SystemOneHarness, aichat, dscode, ruflo, Axl, localix-cli
作者
Muvon
大小
21.4 MB
星标
664
时长
1年
提交 · 90 天