Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
268 lines (186 loc) · 8.75 KB

DEVELOPMENT.md

File metadata and controls

268 lines (186 loc) · 8.75 KB
Raw

AgentPatchCheck Development

Primary development paths

APC Headless Runtime and the read-only APC Console are the primary AgentPatchCheck development paths. Use the Runtime and benchmark documentation for controlled repair and evaluation workflows; start the Console independently with cd apc-console, npm ci, and npm run dev.

The root web and desktop commands below are retained upstream/legacy product surface. They remain available for compatibility, but are not the APC Runtime & Evaluation development path.

Retained root web and desktop requirements

  • Node.js 22+
  • npm 10+

Install

npm run install:all

Retained root web and desktop hot reload workflow

Fast path:

npm run dev:full
  • Starts the runtime in watch mode and the Vite web UI dev server together
  • Auto-picks free runtime and web UI ports so multiple checkouts can run side by side
  • Best for day-to-day source development, especially web UI work and runtime changes that benefit from fast iteration

Manual equivalent in two terminals:

  1. Runtime server (API + PTY agent runtime):
npm run dev
  • Runs on http://127.0.0.1:3484
  1. Web UI (Vite HMR):
npm run web:dev
  • Runs on http://127.0.0.1:4173
  • /api/* requests from Vite are proxied to http://127.0.0.1:3484

Use http://127.0.0.1:4173 while developing UI so changes hot reload.

Choose the right workflow

Use npm run dev:full when you are developing the retained root web and desktop surface and want fast iteration. It runs the source checkout with tsx watch plus the Vite web UI dev server, so runtime changes reload and web UI changes get HMR.

By default, dev:full starts with --skip-shutdown-cleanup so stopping a debug/dev instance does not move cards to Trash or delete task worktrees from active boards.

To opt back into shutdown cleanup while using dev:full, run:

npm run dev:full -- --with-shutdown-cleanup

If node_modules has not been installed in this worktree, dev:full auto-runs npm ci before launch.

Use npm run dogfood when you want to validate the latest built CLI behavior more realistically. It builds the current checkout and launches dist/cli.js, which is better for checking packaged behavior, startup and shutdown flows, multi-instance dogfooding, and launch behavior against a target project.

Retained root VS Code F5 debugging

The repo includes .vscode/launch.json with two configurations:

  • Dev (Full Stack): Launches the same workflow as npm run dev:full, starting both the runtime and Vite in one terminal.
  • Run Tests: Runs vitest run with the debugger so you can set breakpoints in tests.

Shutdown cleanup flags:

  • --skip-shutdown-cleanup: do not move sessions to trash or delete task worktrees on shutdown

Retained root packaged CLI

npm run build
node dist/cli.js

This mode serves built web assets from dist/web-ui and does not hot reload the web UI.

Runtime port options:

# fixed port
node dist/cli.js --port 3484

# pick the first free port starting at 3484
node dist/cli.js --port auto

You can still use KANBAN_RUNTIME_PORT if needed, but --port is preferred for local multi-instance runs.

Retained root CLI dogfooding

Run your stable orchestrator first (main checkout):

cd /path/to/AgentPatchCheck-main
npm run build
node dist/cli.js --port 3484

Then run a test checkout against a target project (feature worktree):

cd /path/to/AgentPatchCheck-feature-worktree
npm run dogfood -- --project /path/to/target/repo --port auto

If --project is omitted, the launcher starts the retained root CLI from a non-git cwd and opens the first indexed project (if any):

npm run dogfood -- --port auto

Dogfood launcher behavior:

  • builds the current checkout by default
  • launches dist/cli.js with cwd set to the target project
  • supports --port <number|auto>
  • supports --no-open
  • supports --skip-build when you already built and want faster restarts
  • is the right choice when you want to test the latest built CLI rather than the source-mode dev server

Retained kanban CLI compatibility

After cloning and installing dependencies, create/update the global CLI link from this repo:

npm run link

Verify:

which kanban
kanban --version

This compatibility command can then run from a project directory:

cd /path/to/your/project
kanban

After local code changes, run npm run build again before using the linked command.

When switching between worktrees, re-run npm run link from the worktree you want to test so the global kanban binary points at the right dist/cli.js.

Remove the global link:

npm run unlink

Scripts

  • npm run build: build runtime and bundled web UI into dist
  • npm run dogfood -- [--project <path>] [--port <number|auto>] [--no-open] [--skip-build]: build and launch this checkout, optionally targeting a specific project path
  • npm run dev: run CLI in watch mode
  • npm run dev:full: run the runtime watch server and Vite web UI dev server together
  • npm run web:dev: run web UI dev server
  • npm run web:build: build web UI
  • npm run typecheck: typecheck runtime
  • npm run web:typecheck: typecheck web UI
  • npm run test: run runtime tests
  • npm run web:test: run web UI tests
  • npm run check: lint, typecheck, and test runtime package

Tests

  • test/integration: integration tests for runtime behavior and startup flows
  • test/runtime: runtime unit tests
  • test/utilities: shared test helpers

Retained root agent tracking and runtime hooks

The retained root product surface tracks agent session state with runtime hook events. The core transition model is:

  • in_progress -> review
  • review -> in_progress

Internal runtime session states are named running and awaiting_review, and hook events are transition intents:

  • to_in_progress for review -> in_progress
  • to_review for in_progress -> review

How it works end to end:

  1. prepareAgentLaunch wires each agent with hook commands or hook-aware wrappers.
  2. Hook handlers call kanban hooks ... subcommands.
  3. kanban hooks ingest --event <to_review|to_in_progress> reads hook context from env:
    • KANBAN_HOOK_TASK_ID
    • KANBAN_HOOK_WORKSPACE_ID
    • KANBAN_HOOK_PORT
  4. The ingest command calls runtime TRPC hooks.ingest.
  5. The runtime applies guarded transitions and ignores duplicates or invalid transitions as no-ops.

Current agent mappings:

These are external agent/file-hook names where the agent config requires them. They are distinct from Cline SDK plugin runtime hooks such as beforeRun, beforeTool, afterTool, and afterRun.

  • Claude
    • UserPromptSubmit, PostToolUse, PostToolUseFailure emit to_in_progress
    • Stop, PermissionRequest, and Notification with permission_prompt emit to_review
  • Codex
    • wrapper enables TUI session logging and maps:
      • task_started and exec_command_begin to to_in_progress
      • *_approval_request to to_review
    • Codex notify completion path also emits to_review
  • Gemini
    • BeforeAgent and AfterTool emit to_in_progress
    • AfterAgent emits to_review
    • hook command writes {} to stdout immediately to satisfy Gemini hook contract, then notifies in background
  • OpenCode
    • plugin maps busy activity to to_in_progress
    • plugin maps idle/error and permission ask to to_review
    • plugin filters child sessions to avoid false transitions from nested runs
  • Droid
    • PreToolUse for active tools like Read, Grep, Glob, FetchUrl, WebSearch, Execute, Task, Edit, and Create emits to_in_progress
    • PreToolUse for AskUser and Stop emit to_review
    • PostToolUse for AskUser and UserPromptSubmit emit to_in_progress

Important behavior details:

  • Hooks are best-effort and should not crash or block the underlying agent process.
  • Hook notify paths are asynchronous to keep agent UX responsive.
  • Runtime transition guards are authoritative and prevent state flapping from duplicate events.
  • Hook transport is implemented in Node and invoked through kanban hooks ..., so the behavior is consistent across Windows and non-Windows environments.

For a full technical breakdown, see:

  • .plan/docs/runtime-hooks-architecture.md

PostHog telemetry config

The web UI reads PostHog settings at build time:

  • POSTHOG_KEY
  • POSTHOG_HOST

Local development:

  • Set these in web-ui/.env.local (see web-ui/.env.example).
  • If POSTHOG_KEY is missing, telemetry does not initialize.

Release builds:

  • The publish workflow injects POSTHOG_KEY and POSTHOG_HOST from GitHub Secrets.
  • POSTHOG_HOST is optional and defaults to https://data.cline.bot.

Result:

  • Official releases have telemetry enabled.
  • Forks and source builds have telemetry disabled unless a key is explicitly provided.