ob-1

```text ██████╗ ██████╗ ██╗ ██╔═══██╗██╔══██╗ ███║ ██║ ██║██████╔╝═══ ╚██║ ██║ ██║██╔══██╗ ██║ ╚██████╔╝██████╔╝ ██║ ╚═════╝ ╚═════╝ ╚═╝ ``` [](https://github.com/Overbrilliant/ob-1/actions/workflows/ci.yml) [](https://github.com/Overbrilliant/ob-1/actions/workflows/fresh-install.yml) [](https://www.npmjs.com/package/@overbrilliant/ob1) [](https://github.com/Overbrilliant/homebrew-tap) [](LICENSE) [](https://deepwiki.com/Overbrilliant/ob-1) **The coding agent that needs no account.** Gemini CLI's free tier now routes through Antigravity (account required) and Codex's free plan needs a login. `ob1` still answers your first message with no account, no card, and no API key — install it and start.  *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.*  *A real session: OB-1 writes `primes.py`, runs it, and shows the output — on free models.*  *`/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 ```sh brew install overbrilliant/tap/ob1 ``` ### Native Installer ```sh 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: ```sh curl -fsSL https://github.com/Overbrilliant/ob-1/releases/latest/download/install.sh | sh -s -- --version v0.3.4 ``` ### npm ```sh npm install -g @overbrilliant/ob1 ``` The npm package needs Bun at runtime. ### Source Checkout ```sh 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: ```sh ./scripts/install.sh --binary ``` ## Quick Start Run OB-1 from a Git repository: ```sh 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: ```sh 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: ```text ob1 onboard ``` You can change the route later: ```text /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/](docs/): quickstart, install, free models, providers, core concepts, commands, troubleshooting, architecture, distribution, extensions, privacy, and eval notes. Useful commands: ```text /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. | ```text /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). **The self-fix loop cannot edit your tests.** The easy way to "make the checks pass" is to weaken an assertion or patch the test instead of the bug, so the loop guards against it. During a self-correction round, a `write_file` / `edit_file` / `architect_edit` to a path matching a test pattern (`test/`, `tests/`, `spec/`, `__tests__/`, `*.test.*`, `*.spec.*`, `*_test.*`, `test_*.py`) is refused, and the model is told to fix the source or to say plainly that the test itself is wrong and leave it for you. Outside a fix round, a test-file edit that follows any failing check in the same turn is allowed but flagged: a `⚠ TEST FILE EDIT after a failing check` line in the run output, a review finding in the quality ledger (`/quality`), and a reminder next to the final `✓ verified` line. Set `OB1_TEST_EDIT_GUARD=flag` to allow flagged test edits during self-correction, or `off` to disable the guard. Shell commands that rewrite a test are not intercepted; they stay visible through the normal diff and approval path. 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`](docs/multimind.md). ## Commands ### Shell ```text 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 ```text /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: ```sh 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`](docs/distribution.md). ## Development You need Bun `>=1.3.13`, Git, and macOS or Linux. ```sh bun install bun run start ``` Checks worth running before a PR: ```sh bun run scripts/cli-flags-smoke.ts bun run scripts/ci-smokes.ts bun run typecheck bun run lint ``` Build a standalone binary: ```sh bun run build:bin ``` ## Repository Layout ```text 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 ``` ## Status OB-1 is early public software. The CLI, install paths, memory engine, repo map, provider setup, MCP support, multi-agent modes, and smoke-test harness are active. Interfaces may change before `1.0`. Roadmap and design notes: - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) - [`docs/package-managers.md`](docs/package-managers.md) - [`docs/extensions.md`](docs/extensions.md) - [`docs/privacy.md`](docs/privacy.md) - [`docs/sharing.md`](docs/sharing.md) - [`docs/evals.md`](docs/evals.md) - [`docs/planning/PROGRESS.md`](docs/planning/PROGRESS.md) - [`docs/planning/ob1-plan.html`](docs/planning/ob1-plan.html) - [`docs/research/`](docs/research/) ## Security OB-1 can read project files, run shell commands, and interact with provider credentials. Do not put secrets in public issues, screenshots, prompts, or logs. Report suspected vulnerabilities privately. See [`SECURITY.md`](SECURITY.md). ## Contributing Focused, tested PRs are welcome. Start with [`CONTRIBUTING.md`](CONTRIBUTING.md) and follow [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). Community entry points are in [`COMMUNITY.md`](COMMUNITY.md). ## License Apache License 2.0. See [`LICENSE`](LICENSE).