This file is the authoritative reference for AI agents working in this repository. It supersedes all older planning documents.

All operations in this repository use agentic pair programming.

Every task is executed by two roles working in tandem:

The driver executes. It reads files, writes code, runs commands, and produces output. It operates within the scope defined by the current task and does not take unilateral decisions on ambiguous requirements.

• Performs one logical step at a time, then yields to the navigator before proceeding.
• Does not take destructive or irreversible actions (force push, volume removal, data deletion, CI changes) without navigator sign-off.
• Flags blockers, conflicts, or unexpected state immediately rather than working around them silently.

The navigator reviews. It runs ahead of the driver — auditing the plan, checking assumptions, spotting edge cases, and verifying output after each step. It does not write code directly but directs the driver's next move.

• Reads the PRD and surfaces ambiguities or risks before the driver starts.
• After each driver step, verifies correctness and either approves the next step or redirects.
• Produces the final audit/summary before any task is marked done.

1. Navigator reads the ticket/PRD and briefs the driver on scope, risks, and acceptance criteria.
2. Driver executes step-by-step; navigator reviews each output.
3. On completion, navigator audits the full diff and confirms all acceptance criteria are met.

When in doubt: navigator asks, driver waits.

In addition to the standard driver-navigator model, OCcode supports two specialized pair programming configurations:

Both the driver and navigator roles are filled by sub-agents. This configuration is used for:

• Tasks requiring specialized expertise from multiple sub-agents
• Complex operations where both agents benefit from sub-agent capabilities
• Training scenarios where sub-agents learn from each other

In 3PS:

• Driver sub-agent handles execution tasks
• Navigator sub-agent provides review and guidance
• Both operate with sub-agent permissions and capabilities

Both the driver and navigator roles are filled by main agents. This configuration is used for:

• High-stakes operations requiring main-agent authority
• Tasks needing full access to repository privileges
• Critical path development requiring main-agent decision making

In 3PM:

• Driver main-agent has full execution authority
• Navigator main-agent provides oversight and approval
• Both operate with main-agent permissions

The standard agent operating protocol applies to both 3PS and 3PM configurations, with the distinction being the agent type filling each role rather than changing the fundamental collaboration pattern.

OCcode is a branded IDE built on the Void editor fork (which is itself a fork of VS Code). It ships with the OpenClaw VS Code extension pre-bundled.

The old apps/wrapper (Electron bootstrapper that downloaded VSCodium) has been retired. The Void editor fork is now the main platform.

All agent work is organized via tickets in .tickets/. See .tickets/AGENTS.md for:

• Ticket structure and naming conventions
• Task workflow and subtask specification
• Commit process and verification

Key scripts:

# Find next ticket with pending work
bash .tickets/scripts/find_next_ticket.sh

# Verify ticket statuses
bash .tickets/scripts/verify_tickets.sh

occ/
├── apps/
│   ├── editor/           # Void editor fork — main IDE platform
│   └── web/              # Next.js marketing site
├── packages/
│   └── control-center/   # Shared React UI components
├── watch-editor.sh       # Dev: compile editor (macOS/Linux)
├── watch-editor.bat      # Dev: compile editor (Windows)
├── launch-editor.sh      # Dev: launch editor (macOS/Linux)
├── launch-editor.bat     # Dev: launch editor (Windows)
└── watch-react.sh        # Dev: watch Void React UI components (macOS/Linux)

Root package.json workspaces: apps/web, packages/control-center

apps/editor is intentionally excluded from workspaces — see the npm section below.

Priority: When Docker or an OCI-compatible container runtime is available on the host, use the Docker Compose development workflow as the primary method for implementation, testing, and verification. This is the default approach unless explicitly constrained.

• No local rebuilds required — the watch process runs inside the container, picking up source changes automatically
• Consistent environment — Node 20.18.2, all dependencies, and build tools are pre-configured
• Instant verification — UI and functionality changes are visible through the running editor at http://localhost:9888
• Playwright testing — browser automation tests (including MCP) run against the live editor; browser setup requires checking for existing connections and user approval

The editor runs in the occ-editor-dev container (defined in docker-compose.yml):

services:
  editor:
    build:
      context: .
      dockerfile: Dockerfile
    network_mode: host
    volumes:
      - .:/workspace
      - /var/run/docker.sock:/var/run/docker.sock

The workspace is mounted as a volume, so source changes on the host are immediately visible inside the container.

# 1. Start the dev environment (first time builds the image)
docker compose up -d

# 2. Verify the editor is running
curl -s http://localhost:9888/ | head -5

# 3. Edit source files on the host — changes are picked up by the watch process
#    (no rebuild needed for TypeScript/extension changes)

# 4. For extension TypeScript changes, recompile inside the container:
docker exec occ-editor-dev bash -c "cd /workspace/apps/editor/extensions/openclaw && npx tsc -p ./"

# 5. For Void React changes, rebuild React bundles:
docker exec occ-editor-dev bash -c "cd /workspace && npm run editor:build-react"

# 6. For full editor rebuild (rarely needed — watch handles most cases):
docker exec occ-editor-dev bash -c "cd /workspace/apps/editor && node --max-old-space-size=8192 ./node_modules/gulp/bin/gulp.js compile"

# 7. Verify changes via Playwright or browser automation (MCP):
npx playwright test tests/e2e/ --reporter=list
# or use MCP tools to interact with http://localhost:9888

• Editor container running: docker compose up -d
• Editor accessible at http://localhost:9888

# Start the dev environment (first time builds the image)
docker compose up -d

# Run all E2E tests with standard Playwright (headless)
npm run test:e2e

# Run all E2E tests with Playwright UI (headed, interactive)
npm run test:e2e:ui

# Run tests with an existing Chrome instance via CDP
npm run test:e2e:cdp

⚠️ IMPORTANT: CDP tests must run serially (1 worker)

The E2E fixture shares a single browser context across tests via CDP. This is incompatible with parallel test execution.

# ✓ CORRECT — uses 1 worker by default
npm run test:e2e tests/e2e/onboarding-auth.spec.ts

# ✓ CORRECT — explicitly serial
npm run test:e2e -- --workers=1 tests/e2e/onboarding-auth.spec.ts

# ✗ WRONG — parallel workers interfere with shared context
npm run test:e2e -- --workers=4 tests/e2e/onboarding-auth.spec.ts

When using --workers=4 with CDP tests, you will see:

• Tests run in 4 parallel workers
• Multiple workers open pages simultaneously on the same context
• Network and page state conflicts occur
• Tests timeout waiting for .monaco-workbench or fail with page content errors
• Solution: Always use --workers=1 for CDP E2E tests

Filter tests by file or pattern:

# Run a specific test file
npx playwright test tests/e2e/docker-to-ide-flow.spec.ts

# Run tests matching a pattern
npx playwright test --grep "home panel"

# Run tests matching a pattern (inverted)
npx playwright test --grep-invert "slow"

# Run a specific test by name
npx playwright test -t "should open home panel"

Test Result Interpretation & Next Actions

After running tests, check ./test-results/ for detailed failure diagnostics:

Investigating Failed Tests:

1. Screenshots: test-results/*test-failed-*.png show what the page looked like at failure time
2. Trace files: test-results/trace.zip contains Playwright trace (viewable at https://trace.playwright.dev)
3. Error context: test-results/*error-context.md shows the page's a11y tree snapshot at failure
4. Test output: Re-run failing test with -t "test name" to isolate and debug

# Run a single test for debugging
npx playwright test -t "home panel shows onboarding steps"

# Inspect trace in Playwright Inspector
npx playwright show-trace test-results/trace.zip

Webview Panel Access:

The editor's webview panels are accessible via iframe chains:

const inner = page
  .frameLocator('iframe.webview').first()
  .frameLocator('iframe#active-frame');

All test files use one import that never changes:

import { test, expect, type Page, type FrameLocator, withCDP } from './fixtures';

fixtures.ts selects mode based on environment variables:

Test Results Output:

Test results, screenshots, and videos are saved to ./test-results/. This directory is configured in playwright.config.ts:

outputDir: './test-results',

After test runs, check this directory for:

• test-results/*.png — screenshots from failed tests
• test-results/*.webm — video recordings (on failure)
• test-results/trace.zip — Playwright trace files for debugging

Playwright can connect to an externally-launched Chrome instance via CDP.

Test for existing Chrome CDP connection first:

# Check if Chrome is already running with remote debugging enabled
for candidate in \
  "/root/.config/google-chrome-beta/DevToolsActivePort" \
  "/root/.config/google-chrome/DevToolsActivePort" \
  "/home/linuxdev/.config/google-chrome-beta/DevToolsActivePort" \
  "/home/linuxdev/.config/google-chrome/DevToolsActivePort"; do
  if [ -f "$candidate" ]; then
    echo "✓ Chrome CDP endpoint found at $candidate"
    exit 0
  fi
done

echo "✗ No Chrome CDP connection found"

One-time wrapper setup (if user approves):

sudo tee /usr/local/bin/chrome-devtools-mcp-wrapper > /dev/null << 'EOF'
#!/bin/bash
ACTIVE_PORT_FILE=""
for candidate in \
  "/root/.config/google-chrome-beta/DevToolsActivePort" \
  "/root/.config/google-chrome/DevToolsActivePort" \
  "/home/linuxdev/.config/google-chrome-beta/DevToolsActivePort" \
  "/home/linuxdev/.config/google-chrome/DevToolsActivePort"; do
  if [ -f "$candidate" ]; then
    ACTIVE_PORT_FILE="$candidate"
    break
  fi
done

if [ -z "$ACTIVE_PORT_FILE" ]; then
  exec npx chrome-devtools-mcp@latest "$@"
fi

CDP_PORT=$(sed -n '1p' "$ACTIVE_PORT_FILE")
CDP_PATH=$(sed -n '2p' "$ACTIVE_PORT_FILE")
WS_ENDPOINT="ws://127.0.0.1:${CDP_PORT}${CDP_PATH}"

exec npx chrome-devtools-mcp@latest --wsEndpoint "$WS_ENDPOINT" "$@"
EOF
sudo chmod +x /usr/local/bin/chrome-devtools-mcp-wrapper

⚠️ Chrome 136+: You must use --user-data-dir with a custom profile for CDP to work. ⚠️ Port 9222 conflict: If using the noVNC container, stop it before Chrome debugging: docker kill playwright-novnc

Only start the noVNC container when the user explicitly requests headed browser testing or MCP automation.

# Start only if user requests: "I want to watch the browser tests run"
docker run -d --name playwright-novnc \
  --network host \
  -e SCREEN_WIDTH=1920 \
  -e SCREEN_HEIGHT=1080 \
  -e MCP_BROWSER=chromium \
  ghcr.io/xtr-dev/mcp-playwright-novnc

sleep 5

MCP servers available:

1. playwright-novnc — via noVNC container:

{
  "command": "docker",
  "args": ["run","--rm","-i","--network=host",
           "ghcr.io/xtr-dev/mcp-playwright-novnc","mcp-proxy","http://localhost:3080/sse"]
}

2. chrome-devtools — direct Chrome CDP:

{
  "command": "npx",
  "args": ["chrome-devtools-mcp@latest", "--autoConnect", "--channel", "beta"]
}

Available MCP tools: browser_navigate, browser_snapshot, browser_click, browser_fill_form, browser_take_screenshot, browser_list_pages

Access noVNC interface: http://localhost:6080/vnc.html

Clean up when done:

docker stop playwright-novnc
docker rm playwright-novnc

# View container logs
docker logs occ-editor-dev --tail 50

# Execute commands inside the container
docker exec occ-editor-dev bash

# Restart the container (picks up docker-compose.yml changes)
docker compose up -d --force-recreate editor

# Stop without removing
docker compose stop

# Full cleanup (removes containers and networks)
docker compose down

The OpenClaw gateway services (postgres, redis, gateway) are managed via two docker-compose files:

Development (with local overrides for faster iteration):

# Start gateway services with dev overrides
docker compose \
  -f docker/docker-compose.openclaw.yml \
  -f docker/docker-compose.openclaw.override.yml \
  up -d

# Or with env vars
OPENCLAW_DATA_DIR=./.openclaw docker compose \
  -f docker/docker-compose.openclaw.yml \
  -f docker/docker-compose.openclaw.override.yml \
  up -d

# Check service health
docker compose -f docker/docker-compose.openclaw.yml -f docker/docker-compose.openclaw.override.yml ps

# View gateway logs
docker compose -f docker/docker-compose.openclaw.yml -f docker/docker-compose.openclaw.override.yml logs -f occ-gateway

Production (base config only — used in CI/builds):

# Start gateway services (production-like)
docker compose -f docker/docker-compose.openclaw.yml up -d

# Check service health
docker compose -f docker/docker-compose.openclaw.yml ps

# View gateway logs
docker compose -f docker/docker-compose.openclaw.yml logs -f occ-gateway

# Stop and clean up
docker compose -f docker/docker-compose.openclaw.yml down

Convenience alias (for development):

alias docker-dev="docker compose -f docker/docker-compose.openclaw.yml -f docker/docker-compose.openclaw.override.yml"
docker-dev up -d
docker-dev logs -f occ-gateway
docker-dev ps

The gateway is accessible at http://127.0.0.1:${GATEWAY_PORT:-18789}. Postgres and Redis run on the internal Docker network only (no host port exposure).

See DOCKER.md for detailed OpenClaw setup, environment variables, and troubleshooting.

A fork of the Void editor (vscode code-oss-dev v1.99.3). Already branded as OCcode:

• product.json → applicationName: occode, dataFolderName: .occode-editor

Exact version required: 20.18.2

Enforced by apps/editor/build/npm/preinstall.js. Will hard-fail npm install on any other version. The required version is pinned in apps/editor/.nvmrc.

nvm install 20.18.2   # first time only
cd apps/editor
nvm use               # reads .nvmrc automatically
npm install

When apps/editor is in the root workspaces array, npm hoists its dependencies (including gulp) to the root node_modules/. The editor's internal scripts reference ./node_modules/gulp/bin/gulp.js as a local path — hoisting breaks this, causing Error: Cannot find module.

Root package.json scripts use npm --prefix apps/editor run <script> instead of npm run --workspace=apps/editor <script> to delegate without triggering hoisting.

Always install inside the editor directory directly:

cd apps/editor && nvm use && npm install

Running npm install from the repo root will not install editor dependencies.

If Docker is not available, use the traditional local development workflow:

The Void AI UI (sidebar, settings, Ctrl+K modal etc.) is a separate React build pipeline. The compiled bundles must exist at apps/editor/src/vs/workbench/contrib/void/browser/react/out/ before the main TypeScript compilation runs. If they are missing, the main build emits ~9 "Cannot find module" errors for the React bundle paths.

# From repo root:
npm run editor:build-react

# Or directly:
cd apps/editor && npm run buildreact

Only re-run when editing files inside: apps/editor/src/vs/workbench/contrib/void/browser/react/src/

The watch-editor.sh script automatically runs buildreact if react/out/ is missing, and compiles extensions/openclaw/ if extensions/openclaw/out/extension.js is missing.

./watch-editor.sh       # macOS/Linux
watch-editor.bat        # Windows

Runs gulp watch-client with the correct Node version. Initial compile takes ~2 minutes, incremental recompiles take a few seconds.

Ready signal:

Finished compilation with N errors after Xms
Starting compilation...         ← watch mode is now active

./launch-editor.sh      # macOS/Linux
launch-editor.bat       # Windows

Runs apps/editor/scripts/code.sh (or code.bat) against the compiled out/ directory. Any flags are passed through: ./launch-editor.sh --verbose

After saving a source file, watch-client recompiles in seconds. Pick up changes in the running editor: Cmd+Shift+P → Developer: Reload Window

Only needed when editing Void AI React source files:

./watch-react.sh        # macOS/Linux

Two completely independent pipelines:

noEmitOnError is not set — JS is emitted even when TypeScript errors are present.

The React build must run before the main TypeScript build. The main TS code imports the React bundles as external .js files — if they don't exist, TypeScript reports module not found errors (but still emits JS for all other files).

Location: apps/editor/src/vs/workbench/contrib/void/browser/react/

Seven bundles compiled by tsup, each with an index.tsx that exports a mountXxx() function:

• src/ — Source files. Edit these.
• src2/ — Auto-generated by scope-tailwind, which scopes all Tailwind classes under a void-scope namespace to prevent collisions with VS Code's own styles. Never edit src2/ directly — it is overwritten on every build.

The main TypeScript code imports a compiled bundle and calls its mount function:

import { mountSidebar } from './react/out/sidebar-tsx/index.js'
const { rerender, dispose } = mountSidebar(domElement, accessor)

mountFnGenerator handles ReactDOM root creation, registers VS Code service event listeners, and returns lifecycle methods for the workbench contribution system.

Every compilation produces 44 TypeScript errors. They fall into two categories:

Category 1 — React bundles not built (~9 errors, fixable):

Cannot find module '../react/out/diff/index.js'
Cannot find module './react/out/sidebar-tsx/index.js'

Fix: run npm run editor:build-react once.

Category 2 — API version skew in Void fork (~35 errors, expected):

vscode.d.ts(6,1): Definitions of the following identifiers conflict with those in another file
extHostMcp.ts: Property 'env' does not exist on type 'McpServerDefinition'
extHostTypes.ts: Class 'LanguageModelDataPart' incorrectly implements...

The Void fork's implementation is behind the vscode.d.ts type definitions it ships with. These are inherited from upstream and do not affect runtime behaviour. noEmitOnError is unset so all JS is emitted normally. Do not attempt to fix these without a clear reason — they span the VS Code extension host API and changes risk breaking runtime behaviour.

Next.js 16 with Turbopack. Fully independent — no shared build steps with the editor.

npm run web    # dev server at http://localhost:3000

• The helper scripts source ~/.nvm/nvm.sh and call nvm use automatically.
• Editor launches via apps/editor/scripts/code.sh.

• Requires nvm-windows.
• .bat scripts hardcode nvm use 20.18.2 — nvm-windows does not read .nvmrc.
• Editor launches via apps/editor/scripts/code.bat.

End of Agent Reference