Velocity

Local-first workspace for Claude Code, Codex CLI, and Gemini CLI. Inspect sessions, track costs, manage tools/skills, and run workflow automation from one dashboard.

Why Velocity

• 100% local — No cloud, no accounts, no telemetry. Your data stays on your machine.
• Zero config — bun install && bun dev. SQLite database auto-creates on first run.
• Built for Claude Code, Codex CLI, and Gemini CLI — Parses local logs, normalizes usage analytics, and manages provider-scoped workflows/config.

Features

Beta features are functional but have known rough edges. See feature docs for details.

Quick Start

git clone https://github.com/OptimiLabs/velocity.git
cd velocity
bun install
bun dev

Open http://localhost:3000. That's it — no database setup, no environment variables, no external services.

Prerequisites

• Bun 1.0+ (used as package manager and runtime)
• Node.js 18+ (required by Next.js)
• Claude Code CLI (optional)
• OpenAI Codex CLI (optional)
• Gemini CLI (optional)

Installing Bun

If you don't have Bun installed, run one of the following:

# macOS / Linux
curl -fsSL https://bun.sh/install | bash

# Windows
powershell -c "irm bun.sh/install.ps1 | iex"

# Homebrew (macOS)
brew install oven-sh/bun/bun

After installing, restart your terminal and verify with bun --version.

Troubleshooting: better-sqlite3 bindings error

If you see an error like could not locate the bindings file referencing .pnpm/better-sqlite3, it means dependencies were installed with npm or pnpm instead of Bun. The native better-sqlite3 module must be compiled for the correct runtime.

Fix:

# Remove existing node_modules and reinstall with Bun
rm -rf node_modules
bun install

Important: Always use bun install — not npm install or pnpm install. Velocity uses Bun as both its package manager and runtime, and native modules like better-sqlite3 must be built for it.

Troubleshooting: Console terminals are blank / unresponsive

If the Console terminals show a black area but don't respond to input:

1. Check the WebSocket server started. Look for this line in bun dev output:

   WebSocket server + watchers started via instrumentation
   

   If you see failed to start WebSocket server instead, check that node-pty loads:

   node -e "require('node-pty')"
   

2. Hard-refresh the browser (Cmd+Shift+R / Ctrl+Shift+R) to clear cached state.

3. Clear persisted layout state. Open browser DevTools → Application → Local Storage → localhost:3000 → delete the console-layout-store key, then refresh.

4. Reinstall dependencies:

   rm -rf node_modules
   bun install
   bun dev
   

Architecture

Scripts

Project Structure

app/            → Pages and API routes (Next.js App Router)
components/     → React components organized by feature
  console/      → Terminal and console UI
  sessions/     → Session browser and detail views
  analytics/    → Charts, cost breakdowns, usage stats
  agents/       → Agent builder and management
  layout/       → Sidebar, navigation, shared layout
  ui/           → shadcn/ui primitives and custom components
hooks/          → Custom React hooks (useMultiConsole, useSessions, useAnalytics, etc.)
lib/            → Core logic
  cost/         → Cost calculator and pricing tables
  db/           → SQLite schema, migrations, queries
  parser/       → JSONL session log parser and aggregator
server/         → WebSocket server, PTY manager, console handler
stores/         → Zustand stores (console layout, swarm state)
types/          → TypeScript type definitions
docs/           → Documentation and feature guides

Security

Velocity is a local-only application. It does not make network requests beyond localhost (except for optional GitHub API calls in the Marketplace).

Important notes:

• API keys are stored with base64 encoding, not encryption. Do not share your SQLite database file.
• The WebSocket server binds to localhost:3001 only — it is not accessible from other machines.
• Session data is read from local provider directories (~/.claude/, ~/.codex/, ~/.gemini/).

See SECURITY.md for full details and known limitations.

Configuration

All configuration is optional. Velocity works out of the box with zero setup.

Roadmap

• Improve Codex/Gemini config and extension parity with upstream CLI changes
• Generate better AI hook implementations
• Integrate Claude setup and agent generation
• Improve agent-to-agent communication
• Improve token usage tracking and ways to reduce token consumption
• Add Kimi 2.5 and GLM model support
• Improve UI customization and theming options

Contributing

We welcome contributions! Please read CONTRIBUTING.md for guidelines on:

• Setting up your development environment
• Code standards and conventions
• Submitting pull requests

Interested in collaborating? Reach out at jaewonlee9642@gmail.com or open an issue.

Please note that this project follows a Code of Conduct.

License

GNU AGPL v3.0 or later — jaewon42