BoneCode

BoneCode is a production-grade fork of OpenCode — an open-source AI coding agent built on a BoneScript-generated Node.js + PostgreSQL backend with pgvector RAG.

Install

npm install -g bonecode

Then run it from any project directory:

bonecode

Interfaces

BoneCode ships three ways to interact with the agent.

Terminal UI (default)

bonecode

Opens an interactive terminal session in the current directory. Type / to see all available commands.

| Key | Action | |-----|--------| | / | Show command menu (arrow keys to navigate, Enter/Tab to select) | | Ctrl+C | Interrupt the current agent request | | Ctrl+D | Exit | | ↑ / ↓ | Scroll through prompt history | | @<path> | Attach a file (Tab to autocomplete) |

Web UI

bonecode web

Starts the server and opens the web interface in your browser at http://localhost:3000/ui.

If you already have the server running separately (bonecode serve), just navigate to:

http://localhost:3000/ui

Build the web UI for production (optional — the server serves it automatically after building):

cd web && npm install && npm run build

The built assets are served from /ui. Without a build, the server serves the raw source files in dev mode — functional but without bundling.

Run the web UI in hot-reload dev mode (separate terminal):

cd web && npm install && npm run dev
# Opens at http://localhost:5173 with proxy to the BoneCode server

Headless server

bonecode serve

Starts the API server only (no TUI, no browser). Useful for CI, Docker, or connecting your own client.

Database modes

BoneCode automatically detects what's available:

| Mode | Setup required | Features | |------|---------------|----------| | PostgreSQL (full) | Docker | Sessions + agents + pgvector RAG + hybrid search + durable events | | SQLite (basic) | Nothing | Sessions + agents only — no RAG, no vector search |

No Docker? BoneCode falls back to SQLite automatically — fully working agent, just without codebase indexing.

Want the full experience? Install Docker and run bonecode — it starts Postgres automatically on first run.

Install Docker: https://docs.docker.com/get-docker/

Configuration

Copy .env.example to .env and set your LLM provider:

cp .env.example .env

Minimum config for a local model (LM Studio / Ollama):

DEFAULT_PROVIDER=openai_compatible
DEFAULT_MODEL=your-model-name
OPENAI_BASE_URL=http://localhost:1234/v1
OPENAI_API_KEY=not-needed
MODEL_SUPPORTS_TOOLS=false

For cloud providers just set the API key — no base URL needed:

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...
DEFAULT_PROVIDER=anthropic
DEFAULT_MODEL=claude-sonnet-4-5

# OpenAI
OPENAI_API_KEY=sk-...
DEFAULT_PROVIDER=openai
DEFAULT_MODEL=gpt-4o

# Google
GOOGLE_API_KEY=...
DEFAULT_PROVIDER=google
DEFAULT_MODEL=gemini-2.0-flash

CLI commands

bonecode                    Start server + open TUI
bonecode serve              Start headless server only
bonecode web                Start server + open web UI in browser
bonecode run "fix the bug"  Send a one-shot prompt
bonecode run -i             Interactive terminal mode (no TUI)
bonecode stats              Show token usage and cost statistics
bonecode export [id]        Export a session as JSON
bonecode pr <number>        Checkout a GitHub PR branch
bonecode github install     Show GitHub Actions agent setup
bonecode compile            Recompile .bone domain models
bonecode migrate            Run database migrations
bonecode status             Check if server is running
bonecode --version          Show version

Stats

bonecode stats                  # all-time usage
bonecode stats --days 7         # last 7 days
bonecode stats --models 5       # show top 5 models
bonecode stats --tools          # show tool usage breakdown

Export

bonecode export                 # export most recent session
bonecode export <session-id>    # export specific session
bonecode export --sanitize      # redact file paths, tool outputs, etc.
bonecode export > session.json  # pipe to file

What's different from OpenCode

• BoneScript-aware — every session loads a 13KB BoneScript primer so the agent knows how to write .bone specs, run bonec compile, and use the extension-point workflow. No more "BoneScript isn't a standard language" responses.
• BoneScript backend — domain models declared in .bone files, compiled to Express + state machines + saga flows + durable events
• pgvector RAG — hybrid search (vector + BM25 + RRF fusion), works without an embedding model using structural context
• Web UI — browser interface at /ui in addition to the TUI
• mDNS discovery — server announces itself as bonecode.local on the local network
• Cursor pagination — v2 session and message APIs support bidirectional keyset pagination
• Subagent spawning — POST /v2/session/:id/subagent creates and runs a child session
• Single command — bonecode starts everything in one process
• SQLite fallback — works out of the box without Docker

BoneScript workflow (quick reference)

BoneCode treats BoneScript as the canonical way to build backends. When you ask the agent for a backend feature, it will:

1. Define — edit a .bone file under bone/
2. Compile — run bonec compile to generate routes, models, migrations
3. Extend — add custom logic only in extensions/
4. Check — run bonec check to validate

Install the compiler if you don't have it:

npm install -g bonescript-compiler

The agent never hand-writes models/, routes/, migrations/, or runs prisma migrate / drizzle-kit push / nest g. That's all generated from .bone files.

Build mode (autonomous orchestration)

For project-scoped prompts ("build me", "create a full", "design and implement"), BoneCode automatically enters build mode — a state machine that drives small/local models (8-20B) through narrow, focused stages instead of trusting them with one giant context.

How it works

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│ CLARIFY  │ ──▶ │   PLAN   │ ──▶ │ EXECUTE  │ ──▶ │  VERIFY  │
│ (Q&A)    │     │ (todos)  │     │ (loop)   │     │ (yes/no) │
└──────────┘     └──────────┘     └──────────┘     └──────────┘

1. Clarify — model asks 1-3 specific questions or proposes a design document. You answer, the design is locked in.
2. Plan — model produces a structured todo list (5-15 concrete file actions).
3. Execute — for each todo, the model gets a single focused prompt and must call tools. Prose-only responses are detected and rejected; the system injects a reminder.
4. Verify — for each design requirement, the model gives a yes/no verdict with evidence. Only done when all requirements are satisfied.

Triggering build mode

Auto-detected for prompts like:

• "build me a 2D market simulation"
• "create a full e-commerce backend"
• "design and implement a chat app"

Or trigger it explicitly:

/build a 2D market simulation with 1000 shops over 100 years

Why this works for small models

• Narrow prompts at each stage — the model isn't asked to plan a project, write code, AND verify in one breath
• Structured outputs (JSON) — parsed deterministically, never trusted as prose
• Forced tool calls in execute stage — describing what would be done isn't enough
• Persistent state — each todo's success is recorded in the DB, resumable across restarts
• Re-planning on failure — unsatisfied requirements automatically generate fix-up tasks

State is stored in the sessions.build_state column. You can inspect progress via the TUI or by querying the database directly.

Architecture

See ARCHITECTURE.md for the full design.

Folder structure

BoneCode/
├── bone/               # BoneScript domain specs (.bone files)
│   ├── session.bone    # Session, Message, Part, Project
│   ├── agent.bone      # AgentInstance, Task, Plan, ToolCall
│   ├── rag.bone        # KnowledgeBase, CodeFile, CodeChunk (pgvector)
│   ├── workspace.bone  # Workspace, Codebase, Snapshot
│   └── output/         # Generated backend (do not edit)
├── src/
│   ├── cli.ts          # bonecode CLI entry point
│   ├── tui.ts          # Interactive terminal UI
│   ├── server.ts       # Express server (auto Postgres/SQLite)
│   ├── mdns.ts         # mDNS/Bonjour local network discovery
│   ├── stats.ts        # Token/cost statistics
│   ├── export.ts       # Session export with PII redaction
│   ├── db_adapter.ts   # Database detection + SQLite shim
│   └── engine/         # Agent loop, tools, context builder
├── web/                # Web UI (vanilla TypeScript + Vite)
│   ├── index.html
│   ├── src/
│   │   ├── main.ts     # Entry point
│   │   ├── app.ts      # Main app class
│   │   └── api.ts      # API client
│   └── vite.config.ts  # Dev server with proxy to :3000
├── compat/
│   └── opencode_adapter.ts  # OpenCode v2 API compatibility layer
└── extensions/         # Custom extension points (embeddings, chunking, etc.)