Bobbit

Your AI dev team, running on your machine, controlled from your browser.

Bobbit is a command centre for AI coding agents. Spin up teams — leads that plan, coders that build in parallel, reviewers and testers that enforce quality — and point them at anything from a quick bug fix to a full-stack feature. Watch every agent work in real time, steer them mid-task, and stay in control of what ships.

Quick start

npx @gresearch/bobbit

That's it. Bobbit scaffolds its .bobbit/ state/config directory, creates the built-in Headquarters workspace for the server run directory, starts a gateway on http://localhost:3001, and opens your browser. Send your first prompt and watch it work.

For a detailed walkthrough of your first session, see the Getting Started guide.

Quick start (from source)

If you have a Bobbit source checkout, use the run script to launch it against any project directory — no global install needed.

git clone <repo> bobbit

# From your project directory:
/path/to/bobbit/run                    # Linux/macOS
C:\path\to\bobbit\run.cmd              # Windows

On first run, the script auto-installs dependencies and builds (npm install && npm run build). On subsequent runs, it detects when source files have changed since the last build and rebuilds automatically — so git pull && ./run just works.

Each project gets its own .bobbit/ state directory, and ports auto-increment so you can run multiple instances side by side. All CLI flags are forwarded:

/path/to/bobbit/run --host 0.0.0.0 --port 3005 --no-tls

See Run from Checkout for full details, PATH integration, and troubleshooting.

CLI flags

bobbit [options]

--host <addr>          Bind address (default: localhost)
--port <n>             Port (default: 3001)
--base-path <path>     Mount the production UI and API below a URL path (default: /)
--public-origin <url>  Trust an externally visible gateway origin (repeatable)
--vite-origin <url>    Trust a browser-visible Vite development origin (repeatable)
--nord                 Bind to NordLynx mesh IP (remote access via NordVPN meshnet)
--tls / --no-tls       Override TLS auto-detection
--no-auth              Disable token authentication (loopback-only escape hatch)
--auth                 Explicitly re-enable authentication; retained for compatibility
--cwd <dir>            Working directory for agent sessions (default: .)
--agent-cli <path>     Path to pi-coding-agent cli.js
--static <dir>         Serve a custom UI build directory
--no-ui                Gateway-only mode (no UI)
--new-token            Force-generate a new auth token
--show-token           Print the current token and exit
--version              Print the installed Bobbit version and exit

BOBBIT_PUBLIC_ORIGINS and BOBBIT_VITE_ORIGINS provide comma-separated environment alternatives to the repeatable flags. Command-line values replace their corresponding environment list. Origins must be absolute http:// or https:// origins without credentials, non-root paths, queries, or fragments; invalid values stop startup.

See the Networking guide for trusted-authority, Vite, base-path, and reverse-proxy configuration.

From source

git clone <repo> && cd bobbit
npm install
npm run build     # compile server + bundle UI
npm start         # start gateway on :3001

The UI build enforces bundle budgets via tests/bundle-size.test.ts: the main index-*.js chunk ≤ 250 kB gzipped, every non-worker chunk ≤ 200 kB gzipped, and no non-worker chunk over 600 kB raw (which pins Vite's chunkSizeWarningLimit). Run npm run test:bundle to build and assert in one shot. See docs/design/ui-bundle-size-reduction.md for the route-splitting and lazy-loading patterns that keep the bundle small.

From global install

npm install -g @gresearch/bobbit
bobbit

Why Bobbit?

Most AI coding tools are either locked inside an IDE or limited to a terminal. Bobbit is different:

• Use any device — Work from your laptop, phone, or tablet. Start a task on your desktop, check progress from your phone. Multiple devices can connect to the same session simultaneously.
• Full agent power — The agent has real shell access. It reads your codebase, edits files, runs builds and tests, searches the web, and automates browsers. No copy-pasting code snippets.
• Watch everything happen — Every file read, shell command, and edit streams to your browser in real time with rich tool-call renderers. You see exactly what the agent is doing and can steer it at any point.
• Sessions survive everything — Sessions persist to disk. Restart the server, close your browser, lose your connection — pick up right where you left off.
• Zero config — npx @gresearch/bobbit and you're running. No API keys to configure (uses your existing ~/.pi/ credentials), no Docker, no cloud setup.
• Runs anywhere, even offline — npm install @gresearch/bobbit uses only the npm registry, with no compile step and no postinstall network fetches. The fd and rg search binaries ship as a small (~3–5 MB) per-platform optional npm sub-package so search works out of the box without runtime downloads; airgapped machines and corporate networks are first-class. A startup connectivity probe wires PI_OFFLINE=1 through to agent subprocesses when the network is unreachable, so search tools fail fast with a clear error instead of stalling on doomed downloads.

Features

Multi-Project Support

Every server has a built-in Headquarters workspace for the server run directory, so first launch can start a Quick Session immediately. Register additional project directories with the same Bobbit server when you want repo-specific work. Normal projects get their own .bobbit/ directory for config and state; Headquarters aliases the server .bobbit/ scope. Config cascades hierarchically (Headquarters/server → project). Sessions, goals, staff, and search are scoped per project, with cross-project search enabled by default. The sidebar groups work under collapsible project rows, with Headquarters anchored first when visible.

Sessions

Each session is a running agent with its own conversation and persistence. Run multiple sessions in parallel, each working on different parts of your project. Connect from multiple devices at once.

Goals & Tasks

Track larger work items with structured goals. Each goal has a title, spec, state, and optional task board. Goals can create dedicated git worktrees for isolated work.

Teams

Coordinate multiple agents working together. A team lead spawns role agents (coder, reviewer, tester) that work on tasks in parallel, each in their own git worktree.

Workflows & Gates

Define quality stages — design, implement, test, review — as a DAG of gates. Each gate has criteria and enforced ordering. No cutting corners: the agent can't skip ahead.

Roles

Control what agents can do (tool access, system prompts) and how they behave. Use built-in roles or create your own.

Skills

Reusable templates for isolated sub-agents: code review, security review, test reports. Invoke them from any session for structured, repeatable outputs.

Marketplace

Distribute roles, tools, and skills as self-contained packs — directories that can also contribute panels, entrypoints, and routes. User packs come from a git repo or local source: installing copies the pack in, uninstalling deletes it. Bobbit also ships built-in first-party packs that are auto-resolved in place — active by default, toggle-only (you enable/disable, never install or uninstall), and non-removable as a source — so shipped features (e.g. the PR-walkthrough viewer) flow through the same pack API. Resolution walks one ordered list of packs so entities show up on the Roles/Tools/Skills pages tagged with their origin pack. See docs/marketplace.md and its built-in packs section.

Interactive Agent Prompts

Agents can ask you structured multiple-choice questions mid-task via the builtin ask_user_choices tool. An inline widget renders in the chat with up to 5 questions and an always-rendered free-text "Other" escape hatch. The tool is non-blocking — the agent's turn ends immediately and the session goes idle until you submit; your answers arrive as a tagged user message that wakes the agent on the next turn. See docs/non-blocking-ask.md for the architecture.

MCP Server Integration

Use any MCP (Model Context Protocol) server with Bobbit. Drop a .mcp.json in your project root (same format as Claude Code) and Bobbit auto-discovers, connects, and exposes all MCP tools — appearing in the Tools UI, system prompts, and role-based access control.

Each MCP server is presented to the model as a single tool (mcp_<server>) with on-demand operation discovery via mcp_describe — fixing context bloat and the OpenAI 128-tool cap when many MCP servers are installed. See docs/mcp-meta-tools.md.

Cost Tracking

Per-session token usage and cost, aggregated to goal and task level. Always know what you're spending.

Support Assistant

A built-in Support agent you launch from Headquarters (the LifeBuoy button, left of the QR button) to ask "how do I…" questions about Bobbit itself. It grounds answers in Bobbit's own docs + source and — after explicit confirmation — can apply server-side changes on your behalf via the bobbit gateway tools. It never mutates a running Bobbit without explaining the action and getting your go-ahead. See docs/support-assistant.md.

The Bobbit Mascot

A squishy pixel-art blob that lives in the UI — animated, expressive, and drawn entirely with CSS box-shadows. Each session gets its own colour identity. Role accessories (crown, magnifying glass, bandana) show what the agent is doing at a glance. See the sprite system docs.

Documentation

| Guide | Description | |---|---| | Getting Started | First session walkthrough and key concepts | | Features | Detailed feature reference | | AI Gateway Routing | Gateway setup, model discovery, provider routes, and operations | | Headquarters | Built-in server/default workspace | | Support Assistant | Built-in HQ agent that answers Bobbit questions and applies changes | | Architecture | System design, layers, and dependencies | | Development & Testing | Dev environment, hot reload, testing | | Goals & Workflows | Task tracking, gates, and verification | | Nested Sub-Goals | Goals that spawn child goals — teams, depth caps, roll-up, governance | | Marketplace | Pack-based install of roles, tools, and skills | | Agent Memory (Hindsight) | Built-in, dormant-by-default memory provider backed by Hindsight | | Bobbit Sprites | Pixel-art mascot, animations, and accessories |

Technical reference: REST API · WebSocket Protocol · Security · Networking

Contributing

See the development workflow guide for dev setup, and AGENTS.md for repo layout and common tasks.