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:

1. Run work in local CLI sessions.
2. Inspect usage, cost, latency, tools, and routing context.
3. 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.

Routing Graph

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

Sessions Journey

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

Review Compare

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

Back-to-Back Reel

All demos played continuously.

Stitched Reel

Continuous reel with short holds between each section.

Regenerate all demos:

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

Start in 60 Seconds

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

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

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:

1. Use Console and Sessions to capture real work.
2. Convert proven patterns into Agents and Workflows.
3. 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:

rm -rf node_modules
bun install

Console terminal blank / stuck

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

node-pty spawn-helper permission denied (macOS)

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

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.