vuhlp-code

Created: December 16, 2025

Last commit: January 24, 2026

TypeScript82.6%

CSS16.9%

JavaScript0.5%

Autonomous AI agentsAgent orchestrationGraph-based workflowsLocal-first privacy / local-first storage (runs, logs, artifacts stored locally)Observability (prompts, tool calls, outputs, artifacts logged)Loop safety / stall detectionMobile companion appsProvider adapters / provider integrationMulti-turn streaming for agent CLIsWS / WebSocketHTTP / httpJSONL / JSON Lines / NDJSONCLI / command-line interfaceCodex / OpenAI CodexClaude Code / ClaudeGemini CLI / GeminiOpenAIAnthropicGooglepnpm v9 / pnpmnode / Node.js (Node 25+)express.js / Expressreact.js / ReactExpo CLI / ExpoRN / React Nativestream-json (npm)pnpm (package manager; pnpm install, pnpm dev, pnpm --filter)package.jsongit submoduleProvider CLIs: Claude Code, Codex, Gemini (Gemini CLI)stream-json (npm streaming JSON library)stdin/stdout streamingExpress + WS runtime (daemon)Daemon: HTTP server and WebSocket serverdocs/ (project documentation/spec)

README.md

Vuhlp Agent Platform

Local-first, graph-based orchestration for autonomous AI agents.

Vuhlp is a monorepo platform designed to orchestrate multiple coding agents (OpenAI, Anthropic, Google, etc.) in user-defined workflows. Workflows are graphs: nodes are autonomous agents and edges are explicit handoffs.

Core Philosophy

Graph-First: Workflows are directed graphs. Nodes and edges define data flow.
Local-First Privacy: Runs, logs, and artifacts live on your machine.
Agent Autonomy: Nodes can work independently; an orchestrator node can coordinate.
Full Observability: Prompts, tool calls, outputs, and artifacts are logged.
Loop Safety: Stall detection pauses runs instead of hard-capping them.

Quickstart

Prerequisites

Node.js: 25+
pnpm: 9.x (see package.json)
Provider CLIs (optional but recommended): Claude Code, Codex, Gemini

Install

pnpm install

Run the daemon

pnpm dev

Daemon defaults:

HTTP: http://localhost:4000
WebSocket: ws://localhost:4000/ws

Run the UI (dev)

pnpm --filter @vuhlp/ui dev

Open the UI at http://localhost:5173

Project Structure

packages/daemon: Runtime (Express + WS) that manages runs, nodes, and events.
packages/ui: React UI (graph editor + inspector).
packages/contracts: Shared TypeScript types and JSON schemas.
packages/shared: Shared utilities (API client, logging, UI helpers).
packages/providers: Provider adapters and local CLI forks.
packages/mobile: Mobile companion app (Expo / React Native).

CLI Patches for Orchestration

To support true multi-turn streaming, Vuhlp uses local forks:

Codex: packages/providers/codex (submodule) with codex vuhlp JSONL stdin/stdout.
Gemini: packages/providers/gemini-cli (submodule) with stream-json stdin.

See docs/09-cli-patches.md for details and maintenance notes.

Documentation

The docs/ folder is the canonical spec for the current implementation. Start here: