Core Concepts

Understanding these concepts helps you get the most out of ByteMind.

Agent Modes

ByteMind has two working modes you can switch between at any time during a session.

Build Mode (Default)

In Build mode the agent reads files, searches code, writes changes, and runs verification commands directly after receiving your task. Best for most everyday coding work:

• Fixing bugs
• Adding new features
• Refactoring code
• Updating documentation

bytemind          # starts in Build mode by default

Plan Mode

In Plan mode the agent first produces a step-by-step plan that you review before any execution begins. Best for complex, multi-step tasks:

• Large-scale refactors spanning many modules
• Feature implementations with sequential dependencies
• Phased migrations requiring stage-by-stage sign-off

Switch modes with slash commands inside a session:

/plan    switch to Plan mode
/build   switch back to Build mode

Sessions

Every bytemind invocation creates or resumes a session. Sessions automatically persist the full conversation context.

• Stored in the .bytemind/ directory
• Survive interruptions — restart and continue where you left off
• Multiple sessions can coexist; switch by ID

Common session commands:

Command	Description
/session	Open session picker to view/resume/delete sessions
/new	Start a new session in the current workspace

Tools

Tools are the capability units the agent uses to take action. ByteMind ships with:

Tool	What it does
list_files	List directory structure
read_file	Read file contents
search_text	Full-text search (regex supported)
write_file	Write or create files
replace_in_file	Replace specific content in a file
apply_patch	Apply a unified diff patch
run_shell	Execute shell commands
update_plan	Update the task plan (Plan mode)
web_fetch	Fetch a web page
web_search	Search the web

High-risk tools (write_file, replace_in_file, apply_patch, run_shell) trigger the approval flow before executing.

Approval Policy

The approval policy controls how the agent handles high-risk operations:

• on-request (default): waits for your explicit confirmation before each high-risk tool call
• full_access: in unattended scenarios, automatically approves approval-required actions with no prompt
• Migration gate: legacy approval_mode: away is blocked by default; set BYTEMIND_ALLOW_AWAY_FULL_ACCESS=true only for temporary migration

See Tools and Approval for details.

Iteration Budget

max_iterations caps the number of tool-call rounds per task, preventing runaway loops from consuming tokens:

• Default: 64
• When the limit is reached, the agent produces a progress summary and stops gracefully
• Raise it for complex tasks via config or CLI flag:

bytemind -max-iterations 64

Skills

A skill is an activatable workflow guide — it injects additional system-level instructions that steer the agent through a domain-specific process.

ByteMind's built-in skills:

Skill	Command	When to use
Bug Investigation	/bug-investigation	Structured bug diagnosis
Code Review	/review	Focus on correctness and risk
GitHub PR	/github-pr	Analyze PR diffs and merge risk
Repo Onboarding	/repo-onboarding	Get up to speed on a new repo
Write RFC	/write-rfc	Draft structured technical proposals

Skills also support project-level and user-level customization. See Skills.

Subagents

Subagents are specialized agents with their own tool sets and instructions, invoked by the main agent via delegate_subagent when needed. Ideal for parallel work, context isolation, or restricted tool permissions.

ByteMind includes three built-in subagents: explorer (read-only code exploration), review (code review), and general (general-purpose coding). You can also define custom subagents under .agents/agents/.

See Subagents.

MCP

MCP (Model Context Protocol) lets you extend ByteMind's tool capabilities through external MCP servers. Once configured, server-provided tools are automatically registered in the agent's tool list.

See MCP Setup and Usage.

Context Budget

ByteMind tracks token consumption per session and warns before approaching the model's context window limit:

• warning_ratio (default 0.85): emits a warning at 85% usage
• critical_ratio (default 0.95): triggers compaction or stops at 95% usage

Adjust these thresholds in the context_budget section of your config file.