VoidCode

A terminal-first AI coding assistant with a Plan → Build workflow. Tools run on your machine, billing runs metered credits, and the whole UI lives in your terminal.

• PLAN mode — read-only analysis. Explore, research, propose. No files touched.
• BUILD mode — full implementation: read, write, edit, shell. Git-style diffs render inline.

Features

• Terminal UI built with React + @opentui/react — react-router in your terminal.
• Local tool execution — readFile, writeFile, editFile, listDirectory, glob, grep, bash run on the client. File tools are confined to the project directory; bash is not sandboxed — treat model-issued commands like any untrusted script.
• Inline diffs — every writeFile / editFile produces a git-style diff with line numbers, rendered in-stream.
• Two modes — PLAN exposes only read tools and a read-only system prompt; BUILD unlocks writes and shell.
• Multi-provider streaming — Anthropic (Claude), OpenAI (GPT-5.4), and Google (Gemini) via the Vercel AI SDK, streamed over SSE.
• Persistent sessions — every session + its messages are stored in Postgres; interrupted turns are snapshotted client-side and flushed on stop/leave.
• Auth + metered billing — Clerk OAuth for identity, Polar for credits. Usage is metered per token, pegged at $0.01 = 1 credit, with checkout and customer-portal routes.
• Theming — swappable color themes with plan/build/thinking/success states.

Tech Stack

Layer	Tech
Runtime / PM	Bun
Language	TypeScript
TUI	React 19, @opentui/react, react-router
Server	Hono
AI	Vercel AI SDK v6/v7 (ai, @ai-sdk/*)
Database	Prisma + PostgreSQL
Auth	Clerk
Billing	Polar
Observability	Sentry
Validation	Zod

Monorepo

packages/
├── cli/        # Terminal UI + local tool runner (the `voidcode` bin)
├── server/     # Hono API — chat streaming, sessions, auth, billing
├── database/   # Prisma schema + generated client
└── shared/     # Types, zod schemas, tool contracts, model registry

Workspaces are wired through Bun — @voidcode/* packages reference each other via workspace:*.

Quickstart

Prerequisites: Bun, a PostgreSQL database.

# install
bun install

# set up env
cp .env.example .env
# fill in DATABASE_URL, ANTHROPIC_/OPENAI_/GOOGLE_ keys, Clerk + Polar creds

# database
cd packages/database
# generate the Prisma client and push the schema
npx prisma generate
npx prisma db push
cd ../..

# run both (in separate terminals)
bun run dev:server   # Hono on :3000
bun run dev:cli      # TUI (watch mode)

To build and link the voidcode command globally:

bun run link:cli

Scripts

Script	What it does
bun run dev:server	Hono server with hot reload
bun run dev:cli	TUI in watch mode
bun run build:cli	Bundles the CLI to packages/cli/dist
bun run link:cli	Builds, then bun links voidcode globally

How it works

1. You type a prompt in the TUI with a mode + model selected.
2. The CLI POSTs to /chat on the server with the session id, messages, mode, and model.
3. The server streams an AI response back over SSE. When the model emits a tool call, the useChat hook catches it and runs the tool locally — file reads/writes/shell happen on your machine, never on the server.
4. The tool output is fed back into the stream; the assistant continues until done.
5. On finish, the server persists the session messages and meters usage to Polar. On interrupt, the client owns the snapshot and flushes it via PUT /sessions/:id.

Tool-execution lives in the client by design: the server is a thin streaming + persistence + billing layer, and your filesystem never leaves your machine.

Environment

See .env.example for the full list:

• API_URL — where the CLI finds the server (default http://localhost:3000)
• DATABASE_URL — PostgreSQL connection string
• ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_GENERATIVE_AI_API_KEY — model providers
• CLERK_* — OAuth client, publishable/secret keys, JWT secret
• POLAR_* — access token, product id, server (sandbox/production), credits meter id

Supported Models

Anthropic claude-sonnet-4-6 · claude-haiku-4-5 · claude-opus-4-6 · OpenAI gpt-5.4 / -mini / -nano · Google gemini-3-pro-preview · gemini-2.5-flash · gemini-3-flash. Default: gemini-2.5-flash.