Borealis Coder is a provider-portable, policy-first, resumable AI coding harness for autonomous repository work. It combines a compact asynchronous agent runtime with deterministic editing tools, durable SQLite sessions, context-efficient repository discovery, checkpoints, verification, MCP extensions, and an ACP v2 editor bridge.
Created and maintained by Till Striegel.
The project is deliberately dependency-light: the runtime uses the Python standard library, prompt-toolkit for interactive terminal input, and quickjs-ng for isolated JavaScript workflows on Python 3.11–3.13. Provider SDKs are not required. This keeps the execution boundary inspectable and makes the harness practical for local tools, CI workers, containers, and embedded applications.
Release status:
0.1.3is a production-oriented beta/release candidate. The offline acceptance suite, unit/integration tests, wheel build, and clean-install checks are part of the release process. Live provider behavior still depends on the selected API, model, account, and network environment. Use Docker or another operating-system sandbox for untrusted repositories or models; the native driver is resource-bounded process execution, not a kernel security boundary.
Modern coding agents need more than an LLM call wrapped around a shell. Borealis treats the following as first-class runtime subsystems:
- Programmatic tool calling: one JavaScript workflow can call many tools, filter their full results, and print a small summary.
- Agent orchestration: streaming model turns, tool cycles, cancellation, steering, fallback routes, stuck-loop detection, budgets, and compacted context.
- Deterministic code mutation: SHA-guarded writes, exact replacements, transactional patch validation, bounded deletion, checkpoints, and rollback.
- Repository intelligence: Git-aware discovery, hierarchical
AGENTS.mdinstructions, lazy skills, language-aware symbol extraction, ranked repository maps, search, and focused reads. - Least-privilege execution: workspace-root containment, symlink-escape prevention, centralized policies, interactive approvals, command classification, network gates, and Docker isolation.
- Durability and interoperability: SQLite/WAL sessions, event traces, full-history export, MCP tools, ACP v2 sessions, and Python entry-point plugins.
- Visible model progress: provider-supplied reasoning summaries stream separately from assistant answers and are shown by default.
- Evidence-based completion: repository-aware verification, Git diff/status reporting, usage/cost accounting, and structured terminal or JSON output.
The design was synthesized from a code-level review of the most-starred open-source coding harnesses as of August 20, 2026. See the research report and feature matrix.
python -m venv .venv
. .venv/bin/activate
python -m pip install -e .Initialize a workspace:
cd /path/to/project
borealis initSet a provider key, then start the persistent coding shell:
export OPENAI_API_KEY='...'
borealisEnter tasks one after another. Borealis keeps the same durable session, streams assistant responses, displays tool progress, and returns to the prompt after each turn. You can also provide the first task directly:
borealis "Fix the failing tests, verify the result, and summarize the changes"The explicit one-shot automation surface remains available through
borealis run.
Or use an eligible ChatGPT account through Codex-compatible authentication:
# Reuses a secure, readable file-backed Codex login when one exists.
borealis auth status
# Otherwise launches the official Codex sign-in flow into a Borealis-managed store.
borealis auth login
borealis \
--provider chatgpt \
--model gpt-5.6-terraborealis auth login --device-code is available for headless systems. This route
uses Codex OAuth credentials and the Codex Responses backend. It does not inspect
ChatGPT browser cookies, local browser profiles, or private web-session storage.
Borealis automatically selects the first configured provider whose credentials are available. You can select a route explicitly:
borealis \
--provider anthropic \
--model claude-opus-5 \
--mode workspace-write \
--approval on-riskThe built-in deterministic mock provider exercises the full model/tool/session loop without network access:
borealis evalFor an inspectable end-to-end write cycle:
BOREALIS_PROVIDER=mock borealis run --non-interactive OFFLINE_WRITE_DEMO| Command | Purpose |
|---|---|
borealis |
Open the persistent interactive coding shell (the primary local workflow). |
borealis chat / borealis interactive |
Explicit aliases for the interactive shell. |
borealis resume [SESSION_ID] |
Resume a saved session in the interactive shell; use --last for the latest. |
borealis run |
Execute one autonomous task for scripts and automation. |
borealis init |
Create .borealis/config.toml, ignore rules, skills, and plugin directories. |
borealis auth |
Inspect, create, or remove ChatGPT/Codex authentication. |
borealis doctor |
Check provider configuration, tools, Git, Docker, storage, and workspace access. |
borealis tools |
Print the effective built-in, plugin, and MCP tool palette. |
borealis config |
Print the merged configuration with secret-bearing fields redacted. |
borealis sessions |
List, inspect, export, or delete durable sessions. |
borealis rollback |
List or restore pre-mutation checkpoints. |
borealis maintenance |
Preview or apply event, trace, and checkpoint retention. |
borealis acp |
Serve Agent Client Protocol v2 over stdio. |
borealis eval |
Run deterministic offline acceptance checks. |
Examples:
# Open a new interactive session
borealis
# Resume the newest session in this workspace
borealis --continue
borealis resume --last
# Resume a specific session and immediately send a prompt
borealis resume sess_abc123 "Now implement the proposed change"
# Machine-readable one-shot events and final result
borealis run --json "Explain the current architecture"
# Inspect/export durable session history
borealis sessions show sess_abc123
borealis sessions export sess_abc123 --output session.json
# Stronger command isolation in the interactive shell
borealis --sandbox dockerRunning borealis without a subcommand opens a long-lived terminal shell over the
same AgentRunner, EventBus, policy engine, and SQLite session store used by
one-shot runs and ACP. A conversation therefore survives multiple prompts and can
be resumed after the process exits.
The interactive surface is the Aurora Shell: a responsive, color-aware inline
TUI backed by prompt-toolkit, with a session prompt, framed assistant responses, live
elapsed-time pulses, a model/tool/verification activity rail, structured slash
commands, and compact turn receipts. It preserves terminal scrollback and falls
back to clean uncolored output for pipes, basic terminals, and NO_COLOR.
Common commands inside the shell:
| Command | Effect |
|---|---|
/status |
Show provider, model, safety settings, active session, usage, and cost. |
/sessions [N] |
List recent sessions for the current workspace. |
/resume [ID or last] |
Resume a durable session without leaving the shell. |
/history [N] |
Show recent persisted messages from the active session. |
/new or /clear |
Begin a fresh conversation while retaining the old session. |
/provider [NAME MODEL] |
List providers or switch provider/model for this process. |
/model MODEL |
Switch models while keeping the current durable session. |
/mode, /approval, /network, /verify, /sandbox |
Inspect or change runtime controls. |
/tools [FILTER], /doctor, /rollback [ID] |
Inspect tools, diagnose the runtime, or restore a checkpoint. |
/paste |
Enter a multiline task and finish it with a line containing only /end. |
/exit or /quit |
Close the shell. |
Delegation supports bounded recursive swarms. Defaults allow two levels, eight
cumulative descendants, two simultaneous delegated provider operations, and six
turns per child. Every delegate_task call must explicitly select
capability: "read-only" for investigation/review or capability: "write" for
implementation/file edits. A child cannot exceed its parent's permissions;
requests above that ceiling fail before admission, without a silent downgrade.
Normal workspace-write/full parents can select write without another opt-in.
Trusted agent.swarm_allow_writes = false or /swarm-writes off disables write
delegation for future runs. This operator ceiling defaults to true; it does not
select any child's capability. Normal approvals, protected paths, checkpoints,
and verification still apply; children cannot use shell, network, or Script.
Set swarm_max_depth or swarm_max_descendants to 0 to disable delegation.
See configuration.
The live Aurora swarm tree appears when delegation starts. Press F6 to inspect
agents with arrows, Left/Right to fold/expand, Page Up/Down for evidence,
and Enter to return to your draft. F7 or /swarm toggles the view. The tree
shows admitted capabilities, live state, and shared limits without replacing
terminal scrollback. See interactive controls.
Press Ctrl+C while a turn is running to cancel that turn and retain the shell and
session. At the input prompt, Ctrl+C exits. Prefix a literal slash-leading prompt
with another slash, such as //explain /api/users.
Useful startup options include --continue, --resume SESSION_ID, --no-stream,
--show-tool-output, and --no-history. Prompt history is stored separately from
model conversation history under the configured Borealis data directory and uses
mode 0600 on Unix. See the complete interactive CLI reference.
Borealis applies policy before every tool invocation.
| Mode | Behavior |
|---|---|
plan |
Read-only repository work plus structured plan updates. |
workspace-write |
Reads and deterministic mutations inside configured workspace roots; risky effects require policy approval. |
full |
Enables the broadest effect surface, while preserving explicit network, commit, push, and path gates. |
The default is workspace-write, approval = "on-risk", and network = false.
Opt in to automatic AI review of risky operations:
borealis run --approval smart --non-interactive "Fix the failing tests"smart sends policy ASK decisions to a separate, tool-free request using the
configured primary provider and model. It never asks a human and fails closed on
invalid replies, failures, or exhausted budgets. Low-risk ALLOW operations stay
fast; DENY operations stay blocked. Reviews share run request/time/cost limits,
add model cost, and are never cached. Network, shell, Git and file-tool path gates
still apply. This is a fallible automatic reviewer, not a security boundary.
See the security model for details.
Important invariants:
- Relative file paths resolve from the session workspace.
- Resolved paths must remain inside an allowed root unless explicitly configured otherwise.
- Symlink traversal cannot escape a root.
- Existing-file writes require the caller to provide the SHA-256 observed during a prior read.
- Multi-file patches are prevalidated before any mutation and checkpointed before application.
- Protected recovery and repository-control paths such as
.gitand.borealis/checkpointscannot be mutated through file tools. - Network commands, Git hooks, Git commits, and Git pushes have independent hard gates.
- Provider keys and likely secret values are redacted from traces and persisted errors.
With the native process driver, network = false allows only a small set of
network-inert inspection commands. Other commands are blocked because a host
process cannot otherwise be prevented from opening sockets. Select the Docker
driver to run them inside a network-disabled container.
Read SECURITY.md and the security model before enabling autonomous execution in sensitive environments.
Configuration is merged in this order:
- Built-in defaults
~/.config/borealis/config.toml<workspace>/.borealis/config.toml- An explicit
--configfile - Environment variables
- CLI overrides
Minimal workspace configuration:
[context]
include_git_status = true
instruction_names = ["AGENTS.md", "BOREALIS.md", "CLAUDE.md"]
skill_dirs = [".agents/skills", ".borealis/skills"]Workspace configuration is repository-owned and cannot change provider
selection, budgets, safety, sandbox, storage, cache, telemetry, or context
resource ceilings by default. Put those settings in the user configuration or
an explicit --config file. To trust them in a workspace file, set
BOREALIS_ALLOW_WORKSPACE_AUTHORITY=1 outside the repository. MCP servers and
provider endpoints still require their dedicated opt-ins.
Trusted user or explicit-file provider override:
[providers.openai]
type = "openai"
base_url = "https://api.openai.com/v1"
api_key_env = "OPENAI_API_KEY"
model = "gpt-5.4-mini"
api_style = "responses"
timeout_seconds = 180
max_retries = 4ChatGPT plan through Codex OAuth:
[agent]
provider = "chatgpt"
model = "gpt-5.6-terra"
[providers.chatgpt]
type = "chatgpt"
base_url = "https://chatgpt.com/backend-api/codex"
model = "gpt-5.6-terra"
api_style = "responses"
# auth_file = "~/.codex/auth.json" # optional explicit file-backed Codex loginCredential resolution checks CODEX_ACCESS_TOKEN, explicit configuration, an
existing file-backed Codex login, and the Borealis-managed login directory. Run
borealis auth status --json to inspect the selected source without printing any
token. Model availability and usage limits follow the signed-in ChatGPT account.
Because this subscription route does not expose API-dollar billing to Borealis,
local cost_usd remains zero; account-side usage limits remain authoritative.
OpenRouter:
export OPENROUTER_API_KEY='sk-or-v1-...'
borealis run --provider openrouter --model anthropic/claude-sonnet-4.6 "Fix the failing tests"[agent]
provider = "openrouter"
[providers.openrouter]
type = "openrouter"
base_url = "https://openrouter.ai/api/v1"
api_key_env = "OPENROUTER_API_KEY"
model = "anthropic/claude-sonnet-4.6"
api_style = "chat"
app_name = "Borealis Coder"
# site_url = "https://your-project.example"
model_fallbacks = ["openai/gpt-5.4-mini"]
[providers.openrouter.provider_preferences]
allow_fallbacks = true
data_collection = "deny"
zdr = trueapi_style = "responses" is also supported for OpenRouter models that expose the Responses API.
OpenRouter's own provider failover remains active by default; model_fallbacks adds model-level
fallbacks on top of it.
OpenAI-compatible local server:
[agent]
provider = "openai_compatible"
[providers.openai_compatible]
type = "openai_compatible"
base_url = "http://127.0.0.1:11434/v1"
model = "your-local-model"
api_style = "chat"See configuration reference and provider adapters.
The built-in palette includes:
script,script_job,discover_toolsrecord_finding,read_artifact,search_historyread_file,list_directory,glob_files,grepwrite_file,replace_in_file,delete_file,make_directoryapply_patchshellgit_status,git_diff,git_log,git_commit,git_pushfetch_urlupdate_planrepo_map,read_instructions,read_skillverifydelegate_task
All tool schemas use strict JSON-object contracts. Read-only calls can execute concurrently; mutations execute sequentially to preserve deterministic state.
glob_files treats **/ as zero or more directories. For example, **/*.json
under settings finds immediate and nested JSON files; settings/**/*.json does
the same from the workspace. Basename patterns such as *.json still find nested
files. Results are sorted and bounded, configured ignored directories are skipped,
and glob discovery does not follow file or directory symlinks.
Normal sessions expose a small native surface: script, script_job,
discover_tools, and the separate delegate_task capability. Use
discover_tools({names: [], offset: 0}) for the paged catalog, then exact names
for full argument schemas. Run work inside Script with await tools.NAME(args);
only printed output returns to the model. Discovery does not grant permission.
Script's provider-compatible object schema accepts
one literal JavaScript source string and a background boolean. For example:
const found = await tools.grep({
pattern: "TODO", path: ".", glob: "*.py", regex: false,
case_sensitive: true, context_lines: 0, max_results: 100, cursor: null
});
const paths = [...new Set(found.matches.map(match => match.path))];
const files = await Promise.all(paths.map(path => tools.read_file({
path, start_line: null, end_line: null, max_chars: null
})));
text({files: files.length, lines: files.reduce((n, file) => n + file.line_count, 0)});read_file returns selected UTF-8 content without line-number wrappers, plus
path, sha256, line_count, start_line, and end_line. It retains the file
byte ceiling; max_chars affects direct previews only. grep returns structured
matching lines and coverage/continuation metadata under the existing search and
file ceilings. Other tools return {output, is_error, metadata}; extensions may
supply structured data instead. Tool errors reject with error.result and count
as job errors even when caught. Edits retain short responses and hash/checkpoint
rules. Direct tools remain available with their existing preview caps.
Only text(...)/print(...) output and bounded job status enter the conversation.
Nested outputs are redacted and archived under session quotas; use
search_history and read_artifact to inspect retained evidence. JavaScript has
no native file, network, system, environment, Node, or Python APIs. Calls still
pass through Borealis policy and approvals. Recursive Script, job control, and
delegation calls are refused inside programs; use delegation directly.
Foreground work waits at most 300 seconds, then returns a live job_id and output
so far. background: true returns immediately. script_job accepts job_id,
action (status, wait, or stop), and seconds (0–300). Completion wakes the
owning run through events and a completion notice; the model need not poll. The
runner settles jobs before verification and final publication. Run cancellation,
budget expiry, stop, and runner close drain child calls and reap workers. Jobs are
run-scoped: handles expire at run end, and restart never replays uncertain work.
Partial effects remain visible; a Script is not an atomic transaction.
Script is enabled by default. Set [script] tool_surface = "direct" for explicit
legacy compatibility with the full native tool palette. Set [script] enabled = false in trusted
configuration to remove both tools from the effective palette. A missing or
unusable engine fails explicitly; no unsafe interpreter fallback is used. See
configuration limits and the
security boundary.
Borealis builds model context incrementally:
- It respects Git and
.borealisignoreexclusions. - It discovers
AGENTS.md,BOREALIS.md, andCLAUDE.mdfrom the repository root down to the active path. - It discovers project skills in
.agents/skillsand.borealis/skills, but injects only compact descriptions until a skill is explicitly loaded. - It extracts symbols for common programming languages and ranks files against the task query.
- It gives the model search/read tools instead of front-loading the entire repository.
- It compacts validated turn bundles to a calculated provider target while retaining append-only full history and reusable versioned artifacts in SQLite. See Compaction v2.
- It keeps a deterministic system-context prefix for provider prompt caching and appends Git status and request-ranked context afterward.
- It reports provider cache reads, writes, hit rate, and savings, and can reuse short-lived exact text-only responses without replaying tools. Validated provider continuation state is retained so cached responses remain resumable.
- Typing
/at the interactive prompt opens a compact command selector with descriptions; continue typing to narrow it and use Tab to complete.
verify detects common project types and runs focused checks under the same process policy as ordinary shell commands. Current built-in detection covers:
- Python (
ruff,pyright, andpytestwhen installed; otherwiseunittest) - JavaScript/TypeScript (
npmorpnpmlint, typecheck, test, and build scripts when present) - Rust (
cargo fmt, offlinecargo check, and offlinecargo test) - Go (
go test ./...andgo vet ./...) - Make-based repositories (
make testwhen no more specific project plan was detected)
Automatic verification runs after mutations when agent.auto_verify = true. A failed verification changes the process exit status even when the model produced a nominal end-turn response.
Borealis can connect to Model Context Protocol servers over stdio or Streamable HTTP. Tools are namespaced by server name and pass through the local policy engine.
[mcp_servers.issues]
type = "stdio"
command = "python"
args = ["/absolute/path/to/server.py"]
timeout_seconds = 30
allowed_tools = ["search_issues", "read_issue"]
read_only_tools = ["search_issues", "read_issue"]Workspace-defined MCP servers require the external
BOREALIS_ENABLE_WORKSPACE_MCP=1 opt-in. Remote MCP annotations can increase
local risk, but only read_only_tools can lower a tool to read-only policy.
MCP server failures are isolated: a failed optional server does not corrupt the core registry or session state. See protocol documentation.
Run the stdio server:
borealis acpThe server implements the ACP v2 baseline plus advertised session-delete, additional-directory, and MCP capabilities for editor and client integrations:
- initialization and capability negotiation
- session create, list, resume, close, and delete
- optional full-history replay
- foreground prompt acceptance and streamed updates
- cancellation and mid-run steering
- plan, message, tool, usage, and state updates
- client-mediated permission requests
- additional workspace roots
- per-session MCP server configuration
The portable Borealis operator skill teaches an
external agent to delegate bounded tasks through borealis run, choose explicit
permissions and budgets, parse results, resume sessions, and independently verify
changes. It does not depend on a particular agent host.
Install the CLI as above, then copy skills/borealis/ from this repository or
source distribution into your agent's supported skill directory. For example,
to make it available in a project's .agents/skills directory, run from this
checkout (replace the target with the actual project path):
mkdir -p /path/to/project/.agents/skills
cp -R skills/borealis /path/to/project/.agents/skills/Use your host's own skill location if different, and reload its skill catalog
if needed. Inspect an existing borealis skill before replacing it. The skill
ships in the repository and source distribution; installing the Python wheel
installs the CLI, not a skill into your agent's configuration. The operator
skill is distinct from project-local skills that Borealis itself consumes.
import asyncio
from pathlib import Path
from borealis_coder import build_runner, load_config
async def main() -> None:
workspace = Path(".").resolve()
config = load_config(workspace)
runner = await build_runner(workspace, config=config, interactive=False)
try:
result = await runner.run("Inspect the repository and propose three improvements")
print(result.text)
print(result.session_id, result.usage.total_tokens)
finally:
await runner.close()
asyncio.run(main())- Tools: package entry points in the
borealis.toolsgroup. - Workspace plugins: Python files in
.borealis/plugins, disabled unlessBOREALIS_ENABLE_WORKSPACE_PLUGINS=1. - Skills: Markdown skill files in configured skill directories.
- MCP: local or remote tool servers.
- Providers: register a
ProviderFactoryin a customProviderRegistrypassed tobuild_runner. - Clients: use ACP v2 or subscribe directly to the in-process
EventBus.
See extending Borealis.
make test
make smoke
make checkThe release gate checks:
- all tests and offline agent acceptance
- Python compilation
- strict tool schemas
- package metadata and required documentation
- secret-marker hygiene
- wheel/sdist construction and clean installation
- CLI import,
--version,doctor, andeval
The generated validation manifest records the commands, environment, source statistics, artifact hashes, and known limitations.
- Architecture
- Research and benchmarked harnesses
- Frontier feature matrix
- Security model
- Configuration reference
- Provider adapters
- MCP and ACP protocols
- Extension guide
- Operations
- Release checklist
MIT. Borealis Coder is a clean-room implementation. It incorporates architectural lessons from public repositories and protocols, not copied source code.