See every decision. Direct every action. Audit everything.
A desktop IDE that turns AI coding agents into transparent, graph-aware coding partners.
Multi-backend workflow orchestration (Claude + Codex) with visual pipeline builder, custom MCP tools,
knowledge-graph context injection, and an append-only audit trail of every choice your agents make.
Quick Start • What It Does • Architecture • Interface • Features • Testing
AI coding tools are black boxes. You paste a prompt, hope for the best, and get back code you didn't watch being written. You can't see what context the model used, what decisions it made, or why it chose one approach over another. And every tool forces you to pay for API access on top of whatever subscription you already have.
VIBE OS makes AI-assisted development visible, auditable, and directable — orchestrating multiple backends on top of your existing subscriptions.
| Requirement | Version | Why |
|---|---|---|
| Node.js | 18+ | Frontend + sidecar build tooling |
| Rust | 1.89+ | Tauri backend compilation |
| Claude Code CLI | Latest | Auth + execution backend (npm install -g @anthropic-ai/claude-code) |
| Git | Any | Repository management |
| NASM | Any | Windows only — required by SurrealDB's crypto deps |
No Anthropic API key required. VIBE OS authenticates through your existing Claude Code subscription.
# Clone
git clone https://github.com/TPal126/vibe-os.git
cd vibe-os
# Install frontend dependencies
npm install
# Build the Node agent sidecar (bundles the Claude Agent SDK)
cd agent-sidecar && npm install && npm run build && cd ..
# Run tests (205+ tests across Rust + TypeScript)
npm run test:all
# Launch in development mode
npm run tauri dev
# Build distributable binary (Windows/macOS/Linux)
npm run tauri buildFirst launch creates ~/.vibe-os/vibe-os.db, copies starter skill files to ~/.vibe-os/skills/, and spawns the agent sidecar which auto-detects your installed claude binary and available CLIs (git, gh, aws, docker, node, python, etc.).
VIBE OS is a reasoning-first desktop IDE that owns the orchestration layer on top of multiple AI backends. It runs a native agent loop via the Claude Agent SDK in a Tauri sidecar, supports multi-backend workflow pipelines (Claude + Codex), injects graph-aware context before every query, and exposes custom MCP tools that let agents read and write the knowledge graph directly.
- Multi-Backend Workflow Orchestration — visual pipeline builder with phase sequencing, gated transitions, and artifact handoff across Claude and Codex backends
- Native Agent SDK Loop —
@anthropic-ai/claude-agent-sdkrunning in a Node sidecar, not CLI stdout parsing - Backend Adapters — pluggable
BackendAdaptertrait with Claude, Codex, and test-fake implementations - Graph-Native Context — SurrealDB knowledge graph queried and injected into every system prompt
- VIBE OS MCP Tools — 6 custom tools let agents access provenance, impact analysis, architecture topology, and record their own decisions
- Multi-Project Home — project cards with resource summaries, delete support, up to 20 concurrent projects
- Project Setup Flow — two-step project creation with unified resource catalog and inline pipeline builder
- Pipeline Builder UI — drag-and-drop phase palette, backend/framework/model configuration per phase, gated vs. auto transitions
- Unified Events Timeline — single append-only log with both actions and decisions, kind-tagged, exportable
- Auto-Detected CLIs —
git,gh,aws,docker,kubectl,node,npm,python,cargo, etc. surfaced in system prompt and title bar - Light + Dark Themes — CSS-variable driven, toggle in title bar, persists across sessions
- Multi-Session Agents — run multiple agent sessions simultaneously with attention routing
- Agent Capture — save agent-spawned subagents as reusable
.mddefinitions in~/.vibe-os/agents/ - Knowledge Graph Visualizer — D3 force-directed view of repos, modules, functions, decisions, and sessions
+-----------------------------------------------------+
| Frontend |
| React 18 . TypeScript 5.5 . Zustand . Tailwind |
| Monaco . D3.js . Vite 6 . @dnd-kit . Lucide |
+-----------------------------------------------------+
|
Tauri IPC Bridge
|
+-----------------------------------------------------+
| Rust Backend |
| SQLite (WAL) . SurrealDB (embedded) |
| BackendAdapter trait (Claude / Codex / Fake) |
| WorkflowEngine . ArtifactStore . Graph context |
| Sidecar lifecycle + stdin/stdout bridge |
+-----------------------------------------------------+
| |
stdin/stdout JSON CLI spawn
| |
+---------------------+ +-------------------+
| Node Agent Sidecar | | Codex CLI |
| claude-agent-sdk | | JSONL events |
| VIBE OS MCP server | +-------------------+
+---------------------+
|
v
Claude Code binary
Why this architecture:
- No API key cost — the SDK uses your Claude Code subscription, not direct Anthropic API access
- Multi-backend — pluggable
BackendAdaptertrait lets the workflow engine dispatch phases to different AI backends (Claude, Codex) in a single pipeline - Typed messages — SDK emits structured
SDKAssistantMessage/SDKResultMessageevents directly, no stdout parsing gymnastics - Graph context injection — Rust assembles provenance and session history from SurrealDB before each query and appends it to the system prompt
- Custom tools — the sidecar exposes a VIBE OS MCP server whose tools call back into Rust for graph queries
- Zero wrapper overhead — we control the full prompt composition, tool orchestration, and event routing
The sidecar exposes an in-process MCP server with tools that give Claude direct access to your knowledge graph:
| Tool | Purpose |
|---|---|
vibe_graph_provenance |
Decision history, skill attribution, and test coverage for a function |
vibe_graph_impact |
Direct + indirect callers, dependent tickets, validating tests |
vibe_record_decision |
Agent records architectural choices with rationale, confidence, reversibility |
vibe_search_graph |
Free-text search across functions, modules, decisions, skills |
vibe_session_context |
Current session's action history, decisions, token spend |
vibe_architecture |
Module topology, import graph, call graph for a subsystem |
When Claude calls any of these, the request flows sidecar → Rust → SurrealDB → back to the SDK as a tool result. No guessing, no hallucinated history — the agent sees what actually happened.
Before every query() call, Rust extracts file and function references from the user's message, queries SurrealDB for provenance (decisions, skill attribution, test coverage) and session history, and injects it into the system prompt under a # VIBE OS Context section. This is where VIBE OS gets meaningfully smarter than raw Claude Code.
+-----------------------------------------------------------------------+
| VIBE OS 6 CLIs 0 repos 1 skill $0.00 - x |
+-----------------------------------------------------------------------+
| |
| PROJECTS |
| |
| +-------------------+ +-------------------+ +-----------------+ |
| | vibe-os (X) | | seat-sniper | | + New Project | |
| | 2 active | | idle | | | |
| | 3 repos 2 skills | | 1 repo | | | |
| | + New session | | | | | |
| +-------------------+ +-------------------+ +-----------------+ |
| |
| Clear all projects |
+-----------------------------------------------------------------------+
Each card shows name, active session count, resource summary chips, and a delete button on hover. The title bar shows CLI count, active repo/skill counts, cost, and a theme toggle.
Two-step flow: Step 1 — name, description, and resource catalog (repos, skills, agents with checkbox composition and drag-drop repo adding). Step 2 — visual pipeline builder.
+-----------------------------------------------------------------------+
| PIPELINE BUILDER |
| |
| +-------------+ +------------------------------------------+ |
| | PHASES | | PIPELINE CANVAS | |
| | | | | |
| | [Ideation] | | +----------+ gate +----------+ | |
| | [Planning] | | | Planning |------->| Execution| | |
| | [Execution] | | | Claude | | Codex | | |
| | [Verify] | | +----------+ auto +----------+ | |
| | [Review] | | | |
| | [Custom] | +------------------------------------------+ |
| +-------------+ |
| +------------------------------------------+ |
| | PHASE CONFIG | |
| | Backend: [Claude v] Framework: [React v] | |
| | Model: [Sonnet v] Prompt: [...] | |
| +------------------------------------------+ |
+-----------------------------------------------------------------------+
Drag phases from the palette onto the canvas, configure backend/framework/model per phase, and toggle gated vs. auto transitions between phases.
Click a project and you get the quadrant layout: full chat on the left with inline activity cards, knowledge graph visualizer on the right, resource controls and audit trail in the bottom quadrants. Rich cards render inline: file modifications, test results with pass/fail breakdowns, architectural decisions, preview URLs, outcome summaries with cost and token counts. Pipeline runs show a PhaseIndicator header with current phase and progress, GatePromptCard for human-gated transitions, and InteractionCard for framework question/answer flows.
Define multi-phase development workflows with a visual drag-and-drop builder. Each phase can target a different backend (Claude or Codex), a specific framework, and a model. Phases connect via gated transitions (human approval required) or auto transitions (proceed on success). The WorkflowEngine in Rust dispatches each phase to the appropriate BackendAdapter, the ArtifactStore passes context between phases, and inline conversation cards (PhaseIndicator, GatePromptCard, InteractionCard) let you monitor and control the pipeline from the chat view.
VIBE OS runs @anthropic-ai/claude-agent-sdk in a Node sidecar process managed by Tauri's shell plugin. Messages flow through typed SDKMessage events — no CLI stdout parsing, no event classification heuristics. The sidecar manages session lifecycles (multi-turn via streamInput(), cancel via query.close(), resume across restarts) and exposes the VIBE OS MCP server so custom tools are available to Claude on every call.
SurrealDB stores a knowledge graph of your code (repos, modules, functions, classes) connected to every decision, action, test, and skill your sessions produce. Before each agent call, Rust queries the graph for provenance on referenced files, recent session history, and architecture context, then injects it as a # VIBE OS Context section in the system prompt. Token-budgeted so graph context doesn't crowd out skills and repo summaries.
Repos, skills, and agents live in a single scrollable panel with collapsible sections and checkboxes. Everything you've ever added persists globally — check items to include them in a project, uncheck to remove from context without deleting. Repo adding supports three paths: native folder picker (multi-select), GitHub URL batch paste, and drag-and-drop from the OS file explorer.
When Claude spawns a subagent during a session, an inline card appears with a "Save Agent" button. Click it to edit the agent's name, description, system prompt, and tool permissions, then save it as a .md file in ~/.vibe-os/agents/ (with a copy to .claude/agents/ for native Claude Code discovery). Captured agents appear in the resource catalog and can be reused on any future project.
A single events table stores both actions and decisions with a kind field. Actions track file creates, test runs, repo toggles — the low-level breadcrumbs. Decisions add rationale, confidence scores, impact category, and reversibility. The vibe_record_decision MCP tool lets Claude record its own reasoning inline, which then becomes provenance context for future sessions. Everything is append-only and exportable to JSON or CSV.
On sidecar startup, VIBE OS scans PATH for common developer CLIs (git, gh, aws, docker, kubectl, node, npm, python, cargo, pip, terraform, gcloud). Detected tools are listed in the agent's system prompt so Claude knows what's available, and a count badge in the title bar shows the running tally with a tooltip listing every version. No configuration, no install flow — if it's on PATH, the agent can use it.
Each project can have multiple Claude sessions running simultaneously, each with independent conversation history via the SDK. Background sessions that need input trigger OS desktop notifications and surface through pulsing badges in the title bar and project cards. Switch sessions via the tab strip; sessions survive navigation and app restarts through the SDK's native session persistence.
A small pill toggle in the title bar switches between themes instantly via CSS variable overrides — zero component changes required. The preference persists to SQLite and loads before first render to avoid flash. Every color (backgrounds, borders, text, accents, status colors) is re-mapped for the light palette with adjusted contrast.
An interactive D3 force-directed graph of the knowledge base: nodes for repos, modules, functions, classes, decisions, sessions, and tests, with edges for imports, calls, inheritance, session provenance, and decision impact. Filter by node type, search by name, click-to-inspect for details. Auto-updates as the agent works.
VIBE OS has 205+ tests across the stack:
# Run all tests (TypeScript + Rust)
npm run test:all
# TypeScript only (Vitest) — 153 tests
npm run test
# Rust only (Cargo) — ~52 tests
npm run test:rust
# Watch mode
npm run test:watch| Area | Tests | What's Tested |
|---|---|---|
| TypeScript (Vitest) | 153 | Event parser, event normalization, agent slice, project slice, pipeline slice, layout slice, token slice, repo slice, component rendering (PhaseIndicator, GatePromptCard, InteractionCard), useAgentStream hook, resource catalog wiring |
| Rust SQLite | ~20 | Decisions, events, audit, sessions, workspaces, token budgets, pipeline persistence, migrations |
| Rust SurrealDB | ~17 | Node CRUD, edge creation, population pipeline, provenance queries, impact queries, session reports |
| Rust workflow | ~8 | Workflow runner integration, pipeline progression, gate management, backend adapters |
| Rust event stream | ~7 | Stream parsing, event classification, Codex JSONL parsing, serialization fixtures |
Tests use real captured agent output as fixtures, not assumed formats.
- React 18 + TypeScript 5.5 (strict mode)
- Vite 6 for dev server + production bundling
- Tailwind CSS 4 with CSS-variable-driven theme system
- Zustand 5 state management (20 composed slices)
- Monaco Editor for the escape-hatch code editor
- D3.js for the knowledge graph visualizer
- @dnd-kit for drag-and-drop pipeline builder
- Lucide icons
- Rust 1.89+
- Tauri 2 (
tauri-plugin-shell,tauri-plugin-dialog,tauri-plugin-notification,tauri-plugin-clipboard-manager) - rusqlite 0.32 (bundled) for operational data, WAL mode
- SurrealDB 3.0 (embedded,
kv-surrealkv) for the knowledge graph - Tokio async runtime
- Notify + notify-debouncer-mini for file watching
- Node.js 18+
@anthropic-ai/claude-agent-sdk— the agent loop- Zod for MCP tool schema validation
- esbuild for bundling
Zustand store with 20 slices, persisted to SQLite via a custom storage adapter:
| Slice | Responsibility |
|---|---|
projectSlice |
Project CRUD, active project, project card state, max 20 cap |
sessionSlice |
Active session lifecycle |
agentSlice |
Multi-session chat, agent events, outcome detection, attention routing |
agentDefinitionSlice |
Saved agent .md definitions from ~/.vibe-os/agents/ |
repoSlice |
Unified repo management — local + GitHub, CRUD, toggle, branch metadata |
skillSlice |
Skill discovery, toggle state, sync to ~/.claude/skills/ |
promptSlice |
System prompt, task context, composed prompt with token budget |
editorSlice |
Open files, active file, save with timestamp |
consoleSlice |
REPL output, command history |
eventSlice |
Unified events (actions + decisions), load, export |
decisionSlice |
Legacy decision state (kept for backward compat) |
auditSlice |
Legacy audit state (kept for backward compat) |
diffSlice |
Pending diffs, accept/reject flow |
previewSlice |
Preview URL, auto-refresh toggle |
workspaceSlice |
Workspace CRUD, file tree, CLAUDE.md watcher |
layoutSlice |
Drawer state, editor panel, quadrant tabs, pinned panes |
dashboardSlice |
Session goal |
pipelineSlice |
Pipeline builder state, phase CRUD, run tracking, gate advancement |
tokenSlice |
Token budgets per skill/repo/session with warnings |
themeSlice |
Light/dark theme state + persistence |
src-tauri/src/
lib.rs # Tauri builder, command registration, state init
db.rs # SQLite init with WAL mode, migrations via user_version
backends/
mod.rs # BackendAdapter trait, AgentProcesses registry
claude.rs # ClaudeAdapter — wraps Claude CLI with stream-json output
codex.rs # CodexAdapter — wraps Codex CLI with JSONL events
fake.rs # FakeAdapter — test double for workflow engine tests
commands/
agent_commands_v2.rs # SDK sidecar management, start/send/cancel agent
agent_commands.rs # Agent definition CRUD (.md file management)
claude_commands.rs # Legacy CLI wrapper (kept for fallback)
context_commands.rs # Prompt composition, skill discovery, skill sync
db_commands.rs # Session CRUD, settings, claude sessions
events_commands.rs # Unified events (actions + decisions)
pipeline_commands.rs # Pipeline CRUD, phase management
project_commands.rs # Project CRUD (SQLite-backed)
workflow_commands.rs # Start pipeline, advance gate, get run status
decision_commands.rs # Legacy decision ops
audit_commands.rs # Legacy audit ops
file_commands.rs # File read/write with audit logging
workspace_commands.rs # Workspace scaffolding, file tree, CLAUDE.md watcher
token_commands.rs # Token budget CRUD
graph_commands.rs # SurrealDB graph queries (provenance, impact, etc.)
architecture_commands.rs # Architecture analysis
script_commands.rs # Script tracking, skill generation
shell_commands.rs # Shell command spawning
workflow/
runner.rs # WorkflowRunner + WorkflowEngine — phase sequencing, gate management
context.rs # ArtifactStore — phase context handoff
graph/
schema.rs # SCHEMALESS tables + indexes
nodes.rs / edges.rs # CRUD primitives
queries.rs # Composite queries (provenance, impact, session report)
population.rs # Populate from events, decisions, actions
indexer.rs # Source file walker + function/class extraction
services/
sidecar.rs # Node sidecar process lifecycle
tool_handler.rs # Dispatches MCP tool requests to graph queries
event_stream.rs # Legacy CLI stream parser
105 Tauri commands total, registered in lib.rs's invoke_handler!.
agent-sidecar/
package.json # depends on @anthropic-ai/claude-agent-sdk + zod
build.mjs # esbuild bundler (bundles SDK inline, not external)
src/
main.ts # stdin/stdout JSON line protocol dispatcher
session.ts # SessionManager wrapping SDK query() lifecycle
tools.ts # 6 VIBE OS MCP tools with Zod schemas
types.ts # Shared protocol types (commands + events)
The sidecar is built with esbuild into a single self-contained dist/main.mjs (~800KB with the SDK bundled inline). Rust spawns it via node dist/main.mjs and communicates through stdin/stdout JSON lines. On startup it auto-detects the claude executable via where claude / which claude so the SDK knows where to execute.
SQLite (WAL mode) at ~/.vibe-os/vibe-os.db for operational data:
sessions— VIBE OS app sessionsclaude_sessions— per-project Claude session metadataevents— unified action + decision timeline (append-only)audit_log,decisions— legacy tables kept for backward compatprojects— SQLite-backed project CRUD (replaces settings-based storage)pipelines— workflow pipeline definitions per projectpipeline_phases— ordered phases within a pipeline (backend, framework, model, gate config)phase_runs— execution state for each phase in a pipeline runsettings— key/value persistence (theme, global repos, token budgets)token_budgets— per-scope budget enforcementworkspaces— workspace metadatarepos— unified repo registry (replaces old global/workspace split)
Schema migrations via PRAGMA user_version (currently v9).
SurrealDB (embedded, kv-surrealkv) at ~/.vibe-os/graph/ for the knowledge graph:
- Node tables:
repo,module,fn_def,class,ticket,skill,event,session,prompt,test - Edge tables:
belongs_to,imports,calls,inherits,defined_in,informed_by,modified,addresses,validated_by,led_to,triggered_by,implemented_by,occurred_in,produced,branched_from,session_uses_repo,project_contains_repo
Queried via SurrealQL with composite graph traversals.
| Shortcut | Action |
|---|---|
Ctrl+Shift+C |
Toggle editor panel (escape hatch) |
Ctrl+S / Cmd+S |
Save active file (audit logged) |
Ctrl+R / Cmd+R |
Focus Python console |
Enter (in chat) |
Send message to Claude |
Shift+Enter (in chat) |
New line |
| Role | Hex |
|---|---|
| Background | #08090d |
| Surface | #12141c |
| Border | #232738 |
| Text | #b8bdd4 |
| Accent | #5b7cfa |
| Green | #34d399 |
| Red | #f87171 |
| Orange | #fbbf24 |
| Cyan | #22d3ee |
| Role | Hex |
|---|---|
| Background | #f8f9fc |
| Surface | #ffffff |
| Border | #e2e5f0 |
| Text | #3a3f56 |
| Accent | #4a66d9 |
| Green | #16a34a |
| Red | #dc2626 |
| Orange | #d97706 |
| Cyan | #0ea5ba |
Typography: Instrument Sans (UI), JetBrains Mono (code), Space Mono (branding).
Theme switching is instant via [data-theme="light"] attribute on <html> — no component-level changes, every color resolves via CSS variables.
| Path | What's There |
|---|---|
~/.vibe-os/vibe-os.db |
SQLite operational database |
~/.vibe-os/graph/ |
SurrealDB knowledge graph |
~/.vibe-os/skills/ |
User skill markdown files |
~/.vibe-os/agents/ |
Saved agent definitions |
~/.vibe-os/repos/ |
Cloned GitHub repos (when no workspace active) |
~/vibe-workspaces/{name}/ |
Per-project workspaces |
~/.claude/skills/ |
Skill sync target for Claude Code discovery |
~/.claude/agents/ |
Agent sync target for Claude Code discovery |
MIT
VIBE OS is an independent open-source project and is not affiliated with, endorsed by, or sponsored by Anthropic or OpenAI. It builds on top of the publicly available @anthropic-ai/claude-agent-sdk and integrates with the Codex CLI. Users must have their own Claude Code and/or Codex installations and subscriptions. "Claude" and "Claude Code" are trademarks of Anthropic, PBC. "Codex" is a trademark of OpenAI.
Built with Tauri v2, React 18, and Rust. Multi-backend workflow orchestration powered by the Claude Agent SDK.