English | 简体中文

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

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

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

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

bytemind chat

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

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

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.

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

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

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.

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.

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.

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.

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

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

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

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"]

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

{
  "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
}

{
  "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"
}

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.

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

SubAgents provide isolated execution contexts for focused work:

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

# View current safety configuration
bytemind safety status

# Understand the safety model
bytemind safety explain

# Check environment, config, and dependencies
bytemind doctor

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

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

This project is licensed under the MIT License.