Velocity

Velocity is a local-first command center for Claude Code, Codex CLI, and Gemini CLI. It helps you run sessions, understand what happened, and turn repeated work into reliable workflows.

Why Velocity

Most CLI-only workflows break down as your team scales:

session context is fragmented
routing/entrypoint behavior is opaque
reusable flows stay tribal knowledge

Velocity addresses this with three core loops:

Run work in local CLI sessions.
Inspect usage, cost, latency, tools, and routing context.
Reuse what works as agents, workflows, skills, and commands.

Preview

These GIFs are embedded directly in the README and render on GitHub.

Workflow Builder

AI Assist setup -> finished workflow canvas -> AI prompt review -> node prompt editing. Workflow Builder Demo

Routing Graph

Fullscreen routing deep-dive with readable node zoom and multi-node inspection. Routing Demo

Sessions Journey

Console -> Sessions -> Session Detail walkthrough with transcript filters and scrolling. Sessions Journey Demo

Review Compare

Two-session review workspace with compare scope and analysis controls. Review Compare Demo

Back-to-Back Reel

All demos played continuously. Back-to-Back Demo Reel

Stitched Reel

Continuous reel with short holds between each section. Stitched Demo Reel

Regenerate all demos:

BASH

python3 scripts/demo/capture-demos.py --base-url http://127.0.0.1:3000 --provider claude --target-seconds 12

Start in 60 Seconds

BASH

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

If Console PTY launch fails on macOS during setup, run:

BASH

chmod +x node_modules/node-pty/prebuilds/*/spawn-helper

Open http://localhost:3000.

Workflow-First Mental Model

If you only learn one thing, learn this:

Use Console and Sessions to capture real work.
Convert proven patterns into Agents and Workflows.
Use Routing and Analytics to validate that automation is actually correct and cost-efficient.

Feature Inventory

Velocity is organized into three layers:

Layer	Purpose	Key surfaces
Workspace	Run and inspect	Console, Sessions, Review, Analytics, Usage
Build	Reuse and automate	Agents, Workflows, Skills, Commands, Hooks, MCP, Routing
Platform	Configure and extend	Models, Plugins, Marketplace, Settings

Detailed inventory: docs/guides/functionality-inventory.md

Provider Parity

Capability	Claude	Codex	Gemini
Sessions + analytics ingestion	Yes	Yes	Yes
Agents (global + project scope)	Yes	Yes	Yes
Workflows	Yes	Yes	Yes
Skills + commands	Yes	Yes	Yes
Routing graph	Yes	Yes	Yes
Hooks	Yes	No	Yes
Plugins	Yes	No	No

Core Tech

Layer	Stack
Framework	Next.js 16 (App Router)
Runtime / PM	Bun
DB	SQLite (`better-sqlite3`)
State	TanStack Query + Zustand
Real-time	WebSocket + PTY manager
Graph UI	`@xyflow/react`
Tests	Vitest

Docs

Feature docs: docs/features/
Install + config guides: docs/guides/
Provider matrix: docs/guides/provider-capability-matrix.md

Troubleshooting

`better-sqlite3` binding errors

Reinstall with Bun:

BASH

rm -rf node_modules
bun install

Console terminal blank / stuck

Verify bun dev starts without PTY errors.
Hard refresh browser.
Clear persisted local layout state.

`node-pty` spawn-helper permission denied (macOS)

If PTY launch fails because spawn-helper is not executable:

BASH

chmod +x node_modules/node-pty/prebuilds/darwin-arm64/spawn-helper
# or (portable across prebuild folders)
chmod +x node_modules/node-pty/prebuilds/*/spawn-helper

Then restart bun dev.

Security

Velocity is local-first. Data stays on your machine by default. Optional remote calls are limited to explicit user-driven actions (for example marketplace sources).

See SECURITY.md for reporting and policy details.

Inquiries

For questions or inquiries, contact: jaewonlee9642@gmail.com

Contributing

See CONTRIBUTING.md for setup and PR workflow.