ULPI

Your Autonomous Engineering Fleet.

Dynamic hooks that govern any AI coding agent in real time. Centralized one-click MCP servers per project. Semantic code search, persistent memory, and a full visual dashboard — locally or in the cloud. Upload a sprint and watch your fleet execute dozens of tasks in parallel.

Install

npm install -g @ulpi/cli
ulpi init

Requires Node.js 20+. init detects your stack, generates rules with AI, installs hooks, starts the daemon, and registers your project. Use --no-ai for template-only generation, or --model=<id> to pick a specific model.

Commands

Core

| Command | What it does | |---------|-------------| | ulpi init | Detect stack, generate guards, install hooks | | ulpi start | Start ULPI daemon (API server + codemap watcher + portal) | | ulpi run | Start execution engine loop (--prd, --agent, --tasks) |

Management

| Command | What it does | |---------|-------------| | ulpi repos | Manage registered repos (list/add/remove/default) | | ulpi rules | List, add, enable, disable, or validate rules | | ulpi templates | Browse, apply, save, export, or import templates | | ulpi skills | List, add, get, or attach skills | | ulpi config | Manage settings and API keys | | ulpi prd | PRD management (create/convert/show) | | ulpi job | Manage execution jobs (create/list/status/cancel/logs) |

Monitoring

| Command | What it does | |---------|-------------| | ulpi status | Show current session state | | ulpi log | View activity log | | ulpi history | Shadow branch history (init/capture/list/show/enrich/backfill) | | ulpi tui | Terminal UI client (connects to daemon) | | ulpi portal | Start Portal dashboard in local mode | | ulpi doctor | System health check (agents, MCP, hooks, intelligence) |

Data & Intelligence

| Command | What it does | |---------|-------------| | ulpi codemap | Semantic code indexing (init/search/status/reindex/watch) | | ulpi memory | Agent memory (init/search/remember/status/export/import) | | ulpi mcp | MCP management (gateway/list/add/remove/enable/disable/catalog/setup) | | ulpi cloud | Connect to Cloud MCP Gateway (connect/status/disconnect) |

Agent Integrations

| Command | What it does | |---------|-------------| | ulpi kiro | Manage Kiro CLI integration (install/convert/uninstall/status) | | ulpi codex | Manage Codex CLI integration (install/convert/uninstall/status) |

Utility

| Command | What it does | |---------|-------------| | ulpi export | Export rules configuration | | ulpi import | Import rules configuration | | ulpi update | Check for and install updates | | ulpi ci | Run in CI/PR worker mode (used inside worker containers) | | ulpi auth | Manage AI agent credentials for CI workers | | ulpi uninstall | Remove hooks and ULPI from a project |

Run ulpi --help for the full list, or use -p <project> to target a specific registered project.

Five Pillars

Govern

Define what your AI agent can and cannot do. Four rule types — preconditions, permissions, postconditions, and pipelines — work together for layered enforcement. 28 bundled templates auto-selected for your detected stack. Auto-approve safe operations, block dangerous commands, enforce read-before-write. Session-aware — tracks reads, writes, tests, and lints across the entire session. Fail-open — if ULPI errors, your agent continues unblocked.

Understand

Your agent understands your entire codebase. CodeMap provides hybrid vector + BM25 semantic search with AST-aware chunking. DepGraph uses tree-sitter entity mapping across 35 languages to build dependency graphs with PageRank importance ranking, cycle detection, and coupling metrics. 18 MCP tools exposed directly to your agent. Stack detection with 10 detectors: runtime, language, framework, package manager, formatter, linter, test runner, ORM, git workflow, features.

Remember

Your agent learns from every session instead of starting fresh. ULPI captures session events, classifies them with an LLM into 8 memory types — decisions, patterns, bug root causes, preferences, constraints, context, lessons, and relationships — then stores them with vector embeddings for semantic search. Relevant memories are surfaced automatically at the start of each new session. Deduplication, importance-weighted ranking, and redaction of secrets.

Record

Complete audit trail of every AI action. Per-user shadow git branches (ulpi/history-<user>) store structured records without touching your working tree. Commit diffs, session analytics, metadata, full transcripts, and AI enrichment (summary, intent, challenges, learnings, recommendations). No database — everything lives in git and travels with your repo.

Orchestrate

From PRD to production. The execution engine (ulpi run) parses a PRD into structured tasks, builds a dependency graph, schedules parallel work across multiple agents, and auto-commits results. 6 agent adapters, 5 task trackers, configurable retries, branch management, and team delegation.

ulpi run --prd feature.md --agent claude --auto-commit
ulpi run --tracker jira --agent gemini --branch feat/new-feature
ulpi run --tasks tasks.json --agent claude --parallel

Supported Agents

| Agent | Hook Support | MCP Support | Execution Engine | |-------|-------------|-------------|-----------------| | Claude Code | Full (7 hooks) | Full (18 tools) | --agent claude | | Gemini CLI | Full (7 hooks) | Full (18 tools) | --agent gemini | | OpenCode | Full (7 hooks) | Full (18 tools) | --agent opencode | | Kiro CLI | Full (4 hooks) | Full (18 tools) | --agent kiro | | Codex | Prompt governance | Full (18 tools) | --agent codex | | Factory Droid | MCP only | Full (18 tools) | --agent factory-droid |

ulpi kiro install       # Install ULPI governance for Kiro CLI
ulpi codex install      # Install ULPI governance for Codex CLI
ulpi doctor             # Check which agents are installed and configured

MCP Integration

• 18 MCP tools — CodeMap (12 tools) and Memory (6 tools) exposed via stdio transport
• MCP gateway — multiplexing proxy that aggregates third-party MCP backends through a single connection
• MCP catalog — curated registry of MCP server definitions installable with one command
• Per-repo MCP — enable or disable specific MCP servers per repository
• Hot reload — automatic tool list updates when MCP configuration changes
• Crash recovery — automatic backend restart on failure

ulpi mcp catalog        # Browse available MCP servers
ulpi mcp add <server>   # Add an MCP server
ulpi mcp setup          # Auto-configure MCP connections
ulpi mcp gateway        # Start MCP gateway

Configuration

Rules live in .ulpi/guards.yml — plain YAML, auto-generated based on your stack:

preconditions:
  read-before-write:
    matcher: "Write|Edit"
    requires_read: true
    message: "Read the file before editing it."

permissions:
  auto-approve-tests:
    matcher: Bash
    command_pattern: "pnpm test"
    decision: allow

postconditions:
  run-tests-after-edit:
    matcher: "Write|Edit"
    file_pattern: "src/**/*.ts"
    command: "pnpm test"

pipelines:
  pre-commit-checks:
    matcher: Bash
    command_pattern: "git commit"
    steps:
      - name: build
        command: "pnpm -r build"
      - name: test
        command: "pnpm test"

Interfaces

• Portal — Next.js dashboard for rules, sessions, code search, memory, history, review, and execution monitoring (ulpi start or ulpi portal)
• Terminal UI — ink-based TUI client for live session monitoring (ulpi tui)
• REST API — modular HTTP server with WebSocket for live updates and SSE for event streaming
• macOS LaunchAgent — automatic background startup for daemon and codemap watcher

How It Works

ULPI uses hook protocols — lifecycle events that fire before and after every tool execution in your AI agent.

| Hook | When | What ULPI Does | |------|------|----------------| | SessionStart | Agent session begins | Detect stack, capture branch/HEAD, surface memories, import CodeMap index | | PreToolUse | Before any tool runs | Evaluate preconditions, block dangerous commands | | PostToolUse | After a tool completes | Track files/commands, run postconditions, capture history on new commits | | PermissionRequest | Tool needs approval | Auto-approve or deny based on rules, plan review on ExitPlanMode | | Notification | Event notification | Classify and route to desktop, webhook, terminal, or log channels | | Stop | Session stopping | Final checks (warn about missing tests/lint) | | SessionEnd | Session complete | Persist summary, capture commits to history, classify memories, export indexes |

If ULPI ever encounters an error, it fails open — your AI agent continues normally.

Embedding Providers

| Provider | Setup | Cost | Data | |----------|-------|------|------| | ULPI Cloud (recommended) | No setup, use ULPI_API_KEY | Free tier included | Sent to ULPI servers | | Ollama | Install Ollama locally | Free | Stays on your machine | | OpenAI | Use your OPENAI_API_KEY | Per-token pricing | Sent to OpenAI |

Configure via ulpi config set embedding.provider <ulpi|ollama|openai>.

Cloud

Upload a sprint with dozens of tasks — or import directly from Jira. ULPI Cloud spawns isolated Docker workers, each with a full AI agent, to execute them in parallel. GitHub webhooks trigger automated code review on PRs. Per-org quotas, member roles, API keys, and audit logs.

ulpi cloud connect      # Connect to ULPI Cloud
ulpi cloud status       # Check connection status

Requirements

• Node.js >= 20
• An AI coding agent: Claude Code, Gemini CLI, OpenCode, Kiro, Codex, or Factory Droid

License

MIT