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

🧠 Plan Use Plan mode for higher-risk tasks. Review the approach before making changes.

🛠 Execute Inspect files, search code, apply patches, run commands, and fetch external context when needed.

🧭 Control Keep sensitive actions behind approval policies and runtime boundaries.

---

Use Cases

Scenario	What ByteMind can do
Understand a new repository	Inspect structure, find entrypoints, and map key modules and call paths
Debug failing tests	Read failures, locate related code, patch the issue, and verify again
Review or refine changes	Check correctness, regression risk, and missing test coverage
Generate technical plans and RFCs	Turn repository context into an actionable implementation proposal
Automate repeated engineering tasks	Encode common workflows through Skills, MCP, or SubAgents
Collaborate under approval	Read and write files, run commands, and advance tasks while preserving approval boundaries

---

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

Category	Capability	Notes
Terminal UX	Terminal-first interaction	Built for repository-centric workflows
Streaming	Real-time output	Useful for long-running tasks
Agent Loop	Multi-step tool use + observations	More than a one-shot reply
Build / Plan	Separate planning and execution modes	Better for high-risk changes
Files	Read, search, write, replace, patch	Core repository operations
Shell	Run commands under approval	Keep execution visible and controlled
Web	Search and fetch external content	Useful when external context is needed
Sessions	Persist and resume tasks	Suitable for long-running work
Skills	Reusable workflows	Bug investigation, review, RFC, onboarding
MCP	External tool / context integration	Extend the runtime beyond local tools
SubAgents	Focused delegated work	Reduce noise in the main context
Safety	Approval, allowlists, writable roots	Human-in-the-loop execution
Providers	OpenAI-compatible / Anthropic	Configurable runtime support

---

Built-in Tools

Tool	Purpose
list_files	Inspect repository structure and candidate file scopes
read_file	Read source code, docs, config, and test content
search_text	Locate symbols, error messages, or call sites by keyword
write_file	Create or fully rewrite files
replace_in_file	Make small text replacements in existing files
apply_patch	Apply incremental file changes through patches
run_shell	Run commands inside the approval boundary and read results
web_search	Search external sources when local context is insufficient
web_fetch	Fetch a specific page as supplemental context

---

Core Experience

✅ What ByteMind is good at Understanding unfamiliar repositories Debugging code and failing tests Planning and applying small refactors Reviewing correctness and regression risk Writing RFC-style implementation plans Automating repetitive coding workflows

⚙️ What makes it practical Approval before sensitive actions Execution budget via max_iterations Session persistence Provider-agnostic runtime Extensible skills and external tools SubAgent-based context isolation

---

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

Loading

---

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

Loading

---

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

Runtime boundary example

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

Action	Typical behavior
Read files	Usually allowed automatically
Search files	Usually allowed automatically
Write files	Requires approval
Run shell commands	Requires approval or allowlist
High-risk actions	Shown before execution

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.