README.md

August 27, 2026 · View on GitHub

   ██████╗ ██████╗      ██╗
  ██╔═══██╗██╔══██╗    ███║
  ██║   ██║██████╔╝═══ ╚██║
  ██║   ██║██╔══██╗     ██║
  ╚██████╔╝██████╔╝     ██║
   ╚═════╝ ╚═════╝      ╚═╝

OB-1 start-free demo

Start free: OB-1 works instantly with the free-model catalog — no account or card. Free users get newly released free models after 30 days; hosted plans get them immediately. Add your own provider keys to ~/.ob1/keys.env for higher limits.

OB-1 completing a task

A real session: OB-1 writes primes.py, runs it, and shows the output — on free models.

OB-1 memory inspector

/memory shows the facts and relationship graph OB-1 built from real work.

OB-1 is a free, open-source CLI coding agent built around parallel work: it fans independent sub-tasks out to isolated read-only subagents, and escalates hard changes to Fusion, which generates N candidate solutions in separate copies of the project and selects the candidate that passes your real checks. It keeps going until your checks pass — up to three self-correction rounds by default — then escalates or hands the changes back rather than reporting a silent success. No account, no card, no API key, and no ads: run ob1 in a repository and it reads the codebase, builds a repo map, edits files, runs checks, and keeps persistent project memory you can inspect between sessions.

The default path is free out of the box: OB-1 has an embedded free-models router built into the CLI process — no server, no clone, no Docker/Node dependency — backed by a signed free-model catalog. Keyless providers answer your first message with no setup. No API key, card, or account is required to start; free users get newly released free models after 30 days, hosted plans get them immediately, and your own provider keys in ~/.ob1/keys.env add predictable capacity.

What You Get

Repository context before answers. OB-1 ranks important files, tracks symbols, reads AGENTS.md, and keeps project notes it can reuse later.
A visible memory system. You can inspect facts, revisions, relationships, search results, and the memory graph from the CLI.
Tool use with opt-in guardrails. File edits, shell commands, MCP tools, browser checks, and verification helpers run through the agent loop. By default OB-1 runs in autopilot (it executes tools without prompting) with the OS sandbox off — fast, but it acts on its own. Turn on per-action approvals with OB1_PERMISSION=ask, and confine writes/network with OB1_SANDBOX=workspace-write or read-only (or set permissionMode / sandbox in settings.json). Even in autopilot, catastrophic commands (e.g. rm -rf /) are hard-blocked and destructive actions are flagged.
Free out of the box. Start instantly on keyless cloud free tiers, then add your own free provider keys to ~/.ob1/keys.env for better models and predictable monthly capacity.
Provider-neutral routing. Use your own OpenAI-compatible endpoint, OpenRouter, OpenAI, Gemini, Groq, Ollama, LM Studio, llama.cpp, vLLM, or a LAN GPU box.
Release paths people can test. Homebrew, npm, native archives, checksums, attestations, and fresh-machine install checks are part of the project.

Install

Homebrew

brew install overbrilliant/tap/ob1

Native Installer

curl -fsSL https://github.com/Overbrilliant/ob-1/releases/latest/download/install.sh | sh

The installer picks the right macOS/Linux archive for arm64 or x64, verifies it with checksums.txt, and installs ob1 into a bin directory when it can.

Pin a release:

curl -fsSL https://github.com/Overbrilliant/ob-1/releases/latest/download/install.sh | sh -s -- --version v0.3.4

npm

npm install -g @overbrilliant/ob1

The npm package needs Bun at runtime.

Source Checkout

git clone https://github.com/Overbrilliant/ob-1.git
cd ob-1
./scripts/install.sh

Source installs create a small launcher that runs this checkout through Bun. Pull the repo to update it. To build a standalone binary instead:

./scripts/install.sh --binary

Quick Start

Run OB-1 from a Git repository:

ob1

On first run, choose a model route. Pressing Esc at the first picker starts the free path.

Tier	What you do	Cost	Account?
Free (default)	`ob1` -> Start free	$0	No
Your endpoint	Export `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`, or set `OB1_BASE_URL` / `OB1_API_KEY`; or use `/models`	Your key or local model	No
Hosted frontier	`ob1 login` or choose Hosted frontier	Paid subscription	Yes

Free setup has nothing to install or run — the embedded free-models router is already part of the CLI. Keyless providers are a bootstrap path with variable quality and shared limits. Add your own free provider keys to ~/.ob1/keys.env for stronger free-tier coverage; manage the pool with /free.

BYOK env routes are runtime-only and are never persisted. For Gemini:

GEMINI_API_KEY=... OB1_MODEL=gemini-2.5-pro ob1

Hosted frontier is the convenience tier: no provider keys, one bill, Claude/GPT/Gemini/Qwen-class models through the managed OB-1 server.

If onboarding does not start, run:

ob1 onboard

You can change the route later:

/models       choose Free models or a subscription-backed model
/free         manage the free-models pool (keys, routing strategy, health)
/upgrade      subscribe or manage your plan

Full launch docs are in docs/: quickstart, install, free models, providers, core concepts, commands, troubleshooting, architecture, distribution, extensions, privacy, and eval notes.

Useful commands:

/help           show interactive commands
/agents regen   refresh the project AGENTS.md index
/map            inspect the ranked repository map
/memory         inspect stored project memory

Without a model connection, setup, repository mapping, and memory inspection still work. Coding tasks need a model.

Update checks are non-blocking and skip CI. Set OB1_NO_UPDATE_CHECK=1 to disable the version nudge.

Comparison

Capability	OB-1	Claude Code	opencode	aider
License	Apache-2.0	Proprietary	Open source	Open source
Works with no API key	Yes, via the embedded free-models router (keyless providers)	No	No	No
Local/LAN models	Yes	Limited	Yes	Yes
Persistent visible memory	SQLite + graph inspector	No	No	No
Multi-agent modes	Fusion best-of-N, verified escalation, refute-review, adaptive search	No	No	No
Sandbox/permissions	macOS Seatbelt, Linux bubblewrap, approvals	Yes	Varies	Limited
Hosted convenience tier	Optional paid	Required account	Bring your own	Bring your own

How It Works

Area	What happens
Agent loop	OB-1 plans, calls tools, reads results, and continues until the task is done or blocked.
Repository map	It ranks files by references and symbols so the agent starts with likely-relevant context.
Memory	It stores facts, revisions, relationships, embeddings, and graph edges in SQLite.
AGENTS.md	`/agents regen` refreshes the project memory index while keeping human-owned notes intact.
Tools	It can read files, edit files, run shell commands, inspect the repo map, search memory, use MCP tools, and run checks.
MCP	It connects to stdio, HTTP, and SSE MCP servers and exposes their tools inside the agent. The config file is shared with Claude Code — a project's existing `.mcp.json` works as-is.
Skills	Markdown skills stay discoverable without loading the full instructions into every prompt.
Safety	Approval gates, shell validation, macOS Seatbelt, Linux bubblewrap, and secret checks reduce accidental damage.

Agent Modes

Use /mode for the execution posture:

Mode	Use it for
`auto`	No questions asked: edits and commands run automatically.
`act`	Edits allowed, but OB-1 asks before mutating tools.
`plan`	Read-only investigation; no file or shell mutations.

/mode auto
/mode act
/mode plan

The normal orchestration path is still Solo: after a file-changing turn it reruns the project's checks and fixes failures. On a verified failure it escalates once to Fusion best-of-N automatically (/escalation toggles this). Use /fusion to force best-of-N for future turns, /review for an independent refute-reviewer over your diff, and /deep <task> for an adaptive AB-MCTS search. Any mode that cannot beat Solo at equal tokens is deleted — see docs/multimind.md.

Commands

Shell

ob1                 start the interactive CLI in the current directory
ob1 onboard         run guided setup
ob1 login           sign in to the managed OB-1 server
ob1 signup          create an account on the managed OB-1 server
ob1 logout          remove the local token
ob1 --help          show help
ob1 --version       print the version

Inside OB-1

/help                 show help
/mode auto|act|plan   switch execution mode
/permission ask|autopilot  toggle per-action approvals
/sandbox <mode>       switch shell sandbox mode
/memory               inspect memory
/memory add <text>    remember a fact
/memory search <q>    search memory
/map                  show the ranked repository map
/mcp                  list connected MCP servers and tools
/skills               list available skills
/fusion               switch future turns to Fusion best-of-N
/solo                 exit Fusion back to Solo
/review               refute-review the current diff
/deep <task>          adaptive AB-MCTS search
/escalation on|off    escalate verified failures to Fusion (default on)
/eval [modes…]        run compute-matched evals
/clear                reset conversation context
/exit                 quit

Releases and Verification

OB-1 publishes through:

GitHub releases with native macOS arm64/x64 and Linux arm64/x64 archives
Homebrew: overbrilliant/tap/ob1
npm: @overbrilliant/ob1

Release archives include checksums.txt. GitHub artifact attestations are generated for release assets.

Verify an artifact:

gh release download v0.3.4 --repo Overbrilliant/ob-1 --pattern ob1-darwin-arm64.tar.gz
gh attestation verify ob1-darwin-arm64.tar.gz --repo Overbrilliant/ob-1

Release signing, notarization, provenance, and install testing are documented in docs/distribution.md.

Development

You need Bun >=1.3.13, Git, and macOS or Linux.

bun install
bun run start

Checks worth running before a PR:

bun run scripts/cli-flags-smoke.ts
bun run scripts/ci-smokes.ts
bun run typecheck
bun run lint

Build a standalone binary:

bun run build:bin

Repository Layout

src/
  index.ts             CLI entrypoint and slash-command routing
  agent/               agent loop, tools, execution, recovery, verification, safety hooks
  cli/                 terminal UI, onboarding, login, and model setup
  context/             repository map, AGENTS.md, git state, LSP, topics
  eval/                task harness, runners, parity checks, reports
  mcp/                 MCP clients and server manager
  memory/              fact store, embeddings, ranking, reflection, export
  multimind/           Fusion best-of-N, verified escalation, refute-review, deep search, subagents, worker orchestration
  providers/           OpenAI-compatible model gateway
  safety/              shell policy, validation, and OS sandbox integration
  skills/              on-demand markdown skill registry
scripts/               smoke tests, install/build helpers, live probes
docs/                  distribution notes, roadmap, research, and planning material