English | 简体中文

ByteMind

A terminal-native AI coding agent for real repositories.

Let AI inspect code, search files, run commands, edit files, plan tasks, and operate under configurable human approval.

Documentation · Why ByteMind · Use Cases · Quick Start · Feature Matrix · Architecture · Skills / MCP / SubAgents

Why ByteMind

ByteMind is built for developers who want AI to work inside the repository, not outside it.

Instead of stopping at suggestions, ByteMind can participate in the actual engineering loop:

Prompt → Plan → Tool Call → Observation → Code Change → Verification → Result

Use Cases

Quick Start

Install

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/1024XEngineer/bytemind/main/scripts/install.sh | bash

Windows PowerShell

iwr -useb https://raw.githubusercontent.com/1024XEngineer/bytemind/main/scripts/install.ps1 | iex

Install a specific version

curl -fsSL https://raw.githubusercontent.com/1024XEngineer/bytemind/main/scripts/install.sh | BYTEMIND_VERSION=vX.Y.Z bash

$env:BYTEMIND_VERSION='vX.Y.Z'; iwr -useb https://raw.githubusercontent.com/1024XEngineer/bytemind/main/scripts/install.ps1 | iex

Configure

mkdir -p .bytemind
cp config.example.json .bytemind/config.json

Run

bytemind chat

bytemind run -prompt "Analyze this repository and summarize the architecture"

bytemind run -prompt "Refactor this module and update tests" -max-iterations 64

Terminal Preview

Feature Matrix

Built-in Tools

Core Experience

How It Works

graph TD
    A["User Prompt"] --> B["Build Runtime Context"]
    B --> C["LLM decides: answer or tool call"]
    C --> D{"Tool Call?"}
    D -- "No" --> E["Final Answer"]
    D -- "Yes" --> F["Approval / Policy Check"]
    F --> G["Execute Tool"]
    G --> H["Observation appended to session"]
    H --> I{"Done?"}
    I -- "No" --> C
    I -- "Yes" --> E

Architecture

graph TD
    User["User"] --> CLI["cmd/bytemind"]
    CLI --> App["App Bootstrap"]
    App --> Runner["Runner"]

    Runner --> Engine["Agent Engine"]
    Engine --> Provider["Provider Runtime"]
    Provider --> Model["LLM Provider"]

    Engine --> Tools["Tool Registry"]
    Tools --> FileTools["File Tools"]
    Tools --> PatchTools["Patch Tools"]
    Tools --> Shell["Shell Tool"]
    Tools --> Web["Web Search / Fetch"]
    Tools --> TaskTools["Task Output / Stop"]
    Tools --> Delegate["Delegate SubAgent"]

    Runner --> Session["Session Store"]
    Runner --> Config["Config"]
    Runner --> Skills["Skills Manager"]
    Runner --> SubAgents["SubAgent Gateway"]
    Runner --> Safety["Approval / Sandbox / Allowlist"]

Configuration

ByteMind normally merges three configuration layers: built-in defaults, user-level ~/.bytemind/config.json (or BYTEMIND_HOME/config.json), and project-level <workspace>/.bytemind/config.json.

The example below is a project-level config and only affects the current workspace. Provider credentials reused across repositories usually belong in user-level config or environment variables. Passing -config uses that explicit config file.

.bytemind/config.json

OpenAI-compatible example

{
  "provider": {
    "type": "openai-compatible",
    "base_url": "https://api.openai.com/v1",
    "model": "gpt-5.4-mini",
    "api_key_env": "BYTEMIND_API_KEY"
  },
  "approval_policy": "on-request",
  "approval_mode": "interactive",
  "max_iterations": 32,
  "stream": true
}

Anthropic example

{
  "provider": {
    "type": "anthropic",
    "base_url": "https://api.anthropic.com",
    "model": "claude-sonnet-4-20250514",
    "api_key_env": "ANTHROPIC_API_KEY",
    "anthropic_version": "2023-06-01"
  },
  "approval_policy": "on-request",
  "approval_mode": "interactive"
}

{
  "approval_policy": "on-request",
  "approval_mode": "interactive",
  "writable_roots": [],
  "exec_allowlist": [],
  "network_allowlist": [],
  "system_sandbox_mode": "off"
}

Skills, MCP and SubAgents

Skills

The CLI currently exposes reusable workflow helpers through the registered slash commands below.

/help                 Show available commands
/session              Show the current session
/sessions [limit]     List recent sessions
/agents [name]        List available subagents or show one definition
/explorer             Show the builtin explorer subagent definition
/review               Show the builtin review subagent definition
/resume <id>          Resume a recent session by id or prefix
/new                  Start a new session in the current workspace
/quit                 Exit the CLI

MCP

Use MCP to connect ByteMind to external tools and context beyond local repository operations.

SubAgents

SubAgents provide isolated execution contexts for focused work:

• broad repository discovery
• file targeting
• read-only exploration
• bug scope reduction
• review / analysis subtasks

Safety Model

ByteMind is designed around a simple principle:
AI can execute, but humans should keep the final control boundary.

Project Structure

cmd/bytemind            CLI entrypoint
internal/app            Application bootstrap
internal/agent          Agent loop, prompts, streaming, subagent execution
internal/config         Config loading, defaults, environment overrides
internal/llm            Common message and tool types
internal/provider       Provider adapters and provider runtime
internal/session        Session persistence
internal/tools          File / patch / shell / web tools
internal/skills         Skills discovery and loading
internal/subagents      SubAgent manager and preflight gateway
internal/sandbox        Runtime boundary and sandbox-related logic

Links

• Documentation: https://1024xengineer.github.io/bytemind/zh/
• GitHub: https://github.com/1024XEngineer/bytemind

License

This project is licensed under the MIT License.