# UAP Integration Guide

**Version:** 1.0.2  
**Last Updated:** 2026-03-17  
**Status:** ✅ Production Ready

---

## Executive Summary

This guide provides integration instructions for all supported platforms, including opencode (with oh-my-pi), ForgeCode, Claude Code, and VSCode.

---

## 1.1 opencode with UAP

**opencode** is the recommended platform for UAP, providing:

- Persistent sessions across restarts
- Plugin architecture for Pattern RAG
- Local LLM support (llama.cpp)
- Built-in tooling (file operations, bash, search)

### 1.1.1 Setup

```bash
# Install opencode
npm install -g opencode

# Configure local LLM (optional)
cat > ~/.opencode/config.json << 'EOF'
{
  "provider": {
    "llama.cpp": {
      "name": "llama-server (local)",
      "options": {
        "baseURL": "http://localhost:8080/v1",
        "apiKey": "sk-qwen35b"
      },
      "models": {
        "qwen35-a3b-iq4xs": {
          "name": "Qwen3.5 35B A3B (IQ4_XS)",
          "limit": {
            "context": 262144,
            "output": 16384
          }
        }
      }
    }
  },
  "model": "llama.cpp/qwen35-a3b-iq4xs"
}
EOF

# Initialize UAP in your project
cd your-project
uap init
```

### 1.1.2 Plugin Configuration

UAP plugins automatically load in opencode for:

- **Pattern RAG** - Context-aware pattern injection (~12K tokens saved)
- **Session hooks** - Pre-execution setup, memory preservation
- **Agent coordination** - Multi-agent workflows without conflicts

### 1.1.3 Usage

```bash
# Start opencode with UAP
opencode

# UAP features available:
# - Pattern RAG auto-injection
# - Memory persistence
# - Worktree isolation
# - Compliance enforcement
```

### 1.1.2 Oh-My-Pi Integration with UAP

**oh-my-pi** is a powerful AI coding agent that now has **explicit UAP integration** with deep UI elements, session dashboards, and best-in-class UAP capabilities.

#### 🎯 UAP-Enhanced Oh-My-Pi Features

Unlike basic opencode integration, the UAP-enhanced oh-my-pi provides:

| UAP Feature            | Integration                                                               |
| ---------------------- | ------------------------------------------------------------------------- |
| **Session Dashboard**  | `/uap-dashboard` - Real-time overview of tasks, agents, memory, worktrees |
| **4-Layer Memory**     | Auto-injection on session start, persistent across restarts               |
| **Worktree Isolation** | Enforced via hooks, automatic stale detection                             |
| **Task DAG Tracking**  | `uap task` commands with status, creation, updates                        |
| **Agent Coordination** | Multi-agent heartbeats, overlap detection, conflict prevention            |
| **Pattern RAG**        | Auto-indexed patterns from your work (~12K token savings)                 |
| **Memory Compaction**  | Smart cleanup preserving high-importance lessons                          |
| **Policy Enforcement** | Pre-commit validation, worktree isolation checks                          |
| **Telemetry**          | Tool execution logging for analytics and optimization                     |

#### Installation

```bash
# Install oh-my-pi via Bun (recommended)
bun install -g @oh-my-pi/pi-coding-agent

# Install UAP integration for oh-my-pi
cd your-project
uap-omp install

# Verify installation
omp --version
```

#### Quick Start

```bash
# Start oh-my-pi with UAP context (hooks auto-inject)
omp

# View UAP dashboard
uap-omp dashboard

# Or use /uap-dashboard inside oh-my-pi
/uap-dashboard
```

#### UAP Dashboard UI

The UAP dashboard provides a comprehensive view of your agent session:

```
╔══════════════════════════════════════════════════════════╗
║         UAP Dashboard for Oh-My-Pi                       ║
╠══════════════════════════════════════════════════════════╣
║  🧠 Memory Status                                         ║
║    Recent: 47 lessons stored                              ║
╠══════════════════════════════════════════════════════════╣
║  📋 Task Status                                           ║
║    Active tasks: 3                                        ║
║    Pending:                                               ║
║    • Fix authentication bug                               ║
║    • Add unit tests for API                               ║
║    In Progress:                                           ║
║    • Refactor payment module                              ║
╠══════════════════════════════════════════════════════════╣
║  🌿 Worktrees                                             ║
║    Active: 2 | Stale: 1 | Total: 3                       ║
╠══════════════════════════════════════════════════════════╣
║  🤖 Agents                                                ║
║    Total: 4 | Running: 2                                  ║
╠══════════════════════════════════════════════════════════╣
║  📚 Pattern Library                                       ║
║    Patterns indexed: 156                                  ║
╠══════════════════════════════════════════════════════════╣
║  📁 Current Context                                       ║
║    Branch: feature/auth-fix                               ║
║    Uncommitted changes: 12                                ║
╚══════════════════════════════════════════════════════════╝
```

#### UAP CLI Commands for oh-my-pi

| Command                           | Description                        |
| --------------------------------- | ---------------------------------- |
| `uap-omp dashboard`               | Open UAP dashboard UI              |
| `uap memory status`               | Check memory health and statistics |
| `uap memory query <term>`         | Search memory for relevant lessons |
| `uap memory store <content>`      | Manually store a lesson            |
| `uap task list`                   | List all tasks and their status    |
| `uap task create --title <title>` | Create a new task                  |
| `uap worktree list`               | Show active worktrees              |
| `uap worktree create <slug>`      | Create isolated worktree           |
| `uap patterns query <term>`       | Search pattern library             |
| `uap compact`                     | Compact and optimize memory        |

#### Memory Injection

UAP automatically injects relevant memory context at session start:

```
[UAP Memory Context]
[Importance 9]
Category: authentication
Content: Always validate JWT tokens on every request, use bcrypt for password hashing
---
[Importance 7]
Category: testing
Content: Write unit tests before implementing new features
---

Use this context to inform your decisions.
```

#### Worktree Enforcement

UAP enforces worktree isolation automatically:

```
[UAP-Enforce] You're about to modify files in the main branch (main).

Per UAP compliance protocol, all changes should be made in isolated worktrees.

Consider creating a worktree first:
uap worktree create <slug>
```

#### Hooks System

UAP installs hooks that automatically:

- **Pre-session**: Inject memory, check task readiness, detect stale worktrees
- **Post-session**: Save lessons, update worktree status, cleanup

Hooks are located at `~/.uap/omp/hooks/` and integrate with oh-my-pi's hook system.

#### Feature Parity Comparison

| Capability               | Basic opencode + oh-my-pi | UAP-Enhanced oh-my-pi                |
| ------------------------ | ------------------------- | ------------------------------------ |
| Core Tools               | ✅ Full parity            | ✅ Full parity                       |
| Memory Persistence       | ❌ None                   | ✅ 4-layer system                    |
| Worktree Isolation       | ⚠️ Manual                 | ✅ Auto-enforced                     |
| Task Tracking            | ⚠️ Manual                 | ✅ DAG with status                   |
| Multi-agent Coordination | ❌ None                   | ✅ Heartbeats & overlap detection    |
| Pattern RAG              | ⚠️ Manual                 | ✅ Auto-indexed (~12K token savings) |
| Session Dashboard        | ❌ None                   | ✅ Real-time UI                      |
| Policy Enforcement       | ❌ None                   | ✅ Pre-commit validation             |
| Telemetry                | ❌ None                   | ✅ Tool execution logging            |

#### Advanced Configuration

**Enable UAP features in oh-my-pi:**

Add to `~/.omp/agent/config.yml`:

```yaml
# Enable UAP memory injection
uap:
  enabled: true
  memoryInjection: true
  patternRAG: true
  worktreeIsolation: true

# Dashboard settings
uapDashboard:
  autoOpen: false
  views: ['overview', 'tasks', 'agents', 'memory']
```

**Custom hook behavior:**

Edit `~/.uap/omp/hooks/pre/session-start.sh` to customize memory injection:

```bash
#!/usr/bin/env bash
# Custom pre-session hook
export UAP_INJECT_LESSONS=5  # Only inject top 5 lessons
export UAP_MIN_IMPORTANCE=6   # Only inject importance >= 6
```

---

## 1.2 ForgeCode Integration

### 1.2.1 Overview

**ForgeCode** is the world's #1 coding agent (TermBench 2.0, 78.4% accuracy), providing:

- ZSH-native invocation (type `:` to invoke)
- Multi-agent modes (FORGE, MUSE, SAGE)
- Model flexibility (mix models mid-session)
- Context engine with RAG-powered memory

### 1.2.2 Setup

```bash
# Install UAP in your project
cd your-project
uap init

# Install hooks for ForgeCode integration
uap hooks install forgecode
```

This creates:

- `.forge/hooks/session-start.sh` - Injects recent memory before `:` command
- `.forge/forgecode.plugin.sh` - ZSH plugin with environment injection
- `.forge/settings.local.json` - UAP integration configuration
- Updates `~/.zshrc` to source the plugin automatically

### 2.3 Usage

```bash
# In your ZSH session, type : to invoke ForgeCode
cd ~/projects/my-app && :
: fix login bug in auth middleware
```

UAP will:

1. Load recent memory context from `agents/data/memory/short_term.db`
2. Check for stale worktrees and open loops
3. Inject as environment variables (`UAP_CONTEXT`, `UAP_OPEN_LOOPS`)
4. ForgeCode reads these for enhanced context-aware responses
5. On completion, saves lessons back to UAP memory

### 2.4 Verification

```bash
# Check hook status for all platforms including forgecode
uap hooks status -t forgecode
```

---

## 3. Claude Code Integration

### 3.1 Overview

**Claude Code** is Anthropic's desktop app with full UAP support:

- Full UAP integration
- CLAUDE.md for context
- Persistent memory across sessions
- Built-in tooling

### 3.2 Setup

```bash
# Install UAP in your project
cd your-project
uap init

# CLAUDE.md automatically generated with:
# - Project structure
# - UAP commands
# - Pattern references
# - Memory system docs
```

### 3.3 Usage

```bash
# Open project in Claude Code
claude-code

# UAP features available:
# - CLAUDE.md context injection
# - Pattern Router auto-selection
# - Memory persistence
# - Worktree isolation
```

---

## 4. VSCode Integration

### 4.1 Overview

**VSCode** with Claude Code extension provides:

- IDE integration
- Full UAP support
- File system access
- Terminal integration

### 4.2 Setup

```bash
# Install UAP in your project
cd your-project
uap init

# Install VSCode extensions:
# - Claude Code extension
# - UAP syntax highlighting (optional)
```

### 4.3 Usage

```bash
# Open project in VSCode
code your-project

# Use Claude Code extension:
# - UAP features available
# - File operations
# - Terminal commands
# - Memory queries
```

---

## 5. claude.ai Integration

### 5.1 Overview

**claude.ai** is Anthropic's web version with limited UAP support:

- Web-based interface
- Limited tooling
- No persistent memory
- Reduced functionality

### 5.2 Setup

```bash
# Initialize UAP (for reference)
cd your-project
uap init

# Note: Web version has limited UAP support
# Consider using Claude Code or opencode for full features
```

### 5.3 Limitations

- ❌ No persistent memory
- ❌ No worktree isolation
- ❌ No hook enforcement
- ⚠️ Limited tooling
- ⚠️ No Pattern RAG

---

## 6. Integration Comparison

Every platform listed above ships as a stateless code editor. UAP closes the gap. Here is what it adds and why:

- **4-layer persistent memory** -- agents retain lessons across sessions instead of starting from zero
- **Write gate** -- 5-criteria quality filter prevents memory pollution
- **22 battle-tested patterns** -- Terminal-Bench 2.0 workflows eliminate 37% of common agent failures
- **Pattern RAG** -- on-demand retrieval saves ~12K tokens per session
- **Worktree isolation** -- parallel agents never corrupt each other's git state
- **Multi-agent coordination** -- heartbeats, overlap detection, and conflict risk let multiple agents share a repo safely
- **Deploy batching** -- squashed commits and serialized pushes prevent deploy storms
- **Policy enforcement** -- audit-trailed rules ensure agents follow project standards
- **Task DAG** -- dependency-aware tracking with cycle detection and JSONL sync
- **MCP Router** -- 98% system prompt token reduction (from ~12K to ~200)
- **RTK** -- 60-90% output token savings via Rust-based compression
- **12-gate compliance** -- automated protocol verification catches drift before it ships

> Full 15-harness matrix with per-harness integration details: **[HARNESS-MATRIX.md](../reference/HARNESS-MATRIX.md)**

### Baseline: What Platforms Provide Natively

| Feature                      |  opencode  | ForgeCode | Claude Code | VSCode  |    Cursor    | claude.ai |
| ---------------------------- | :--------: | :-------: | :---------: | :-----: | :----------: | :-------: |
| File system + terminal       |    Yes     |    Yes    |     Yes     |   Yes   |     Yes      |    --     |
| Context file                 |     --     |    --     |  CLAUDE.md  |   --    | .cursorrules |    --     |
| Native hooks                 | Plugin API | ZSH hooks |     Yes     |   --    |  hooks.json  |    --     |
| MCP support                  |   Config   |    --     |   Native    | Via ext |    Native    |    --     |
| Persistent sessions          |    Yes     |  ZSH env  |     Yes     | Limited |   Limited    |    --     |
| Local LLM support            |   Native   |    Yes    |     --      | Via ext |     Yes      |    --     |
| **Persistent memory**        |     --     |    --     |     --      |   --    |      --      |    --     |
| **Pattern library**          |     --     |    --     |     --      |   --    |      --      |    --     |
| **Multi-agent coordination** |     --     |    --     |     --      |   --    |      --      |    --     |
| **Policy enforcement**       |     --     |    --     |     --      |   --    |      --      |    --     |

The bottom four rows are empty across every column. No platform provides them. This is the gap UAP fills.

### With UAP: What Every Platform Gains

| Capability               | Why It Matters                        | opencode | ForgeCode | Claude Code | VSCode  | Cursor  | claude.ai |
| ------------------------ | ------------------------------------- | :------: | :-------: | :---------: | :-----: | :-----: | :-------: |
| 4-layer memory (L1-L4)   | Agents remember across sessions       |   Yes    |    Yes    |     Yes     |   Yes   |   Yes   |    --     |
| Write gate + tiering     | Only high-value knowledge stored      |   Yes    |    Yes    |     Yes     |   Yes   |   Yes   |    --     |
| 22 patterns + RAG        | Proven workflows, ~12K token savings  |   Yes    |    Yes    |     Yes     |   Yes   |   Yes   |    --     |
| Worktree isolation       | Parallel agents, zero conflicts       |   Yes    |    Yes    |     Yes     |   Yes   |   Yes   |    --     |
| Multi-agent coordination | Heartbeats, overlap detection, claims |   Yes    |    Yes    |     Yes     |   Yes   |   Yes   |    --     |
| Deploy batching          | No push races, squashed commits       |   Yes    |    Yes    |     Yes     |   Yes   |   Yes   |    --     |
| Policy engine            | Audit-trailed rule enforcement        |   Yes    |    Yes    |     Yes     |   Yes   |   Yes   |    --     |
| Task DAG                 | Dependency-aware work tracking        |   Yes    |    Yes    |     Yes     |   Yes   |   Yes   |    --     |
| MCP Router               | 98% system prompt token reduction     |   Yes    |    Yes    |     Yes     |   Yes   |   Yes   |    --     |
| RTK compression          | 60-90% output token savings           |   Yes    |    Yes    |     Yes     |   Yes   |   Yes   |    --     |
| 12-gate compliance       | Automated protocol verification       |   Yes    |    Yes    |     Yes     |   Yes   |   Yes   |    --     |
| 20+ CLI commands         | Full management + dashboard           |   Yes    |    Yes    |     Yes     |   Yes   |   Yes   |    --     |
| **Recommended**          |                                       |   Yes    |    Yes    |     Yes     | Partial | Partial |    --     |

### Integration Tiers

| Tier                   | Harnesses                                    | What You Get                                                            |
| ---------------------- | -------------------------------------------- | ----------------------------------------------------------------------- |
| **T1 -- First-Class**  | Claude Code, Factory.AI, OpenCode, ForgeCode | Native hooks, dedicated config dir, `uap sync`, context file generation |
| **T2 -- IDE-Based**    | Cursor, VSCode, Cline                        | Platform-specific hooks, MCP config paths                               |
| **T3 -- CLI/Terminal** | Windsurf, Codex CLI, Aider, Zed AI, Continue | Mapped to T1/T2 via CLAUDE.md or .cursorrules                           |
| **T4 -- Additional**   | GitHub Copilot, JetBrains AI, SWE-agent      | Piggybacks on T2 infrastructure                                         |

All tiers receive identical UAP features. The difference is integration depth, not capability.

---

## 7. Platform-Specific Features

### 7.1 opencode

**Unique Features:**

- Plugin architecture
- Persistent sessions
- Local LLM optimization
- Built-in tooling

**Configuration:**

```json
{
  "provider": {
    "llama.cpp": {
      "name": "llama-server (local)",
      "options": {
        "baseURL": "http://localhost:8080/v1"
      }
    }
  }
}
```

### 7.2 ForgeCode

**Unique Features:**

- ZSH-native (`:` command)
- Multi-agent modes
- Environment variable injection
- Oh My Zsh integration

**Configuration:**

```json
{
  "forge": {
    "enabled": true,
    "uamIntegration": true,
    "memoryInjection": true
  }
}
```

### 7.3 Claude Code

**Unique Features:**

- Desktop app
- CLAUDE.md context
- Full tooling
- Persistent sessions

**Configuration:**

```json
{
  "claudeCode": {
    "enabled": true,
    "claudeMd": true,
    "fullUAP": true
  }
}
```

---

## 8. Quick Start Examples

### 8.1 opencode (Recommended)

```bash
# Install and configure
npm install -g opencode
uap init
opencode

# UAP features available immediately
```

### 8.2 ForgeCode

```bash
# Install and configure
uap init
uap hooks install forgecode

# Use in ZSH
cd project && :
: fix bug
```

### 8.3 Claude Code

```bash
# Install and configure
uap init

# Open in Claude Code
claude-code
```

---

## 9. Troubleshooting

### 9.1 Common Issues

**Issue:** "Memory not persisting"  
**Solution:** Check `agents/data/memory/short_term.db` exists

**Issue:** "Pattern RAG not working"  
**Solution:** Run `python agents/scripts/index_patterns_to_qdrant.py`

**Issue:** "ForgeCode : command not found"  
**Solution:** Restart ZSH or source `~/.zshrc`

**Issue:** "opencode plugin not loading"  
**Solution:** Check `opencode.json` configuration

### 9.2 Getting Help

- Documentation: `docs/` directory
- Issues: GitHub repository issues
- Community: Join UAP Discord

---

**Last Updated:** 2026-03-17  
**Version:** 1.0.2  
**Status:** ✅ Production Ready
