[Spec 0602] VS Code Extension for Codev Agent Farm — V1 by amrmelsayed · Pull Request #672 · cluesmith/codev

amrmelsayed · 2026-04-16T05:39:47Z

Summary

VS Code extension for Codev Agent Farm — thin client over Tower's existing API. Includes monorepo restructuring, shared packages, and all V1 implementation phases.

Infrastructure

Monorepo: pnpm workspaces, shared tsconfig base (packages/config)
@cluesmith/codev-types: Shared TypeScript types (WebSocket protocol, API shapes, SSE events)
@cluesmith/codev-core: Shared runtime (TowerClient, auth, workspace encoding, EscapeBuffer)
Dashboard: Moved to packages/dashboard/ as standalone workspace member, imports from shared packages
CI: All workflows build codev-core before tests

Extension (packages/vscode)

Phase 2a: Connection Manager wrapping TowerClient, SecretStorage auth, workspace detection, Output Channel
Phase 2b: SSE client for real-time updates, Tower auto-start as detached daemon
Phase 3: Terminal integration — Pseudoterminal with binary protocol adapter, architect in left editor group, builders as tabs in right group
Phase 4: Unified Codev sidebar — 7 TreeView sections (Needs Attention, Builders, PRs, Backlog, Recently Closed, Team, Status)
Phase 5: 11 Command Palette commands, 3 chord keybindings (Cmd+K A/D/G), status bar with builder/gate counts
Phase 6: Review comment snippet (rev + Tab), Add Review Comment command, REVIEW(...) line highlighting
Phase 7: vsce package verified — 35KB .vsix, zero leaked workspace references

What works

Auto-connect and auto-start Tower on workspace open
Unified Codev sidebar with Needs Attention, Builders, PRs, Backlog, Recently Closed, Team, and Status sections (live SSE-driven refresh)
Architect terminal in left editor group, builder tabs in right group
Spawn, send, approve, cleanup, tunnel, cron commands via Command Palette
Chord keybindings: Cmd+K A (architect), Cmd+K D (send), Cmd+K G (approve)
Status bar showing builder count + blocked gates
Review comment snippet and REVIEW(...) line highlighting
Workspace auto-activation on connect
2442 existing tests pass, CI green

Deferred

Phase 8: Analytics Webview (post-V1)
Phase 9: File link handling — needs different approach than URI scheme
codev-core exports issue (esbuild resolves dist/ not source)
Extension unit tests

Breaking changes

@cluesmith/codev-core is a new runtime dependency of @cluesmith/codev — must be published to npm before codev
Dashboard moved from packages/codev/dashboard/ to packages/dashboard/
Root build scripts: pnpm build builds core then codev
Local install requires both tarballs: pnpm local-install

Ref #602

Extract @cluesmith/codev-shared from existing tower-client.ts and dashboard EscapeBuffer instead of duplicating logic in the extension. Phase 2a now wraps TowerClient with VS Code concerns instead of reimplementing REST/auth/encoding. Spec: move codev-shared from post-V1 to before V1. Plan: add Phase 1b with full deliverables, update dependency map.

- Subpath exports for codev-shared (not barrel, prevents Node builtins leaking into dashboard Vite build) - TowerClient accepts injectable auth (getAuthKey option) - Split getLocalKey into readLocalKey + ensureLocalKey - Pin exact versions, add release protocol to deliverables - Fix Phase 3 stale EscapeBuffer refs (import from shared) - Fix /api/health → /health (matches actual Tower route)

Replace npm commands with pnpm equivalents. Update monorepo prerequisite note to reference pnpm-workspace.yaml and current package folder names.

Core runtime package signals foundational dependency, not optional shared utilities. Makes publishing order obvious.

Create @cluesmith/codev-core with subpath exports: - tower-client: TowerClient class with injectable auth - auth: readLocalKey (read-only) + ensureLocalKey (CLI-only) - workspace: encodeWorkspacePath / decodeWorkspacePath - constants: DEFAULT_TOWER_PORT, AGENT_FARM_DIR - escape-buffer: EscapeBuffer (browser-safe) Original tower-client.ts replaced with thin re-exports. Constructor accepts both number (backward compat) and options object (injectable getAuthKey for VS Code extension).

Replace local copy with re-export from @cluesmith/codev-core/escape-buffer. Subpath exports isolate browser-safe code from Node builtins.

Replace duplicate type definitions in api.ts with imports from @cluesmith/codev-types. Move codev-types to devDependency (types erased at build time by Vite). Dashboard-specific types stay local.

Root scripts use pnpm --filter to build core then codev in order. local-install installs both tarballs in a single npm install -g. Update CLAUDE.md local build testing section for multi-package flow.

Wraps TowerClient from @cluesmith/codev-core with VS Code concerns: - ConnectionManager: state machine, reconnection, Output Channel logging - AuthWrapper: SecretStorage caching over readLocalKey(), 401 re-read - WorkspaceDetector: traverses up to .codev/ or codev/ project root - Status bar showing connection state (Connected/Offline/Reconnecting) - All 7 extension settings registered - Activation on workspaceContains .codev or codev - esbuild externals for ws native bindings

- SSEClient: fetch-based SSE for /api/events, heartbeat filtering, rate-limited dispatch (max 1/second) - Tower auto-start: spawn afx tower start as detached process, poll health with backoff (max 10 attempts) - ConnectionManager: starts SSE on connect, reconnects on SSE drop, auto-starts Tower when disconnected

- CodevPseudoterminal: binary protocol adapter (0x00/0x01 framing), EscapeBuffer from codev-core, backpressure (16KB chunks, 1MB disconnect), resize deferral during replay, reconnection banner - TerminalManager: WebSocket pool (max 10), editor layout (architect left group, builders right group), terminal lifecycle - Commands: Open Architect Terminal, Open Builder Terminal, New Shell

Encode workspace path for /api/state and /api/tabs/shell requests. These are workspace-scoped Tower routes requiring the base64url encoded path prefix.

Move workspace-scoped API calls into TowerClient (codev-core) instead of manual encoding in the extension. Extension commands now use client.getWorkspaceState() and client.createShellTab() directly.

ConnectionManager calls client.activateWorkspace() after successful health check to ensure architect terminal exists before user tries to open it.

Create terminals directly in editor area via createTerminal location option. Architect in ViewColumn.One, builders in ViewColumn.Two. VS Code auto-creates the split when ViewColumn.Two is first used.

Replace moveIntoEditor references with stable TerminalLocation.Editor + ViewColumn API. Update layout descriptions, risks, and deliverables.

Register Codev view container with 7 TreeView sections: Needs Attention, Builders, Pull Requests, Backlog, Recently Closed, Team, and Status. Overview data refreshes on SSE events. Team section conditional on teamEnabled. Status shows Tower connection, tunnel, and cron state.

Overview cache now calls client.getOverview(workspacePath) instead of raw /api/overview request. TowerClient handles the workspace query parameter internally.

Rename overview-cache.ts to overview-data.ts. Update all view imports. Set codev.teamEnabled VS Code context from workspace state so Team section shows/hides based on actual team configuration.

… metadata Move icon to icons/ (src/ is excluded by .vscodeignore), bump to 0.2.0, add repository field, license, and replace template README with real docs.

All four CI jobs need codev-core dist/ built before running tests or building codev. Without it, imports from @cluesmith/codev-core fail with ERR_MODULE_NOT_FOUND.

Commands: spawn, send, approve, cleanup, refresh, tunnel, cron. Chord keybindings: Cmd+K A (architect), Cmd+K D (send), Cmd+K G (approve). Status bar shows builder count + blocked gate count. Update README with full command list.

The e2e.yml and dashboard-e2e.yml workflows were missing the "Build core package" step before building codev. Dashboard imports from @cluesmith/codev-core which requires core's dist/ to exist.

- Snippet: rev + Tab in markdown files inserts REVIEW(@architect): - Command: Add Review Comment with language-aware comment syntax - Decorations: highlight existing REVIEW(...) lines with colored background - Update README with review comments section

- Point core exports types to dist/*.d.ts instead of src/*.ts - Remove src from core files field (only ship dist) - Update verify-install.mjs to accept multiple tarballs - Pack core tarball in CI and pass both to verify script

Spec compliance, deviations from plan, lessons learned, technical debt, and follow-up items for Phases 1-7.

arch.md: Add monorepo structure, VS Code extension architecture, update diagram for dual clients, fix stale references (dashboard location, af→afx, tower-client re-export, workspace-scoped routes). Team profile: Update role and contributions for amrmelsayed.

waleedkadous · 2026-04-16T13:21:00Z

Architect Review

Approved. Excellent work on this — the thin client architecture is clean, the terminal adapter handles all the hard edge cases from the spec (escape buffering, backpressure, resize deferral), and the monorepo restructuring is solid.

Notes for the record:

The scaffold test file is fine for V1, but real extension tests (connection state machine, workspace detection, escape buffer adapter) should be a fast follow-up
codev-core exports issue (esbuild resolves dist/ not source) is documented and acceptable as tech debt
2442 existing tests pass, CI green

Please merge when ready (regular merge, no squash).

waleedkadous

PR looks good! Only issue is testing looks thin, but we can improve that in a followup PR.

amrmelsayed added 28 commits April 14, 2026 15:58

[Spec 0602] Update plan for pnpm migration

c26f52b

Replace npm commands with pnpm equivalents. Update monorepo prerequisite note to reference pnpm-workspace.yaml and current package folder names.

[Spec 0602] Rename codev-shared to codev-core in spec and plan

eb6922e

Core runtime package signals foundational dependency, not optional shared utilities. Makes publishing order obvious.

[Spec 0602][Phase 1b] Dashboard imports EscapeBuffer from codev-core

b128988

Replace local copy with re-export from @cluesmith/codev-core/escape-buffer. Subpath exports isolate browser-safe code from Node builtins.

[Spec 0602] Dashboard imports types from codev-types

ac0d7bb

Replace duplicate type definitions in api.ts with imports from @cluesmith/codev-types. Move codev-types to devDependency (types erased at build time by Vite). Dashboard-specific types stay local.

[Spec 0602] Add root build/test/local-install scripts, update CLAUDE.md

0190e04

Root scripts use pnpm --filter to build core then codev in order. local-install installs both tarballs in a single npm install -g. Update CLAUDE.md local build testing section for multi-package flow.

[Spec 0602] Use workspace-scoped routes for terminal commands

ab36277

Encode workspace path for /api/state and /api/tabs/shell requests. These are workspace-scoped Tower routes requiring the base64url encoded path prefix.

[Spec 0602] Add getWorkspaceState and createShellTab to TowerClient

109acec

Move workspace-scoped API calls into TowerClient (codev-core) instead of manual encoding in the extension. Extension commands now use client.getWorkspaceState() and client.createShellTab() directly.

[Spec 0602] Auto-activate workspace on Tower connect

a01d2db

ConnectionManager calls client.activateWorkspace() after successful health check to ensure architect terminal exists before user tries to open it.

[Spec 0602] Use TerminalLocation.Editor instead of moveIntoEditor

6f218b1

Create terminals directly in editor area via createTerminal location option. Architect in ViewColumn.One, builders in ViewColumn.Two. VS Code auto-creates the split when ViewColumn.Two is first used.

[Spec 0602] Update spec and plan for TerminalLocation.Editor API

4f12c44

Replace moveIntoEditor references with stable TerminalLocation.Editor + ViewColumn API. Update layout descriptions, risks, and deliverables.

[Spec 0602] Add getOverview to TowerClient, fix workspace-scoped fetch

a39468f

Overview cache now calls client.getOverview(workspacePath) instead of raw /api/overview request. TowerClient handles the workspace query parameter internally.

[Spec 0602] Rename overview-cache to overview-data, fix Team visibility

e745aa5

Rename overview-cache.ts to overview-data.ts. Update all view imports. Set codev.teamEnabled VS Code context from workspace state so Team section shows/hides based on actual team configuration.

Align all package licenses to Apache-2.0 to match root LICENSE

ed10242

[Spec 0602] Fix VS Code extension packaging: icon path, version bump,…

f2409fd

… metadata Move icon to icons/ (src/ is excluded by .vscodeignore), bump to 0.2.0, add repository field, license, and replace template README with real docs.

[Spec 0602] Fix CI: build codev-core before tests in all jobs

0d79189

All four CI jobs need codev-core dist/ built before running tests or building codev. Without it, imports from @cluesmith/codev-core fail with ERR_MODULE_NOT_FOUND.

Fix CI: add missing core build step to e2e and dashboard workflows

edf5fc0

The e2e.yml and dashboard-e2e.yml workflows were missing the "Build core package" step before building codev. Dashboard imports from @cluesmith/codev-core which requires core's dist/ to exist.

[Spec 0602] Add *.vsix to gitignore

72dcd9a

[Spec 0602][Review] SPIR review for VS Code extension

bc21210

Spec compliance, deviations from plan, lessons learned, technical debt, and follow-up items for Phases 1-7.

amrmelsayed changed the title ~~[Spec 0602] VS Code Extension — Phases 1-4~~ [Spec 0602] VS Code Extension for Codev Agent Farm — V1 Apr 16, 2026

amrmelsayed requested a review from waleedkadous April 16, 2026 11:19

amrmelsayed marked this pull request as ready for review April 16, 2026 11:20

waleedkadous approved these changes Apr 16, 2026

View reviewed changes

waleedkadous merged commit 5e01a41 into main Apr 16, 2026
6 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Spec 0602] VS Code Extension for Codev Agent Farm — V1#672

[Spec 0602] VS Code Extension for Codev Agent Farm — V1#672
waleedkadous merged 29 commits intomainfrom
spir/0602-vscode-extension

amrmelsayed commented Apr 16, 2026 •

edited

Loading

Uh oh!

waleedkadous commented Apr 16, 2026

Uh oh!

waleedkadous left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

amrmelsayed commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Infrastructure

Extension (packages/vscode)

What works

Deferred

Breaking changes

Uh oh!

waleedkadous commented Apr 16, 2026

Architect Review

Uh oh!

waleedkadous left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

amrmelsayed commented Apr 16, 2026 •

edited

Loading