Skip to content

docs(vscode): expand README for shipped features and config #842

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
amrmelsayed merged 1 commit into from
May 24, 2026
Merged

docs(vscode): expand README for shipped features and config #842

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
210 changes: 167 additions & 43 deletions packages/vscode/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
# Codev for VS Code

Bring Codev's Agent Farm into VS Code — monitor builders, open terminals, approve gates, and manage your development workflow without leaving the IDE.
Bring Codev's Agent Farm into VS Code — monitor builders, open terminals, approve gates, run dev servers, and manage your development workflow without leaving the IDE.

## Features

- **Unified Sidebar** — Workspace, Builders, Pull Requests, Backlog, Recently Closed, Team, and Status in a single pane (blocked builders are flagged inline in Builders, with live item counts in the view titles)
- **Native Terminals** — Architect / builder / shell terminals in the editor area with full vertical height; dev servers run in the bottom panel
- **Managed dev servers** — start/stop the dev server for the current workspace or any builder worktree from the sidebar; one runs at a time and swaps on demand
- **Gate review** — a toast with one-click **Approve** when a builder reaches a human-approval gate, plus inline `REVIEW(@architect):` comment threads on plan/spec files
- **Live Spawn Notifications** — Get notified (or auto-open a terminal) the moment a new builder starts
- **Status Bar** — Connection state, builder count, blocked gates at a glance
- **Command Palette & shortcuts** — Open terminals, send messages, approve gates, toggle the sidebar
- **Auto-Connect** — Detects Codev workspaces and connects to Tower automatically
- **Auto-Start Tower** — Starts Tower if not running (configurable)
- **Unified sidebar** — Workspace, Builders, Pull Requests, Backlog, Recently Closed, Team, and Status in a single pane. Blocked builders are flagged inline in Builders; live item counts appear in view titles.
- **Native terminals** — Architect / builder / shell terminals in the editor area; dev servers in the bottom panel.
- **One-click dev servers** — Start / Stop the dev server for the current workspace or any builder worktree from the sidebar (`Cmd/Ctrl+Alt+R` / `Cmd/Ctrl+Alt+S`). One runs at a time and swaps on demand. Configurable via `worktree.devCommand` in `.codev/config.json` — see the **Dev servers and runnable worktrees** section below.
- **Open Dev URL rows** — surface staging / preview / tunnel links as one-click rows in the Workspace view via `worktree.devUrls`.
- **Per-engineer config overrides** — `.codev/config.local.json` layers your personal settings (local devCommand, tunnel hostnames, staging URLs) over the shared project config without committing them.
- **Per-builder changed files** — expand any builder row to see its diff vs main inline with native SCM-style status badges. Toggle between folder tree and flat list.
- **Gate review** — toast with one-click **Approve** when a builder reaches a human-approval gate, plus inline `REVIEW(@architect):` comment threads on plan / spec files.
- **"Waiting on input" indicator** — a builder whose terminal has been idle for ≥5 minutes outside a gate gets a chat-bubble icon in Builders and is counted in the status bar.
- **Image paste** — `Cmd+Alt+V` / `Ctrl+Alt+V` in a focused Codev terminal uploads the clipboard image to Tower and injects the saved file path into the terminal.

## Requirements

Expand All @@ -26,6 +26,111 @@ Bring Codev's Agent Farm into VS Code — monitor builders, open terminals, appr
2. Open a Codev project in VS Code
3. The extension auto-detects the workspace and connects to Tower
4. Click the Codev icon in the Activity Bar to see your builders, PRs, and backlog
5. *(Optional)* Add `worktree.devCommand` to `.codev/config.json` to unlock one-click dev servers — see the **Dev servers and runnable worktrees** section below

## Sidebar tour

The Codev sidebar contains seven collapsible views:

- **Workspace** — Open Architect, Open Web Interface, Spawn Builder, New Shell, and Start / Stop Dev Server rows. Any `worktree.devUrls` you've configured appear here as **Open Dev URL** rows.
- **Builders** — every active builder, with status (active / blocked / waiting on input / awaiting). Click a row to open its terminal *and* expand its changed-files list. Right-click for the full builder action menu (see the **Builder actions (right-click)** section below). The title bar carries buttons to toggle accordion mode and tree-vs-list file view.
- **Pull Requests** — open PRs in the repo, with a live count in the title.
- **Backlog** — open issues without a builder. Inline row actions drop the issue's `#<id>` into the architect input, preview the issue, spawn a builder for it, open it in the browser, or copy the issue number.
- **Recently Closed** — recently closed PRs; manual refresh from the title bar.
- **Team** — per-member counts (`Assigned: N`, `Open PRs: N`, `Last 7d: X merged, Y closed`). Manual refresh from the title bar.
- **Status** — connection state; click to reconnect if Tower drops.

## Builder actions (right-click)

Right-click any builder in the Builders view for three grouped action menus:

**Primary**

| Action | Description |
|---|---|
| Open Builder Terminal | Same as left-click — opens the AI terminal in the right editor group |
| Approve Gate | Approve the builder's current human-approval gate (blocked rows only) |
| View Plan | Open the plan file for this builder (PIR builders only) |

**Worktree**

| Action | Description |
|---|---|
| View Diff | Open a single unified diff editor showing `main…HEAD` with a file-list pane and status icons |
| Open Worktree in New Window | Open `.builders/<id>/` as its own VS Code window for native SCM and per-file diffs |
| Open Worktree Folder | Reveal `.builders/<id>/` in Finder / Explorer / xdg-open |

**Dev**

| Action | Description |
|---|---|
| Run Worktree Setup | Re-apply `worktree.symlinks` + `worktree.postSpawn` to the existing worktree (idempotent — use when the lockfile changed or config was extended after spawn) |
| Run Dev Server | Spawn the dev PTY in this builder's worktree; prompts to swap if another dev is running |
| Stop Dev Server | Kill the running dev PTY and close its tab |

## Dev servers and runnable worktrees

Codev can run a single dev server at a time — either for your main checkout, or for any builder's worktree — and swap between them on demand. The single-slot model is deliberate: dev PTYs reuse main's ports so OAuth callbacks, cookies, and webhooks keep working unchanged.

### Starting and stopping

- **For the current workspace** — the **Start Dev Server** row in the Workspace view, or `Cmd/Ctrl+Alt+R`. **Stop Dev Server** (only visible while running) or `Cmd/Ctrl+Alt+S`.
- **For a builder worktree** — right-click the builder → **Run Dev Server** / **Stop Dev Server**.
- Starting one target while another is already running prompts you to swap (the old PTY is killed cleanly, then the new one starts).

### Configuration: `.codev/config.json`

Add a `worktree` block to your project's `.codev/config.json`. Without `devCommand` configured, the Start Dev Server row stays hidden — it would have nothing to run.

```jsonc
{
"worktree": {
"devCommand": "pnpm dev",
"symlinks": [
".env.local",
".env.development.local",
"packages/*/.env.local"
],
"postSpawn": [
"pnpm install --frozen-lockfile"
],
"devUrls": [
{ "label": "Staging", "url": "https://staging.example.com" },
{ "label": "Storybook", "url": "http://localhost:6006" }
]
}
}
```

- **`devCommand`** — the foreground command that starts your dev server. Run by the sidebar Start Dev Server rows and the CLI (`afx dev main`, `afx dev <builder-id>`).
- **`symlinks`** — glob patterns of files to symlink from the main checkout into each new builder worktree (env files, generated configs, etc.). Symlinks, not copies — edits in main reflect instantly in any running dev session. Root `.env` and `.codev/config.json` are always symlinked regardless.
- **`postSpawn`** — shell commands run sequentially inside each new worktree after creation (e.g. `pnpm install --frozen-lockfile`). A non-zero exit aborts the spawn loudly so the half-built worktree stays for inspection.
- **`devUrls`** — array of `{ label, url }` entries that show up as one-click **Open Dev URL** rows in the Workspace view. Distinct from Open Web Interface, which always points at the Tower dashboard.

### Per-engineer overrides: `.codev/config.local.json`

Create a sibling `.codev/config.local.json` (gitignored) to override or extend the shared config with your personal values:

```jsonc
{
"worktree": {
"devCommand": "pnpm dev --port 3001",
"devUrls": [
{ "label": "My tunnel", "url": "https://amr.ngrok.app" }
]
}
}
```

Both files are watched live — every open VS Code window's sidebar re-renders on save, and the override applies both to what the Workspace view shows *and* to the command Tower actually runs.

### URLs are load-bearing

Dev PTYs use the same ports as your main checkout intentionally — OAuth callbacks, CORS allowlists, cookie scoping, and webhook URLs are all keyed off origin. Before starting a sidebar dev server, stop any manually-run `pnpm dev` first, or the new PTY will fail to bind with `EADDRINUSE`.

### Recipes for other stacks

The pnpm example above adapts directly to npm / yarn / bun / cargo / poetry / go. See [Runnable Worktree Recipes](https://github.com/cluesmith/codev/blob/main/CLAUDE.md#runnable-worktree-recipes) in the project's `CLAUDE.md` for ready-to-paste blocks.

## Layout

Expand All @@ -46,54 +151,73 @@ Bring Codev's Agent Farm into VS Code — monitor builders, open terminals, appr
+----------------------------------------------+
```

## Keyboard shortcuts

| Shortcut | Action |
|---|---|
| `Cmd/Ctrl+K A` | Open Architect Terminal |
| `Cmd/Ctrl+K D` | Send Message (pick a builder + type a message) |
| `Cmd/Ctrl+K G` | Approve Gate |
| `Cmd/Ctrl+Alt+C` | Toggle the Codev sidebar (show & focus, or close if active) |
| `Cmd/Ctrl+Alt+R` | Start Dev Server (current workspace) |
| `Cmd/Ctrl+Alt+S` | Stop Dev Server (current workspace) |
| `Cmd/Ctrl+Alt+V` | Paste clipboard image into the focused Codev terminal — uploads to Tower and injects the saved file path |

## Commands

| Command | Shortcut | Description |
|---------|----------|-------------|
| Codev: Open Architect Terminal | `Cmd+K, A` | Open the architect terminal in the left editor group |
| Codev: Send Message | `Cmd+K, D` | Pick a builder, type a message, send via Tower |
| Codev: Approve Gate | `Cmd+K, G` | Approve a blocked builder's gate |
| Toggle Codev Sidebar | `Cmd+Alt+C` / `Ctrl+Alt+C` | Show & focus the Codev sidebar, or close it if it's the active view |
| Codev: Open Builder Terminal | | Pick a builder and open its terminal |
| Codev: New Shell | | Create a new persistent shell terminal |
| Codev: Spawn Builder | | Issue number + protocol + optional branch |
| Codev: Cleanup Builder | | Remove a completed builder's worktree |
| Codev: Start / Stop Dev Server (this workspace) | `Cmd/Ctrl+Alt+R` / `Cmd/Ctrl+Alt+S` | Run/stop the dev server for the current workspace (sidebar Workspace rows) |
| Codev: Run / Stop Dev Server | | Run/stop a builder worktree's dev server (builder right-click) |
| Codev: Open Worktree in New Window | | Open `.builders/<id>/` as its own VSCode window |
| Codev: Run Worktree Setup | | Re-apply `worktree.symlinks` + `postSpawn` to an existing worktree |
| Codev: Refresh Overview | | Manually refresh sidebar data |
| Codev: Refresh Team | | Re-fetch the Team view's GitHub data |
| Codev: Connect Tunnel | | Connect cloud tunnel for remote access |
| Codev: Disconnect Tunnel | | Disconnect cloud tunnel |
| Codev: Cron Tasks | | List, run, enable, or disable cron tasks |
| Codev: Add Review Comment | | Insert a `REVIEW(@architect):` comment at cursor |

## When a Builder Spawns
All actions are also reachable via the Command Palette (`Cmd/Ctrl+Shift+P`):

| Command | Notes |
|---|---|
| Codev: Open Builder Terminal | Pick a builder |
| Codev: New Shell | Create a persistent shell terminal |
| Codev: Spawn Builder | Issue number + protocol (SPIR / ASPIR / AIR / BUGFIX / PIR / …) + optional branch |
| Codev: Cleanup Builder | Remove a completed builder's worktree |
| Codev: Refresh Overview / Refresh Team | Manually refresh sidebar data |
| Codev: Reconnect to Tower | Re-establish the WebSocket if Tower drops |
| Codev: Connect / Disconnect Tunnel | Cloud tunnel for remote access |
| Codev: Cron Tasks | List, run, enable, or disable cron tasks |
| Codev: Add Review Comment | Insert a `REVIEW(@architect):` comment at cursor |

Right-click actions on builders and workspace rows are listed in the **Builder actions (right-click)** section above.

## When a builder spawns

Whenever a new builder starts (e.g. you ran `afx spawn 42`), the extension can open its terminal for you. Choose how with the `codev.autoOpenBuilderTerminal` setting:

- **Notify** (default) — A toast appears with an **Open Terminal** button.
- **Auto** — The terminal opens immediately in the right editor group.
- **Off** — No toast, no terminal. Click the builder in the sidebar when you want it.
- **Notify** *(default)* — a toast appears with an **Open Terminal** button.
- **Auto** — the terminal opens immediately in the right editor group.
- **Off** — no toast, no terminal. Click the builder in the sidebar when you want it.

## Review Comments
## Gate review

- **Snippet**: Type `rev` + Tab in markdown files to insert a review comment
- **Command**: `Cmd+Shift+P` → "Codev: Add Review Comment" inserts with correct comment syntax for any file type
- **Highlighting**: Existing `REVIEW(...)` lines are highlighted with a colored background
When a builder reaches a human-approval gate, a toast surfaces it with the issue and gate context plus a per-gate quick action (View Plan / Run Dev / Review) and an **Approve** button. The seen-toast set persists across reloads, so a still-blocked builder doesn't re-toast on every window reload. Silence the toasts with `codev.gateToasts.enabled: false`.

## Review comments

- **Snippet** — type `rev` + Tab in markdown files to insert a review comment.
- **Command** — `Cmd/Ctrl+Shift+P` → "Codev: Add Review Comment" inserts with the correct comment syntax for any file type.
- **Highlighting** — existing `REVIEW(...)` lines are highlighted with a colored background.
- **Inline threads** — leave `REVIEW(@architect):` threads on plan / spec files via VS Code's Comments API; submit and delete from the gutter.

## Settings

| Setting | Default | Description |
|---------|---------|-------------|
|---|---|---|
| `codev.towerHost` | `localhost` | Tower server host |
| `codev.towerPort` | `4100` | Tower server port |
| `codev.workspacePath` | auto-detect | Override workspace path |
| `codev.workspacePath` | auto-detect | Override workspace path for Tower matching |
| `codev.terminalPosition` | `editor` | Terminal placement (`editor` or `panel`) |
| `codev.autoConnect` | `true` | Connect to Tower on activation |
| `codev.autoStartTower` | `true` | Auto-start Tower if not running |
| `codev.autoOpenBuilderTerminal` | `notify` | Behavior on builder-spawned events (`off` / `notify` / `auto`) |
| `codev.overviewRefreshSeconds` | `60` | Auto-refresh Builders/PRs/Backlog/Recently Closed every N seconds while the sidebar is visible (`0` = event-only) |
| `codev.autoOpenBuilderTerminal` | `notify` | Behavior on builder-spawn events (`off` / `notify` / `auto`) |
| `codev.overviewRefreshSeconds` | `60` | Auto-refresh Builders / PRs / Backlog / Recently Closed every N seconds while the sidebar is visible (`0` = event-only) |
| `codev.gateToasts.enabled` | `true` | Show a toast when a builder reaches a human-approval gate |
| `codev.buildersAutoCollapse` | `true` | Builders view accordion — expanding one builder auto-collapses the others |
| `codev.buildersFileViewAsTree` | `true` | Render a builder's changed-files list as a folder tree (`false` for a flat list) |
| `codev.telemetry` | `false` | No telemetry collected |

## Advanced

- **PIR protocol** — for changes that need pre-PR review of running code (mobile, UI, integration). Exposed in the Spawn Builder picker. See [`codev/protocols/pir/protocol.md`](https://github.com/cluesmith/codev/blob/main/codev-skeleton/protocols/pir/protocol.md).
- **Worktree recipes for other stacks** — npm / yarn / bun / cargo / poetry / go ready-to-paste blocks in [`CLAUDE.md`](https://github.com/cluesmith/codev/blob/main/CLAUDE.md#runnable-worktree-recipes).
Loading