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

5-Minute Demo

A reproducible bug-fix cycle that demonstrates ByteMind's full engineering loop:

go run ./cmd/bytemind run \
  -prompt "Fix the failing test and verify it passes" \
  -workspace examples/bugfix-demo/broken-project \
  -approval-mode full_access

The bug: CalculateAverage returns NaN on empty slice (divide by zero).
The fix: Add a guard clause for len(nums) == 0.

Offline verification (no API key needed):

go run ./evals/runner.go -smoke -run bugfix_go_001

See examples/bugfix-demo/ for details, DEMO.md for a judge-facing walkthrough, and ENGINEERING.md for engineering evidence.

Engineering Evidence

ByteMind is built for evaluators who need reproducible, verifiable engineering output.

Real Agent Loop

Multi-step tool use with observation feedback, context compaction, rate-limit retry, and execution budgets (internal/agent/engine_run_loop.go).

Coding-native Tools

14 built-in tools with JSON-structured output — git_status, git_diff, run_tests, file read/search/write/patch, shell execution, and web access. Each tool has unit tests and a safety classification.

Reproducible Demo

examples/bugfix-demo/broken-project is a self-contained Go project that fails go test ./... initially and passes after agent fix. Complete with expected output and offline verification.

Evaluation System

YAML-defined eval tasks run via evals/runner.go with flexible success criteria: command exit codes, output patterns, file content regex, and file modification detection. CI-integrated with -validate and -smoke flags.

Safety Boundary

Three-layer safety model: approval policy (on-request/always/never), sandbox (off/best_effort/required), and runtime boundaries (writable roots, exec allowlist, network allowlist). See bytemind safety explain.

CI and Testing

PR-gated CI: go build ./..., unit tests with coverage, sandbox acceptance on Linux/macOS/Windows, and eval smoke checks. See .github/workflows/ci.yml.

Extensibility

Skills, MCP servers, and SubAgents for encoding reusable workflows and delegating focused work.

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": 64,
  "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

Reusable workflow definitions loaded from three scopes (builtin > user > project). Each skill has a slash entry, tool policy, and instruction file. Use the /skills and /skill commands to list, activate, and manage skills.

/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

Built-in skills include bug investigation, GitHub PR review, repository onboarding, code review, RFC writing, and skill creation.

MCP

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

SubAgents

SubAgents provide isolated execution contexts for focused work:

Safety Model

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

Safety diagnostics

# View current safety configuration
bytemind safety status

# Understand the safety model
bytemind safety explain

# Check environment, config, and dependencies
bytemind doctor

Project Structure

cmd/bytemind            CLI entrypoint (chat / run / doctor / safety / mcp)
internal/app            Application bootstrap and CLI dispatch
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          Tool registry and 14 built-in tools
internal/skills         Skills discovery and loading
internal/subagents      SubAgent manager and preflight gateway
internal/sandbox        Runtime boundary and sandbox-related logic
tui/                    Terminal UI (BubbleTea framework)
examples/bugfix-demo    5-minute reproducible bug-fix demo
evals/                  Evaluation tasks and runner
docs/                   Architecture docs, RFCs, PRDs
scripts/                Cross-platform install scripts

Links

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

License

This project is licensed under the MIT License.