velocity

Velocity is a local-first command center that unifies Claude Code, Codex CLI, and Gemini CLI workflows into a single interactive interface. It provides three core loops: Run, where you execute tasks in local CLI sessions; Inspect, which surfaces usage metrics, latency, tool availability, and routing context; and Reuse, where proven patterns become Agents, Workflows, Skills, and Commands. With Velocity you can capture real work through Console and Sessions, transform repeated patterns into reusable automation, and visualize how data and commands flow through your routing graph. The built-in tooling supports building and running workflows, managing agents, and ordering complex command sequences with routing and analytics to help validate cost and correctness. You can regenerate actionable automation by turning successful sessions into reusable workflows and agents, then monitor their performance over time via the analytics surfaces.

What you can do in practice: create and modify workflows using the Workflow Builder, inspect session histories and transcripts, and route tasks through a graph to see how data flows between tools. Use Agents to encapsulate recurring tasks, Skills to define individual commands or prompts, and Hooks or Plugins to extend capability. Velocity also exposes a routing graph and analytics views to help you understand where time and cost are being spent, and to verify that automation remains correct as your setup evolves.

Prerequisites:

• Node.js or Bun-based environment (Velocity is built with Bun but can be run in compatible environments).
• Git installed to clone the repository.

Installation steps:

1. Clone the repository: git clone https://github.com/OptimiLabs/velocity.git cd velocity

2. Install dependencies (choose the recommended runner):

   • If using Bun (recommended): bun install
   • If using npm/yarn (alternative, depending on project setup): npm install

3. Start the development server:

   • With Bun: bun dev
   • If using node-based setup (alternative): node server.js

4. Open the app in your browser at http://localhost:3000

Notes:

• If you encounter PTY or terminal issues on macOS during setup, ensure proper permissions for any prebuilt binaries as described in the project's troubleshooting docs.
• If the port is in use, adjust the PORT environment variable or the server configuration accordingly.

Tips and common issues:

• Velocity runs locally and stores data on your machine by default; ensure you understand the local data implications if you enable remote sources.
• If Console PTY launch fails on macOS, run the suggested chmod commands to fix permissions for node-pty spawn-helper.
• When regenerating demos or sessions, you can specify a base URL and provider; ensure the provider is available locally or mocked for testing.
• If you modify routing or analytics, revalidate that your changes reflect correctly in the Routing Graph and analytics dashboards to avoid misinterpretation of cost or latency.
• Environment variables like PORT can be adjusted to fit your development environment; add any required API keys or tool credentials as environment variables if your workflows rely on external services.