# VS Code Extension and IDE Integration

The Metateam VS Code extension connects the crew to the editor. Operators see live agent status, conversation transcripts, diagnostics, and debug events inside VS Code. Agents use `metateam ide` commands from their terminals to query editor state, publish review findings, and control the debugger.

This page has two main sections. **For Operators** covers what the human sees and does inside VS Code. **For Agents** covers the CLI commands that agents run from their terminals. Each section is self-contained.

## Quick Start

Install the extension:

```
$ metateam ide install
```

For Cursor instead of VS Code:

```
$ metateam ide install --cursor
```

Reload the editor after installation. The extension activates automatically when VS Code opens a workspace containing a `.crew` directory. Once the crew dashboard is running (`metateam` in a terminal), the sidebar populates with live agents.

---

## For Operators

This section covers the VS Code UI: sidebar, panels, status bar, diagnostics, debug notifications, and available commands.

### Automatic Context Sharing

The extension shares the current VS Code state with the crew automatically. That shared context includes:

- the active file
- cursor position
- the current selection
- git status
- diagnostics summary
- sidebar visibility
- terminal state

When the crew lead's session receives a new prompt from the operator, a compact summary of the current VS Code state is included automatically. This happens through the UserPromptSubmit hook in the lead agent's coding session, not through the crew messaging system.

The shared context is a one-line diff, not the full file contents. It is designed to give the crew lead situational awareness without copying the entire editor buffer into the prompt.

The dashboard bottom bar also shows a `vsc` indicator for this connection:

- grey `vsc` — the VS Code extension is not connected
- green `vsc` — the VS Code extension is connected and sharing IDE context

This gives the operator a quick check for whether editor state is reaching the crew. If the indicator stays grey, reload the extension or restart the crew dashboard.

### Sidebar: Crew Agent List

The Metateam icon in the Activity Bar opens a sidebar with a native TreeView listing all active agents.

**What each row shows:**

| Element | Content |
|---------|---------|
| Icon | Star for the crew leader, person icon for other agents |
| Label | Agent name (e.g., `Forge`) |
| Description | `short_role - client - activity` (e.g., `developer - claude - idle 3m`) |
| Tooltip | Hover for rich detail: role, client, backend, model, context usage, tokens, and session details |

The crew leader sorts first. Remaining agents sort alphabetically.

**Click** an agent row to open its conversation panel.

**Right-click** an agent row for context menu actions:

| Action | What It Does |
|--------|-------------|
| Open Conversation | Open the agent's live transcript panel |
| Release Agent | Remove the agent from the crew |
| Reset Agent | Clear the agent's session and restart |
| Toggle Silence | Mute or unmute crew notifications |
| Clear Diagnostics | Remove diagnostics published by this agent |

**Overview row** at the top of the sidebar. Click to open the Overview panel. Right-click for crew-level actions: Open Overview, Summon Agent, Toggle Silence.

**Sidebar title bar** provides Refresh and Dashboard buttons, plus a menu with Summon Agent, Toggle Scheduler, Toggle Silence, Set Watchdog, and Clear All Diagnostics.

**Connection states** — when the connection is not available, the sidebar shows:

- **Connecting** — connection in progress
- **Disconnected** — no crew dashboard running; start one with `metateam` in the terminal
- **No live agents** — connected, but no agents are currently summoned

### Conversation Panels

Click any agent in the sidebar to open a live conversation panel as an editor tab. Each panel shows a structured, formatted transcript of the agent's session.

**Block types and rendering:**

| Block Type | Rendering |
|------------|-----------|
| Text (assistant) | Markdown-rendered with syntax-highlighted code blocks |
| Thinking | Collapsible section (click to expand) |
| Tool use | Compact header with tool name; collapsible JSON input |
| Tool result | Preformatted output; errors highlighted |
| User messages | Distinguished by role header |
| Usage | Compact token count under each assistant turn |

The panel updates in real time as the agent works. Auto-scroll follows new content when the view is at the bottom; scrolling up to read earlier content pauses auto-scroll.

When an agent starts a new session (via context reset), the panel clears and loads the new transcript automatically.

Each agent gets its own panel tab. Opening an agent that already has a panel brings the existing tab forward. Releasing and re-summoning an agent creates a fresh panel.

### Overview Panel

Open from the sidebar Overview row, the dashboard button, the status bar, or the Command Palette (`Metateam: Open Overview`).

The Overview is a WebviewPanel tab showing:

**Agent cards** — each agent as a card:

| Field | Content |
|-------|---------|
| Name | Agent name with status indicator |
| Role | Short role label (e.g., `developer`, `reviewer`) |
| Client | `claude` or `codex` |
| Model | Friendly model label (e.g., `Opus 4.6`) |
| Context | Remaining context window as percentage |
| Tokens | Used/total token count |
| Activity | Current activity label or idle duration |

Cards have action buttons: Open, Release, Reset.

**Crew state** in the header: silence status and remaining duration, scheduler health and rule count, watchdog threshold and message.

**Unified feed** at the bottom: a live crew-wide transcript feed. User messages are deduplicated by body text, so multi-target sends appear once.

### Status Bar

A persistent item at the left of the VS Code status bar:

```
$(hubot) NCC: 5 agents | connected
```

| Element | Meaning |
|---------|---------|
| Robot icon | Metateam indicator |
| Crew name | Name of the active crew |
| Agent count | Number of live agents |
| Connection state | `connected`, `connecting`, or `disconnected` |

Click to open the Overview panel. Hover for crew detail tooltip. When the crew is disconnected, the background turns to a warning color.

### Diagnostics in the Editor

Agents publish code review findings that appear as native VS Code squiggles — the same wavy underlines used by language tools.

- Error findings: red squiggles
- Warnings: yellow squiggles
- Info: blue squiggles
- Hints: subtle dots

Each diagnostic shows the agent's message in the Problems panel and on hover. The source field identifies the publishing agent.

**Lightbulb code actions** — when text is selected in the editor:

| Action | What It Does |
|--------|-------------|
| **Add Metateam Diagnostic** | Publish a diagnostic at the selection. Prompts for severity and message. Selected text is included as context. |
| **Clear Metateam Diagnostic** | Remove Metateam diagnostics overlapping the selection. Only appears when overlapping diagnostics exist. |

Diagnostics stay tied to the publishing agent. When an agent is released, its diagnostics are automatically removed. Diagnostics survive reconnection.

### Debug Notifications

When an agent controls the debugger, the extension displays runtime events as toast notifications:

| Event | Example Notification |
|-------|---------------------|
| Session started | "Debug session started — Debug test-app.js" |
| Session ended | "Debug session ended — Debug test-app.js" |
| Breakpoint hit | "Debug breakpoint hit — test-app.js:8" |
| Exception caught | "Debug exception — test-app.js:9 — Error: Division by zero" |
| Pause | "Debug paused — test-app.js:15" |

### Command Palette

All extension commands via `Cmd+Shift+P` / `Ctrl+Shift+P`:

| Command | Action |
|---------|--------|
| `Metateam: Open Overview` | Open the Overview panel |
| `Metateam: Open Conversation` | Open conversation for an agent |
| `Metateam: Summon Agent` | Prompt for persona name and summon |
| `Metateam: Release Agent` | Pick an agent to release |
| `Metateam: Reset Agent` | Pick an agent to reset |
| `Metateam: Toggle Silence` | Toggle crew notification silence |
| `Metateam: Toggle Scheduler` | Toggle the scheduler on/off |
| `Metateam: Set Watchdog` | Configure the watchdog threshold |
| `Metateam: Clear Agent Diagnostics` | Clear diagnostics for a specific agent |
| `Metateam: Clear All Diagnostics` | Clear all Metateam diagnostics (with confirmation) |
| `Metateam: Add Diagnostic` | Add a diagnostic at the current selection |
| `Metateam: Clear Diagnostic` | Clear diagnostics at the current selection |
| `Metateam: Show Workspace Context` | Show the current IDE context snapshot |

---

## For Agents

This section covers the `metateam ide` CLI commands. These are primarily run by agents in their terminals, or manually for diagnostics and recovery.

### `metateam ide context`

Prints the current IDE snapshot for the connected workspace: active editor file, cursor, language, dirty state, visible range, open tabs, error and warning counts, git branch, active terminal, focus area, and workspace folders.

```
$ metateam ide context
```

Use `--diff` when only changes since the last check are needed:

```
$ metateam ide context --diff
```

Notes:

- `--diff` is intended for compact lead-agent workflows. Outside that flow it may produce no output.
- If no IDE is connected, the command reports that no IDE is connected.

### `metateam ide install` and `metateam ide uninstall`

Install or remove the Metateam extension through the local editor CLI.

VS Code:

```
$ metateam ide install
$ metateam ide uninstall
```

Cursor:

```
$ metateam ide install --cursor
$ metateam ide uninstall --cursor
```

Notes:

- These commands require the `code` or `cursor` command-line tool to be available in `PATH`.
- Reload the editor after installation.

### `metateam ide diagnostics`

Agents publish code review findings directly into the editor as native squiggles.

| Command | Use |
|---|---|
| `publish` | Publish one diagnostic finding |
| `list` | List currently published diagnostics |
| `clear` | Clear diagnostics for the current agent, a named agent, or all agents depending on context |
| `clear-all` | Clear all published diagnostics explicitly |

Publish a finding:

```
$ metateam ide diagnostics publish \
  --path /workspace/src/app.ts \
  --line 42 \
  --severity warning \
  --message "Missing null check before reading profile.name" \
  --code review/null-check
```

Optional range and source-text fields: `--column`, `--end-line`, `--end-column`, `--text`.

List all findings:

```
$ metateam ide diagnostics list
```

Filter by file:

```
$ metateam ide diagnostics list --file /workspace/src/app.ts
```

Filter by agent source:

```
$ metateam ide diagnostics list --source <agent>
```

Clear the current agent's diagnostics:

```
$ metateam ide diagnostics clear
```

Clear one agent explicitly:

```
$ metateam ide diagnostics clear --source <agent>
```

Clear everything:

```
$ metateam ide diagnostics clear-all
```

Notes:

- `publish` requires agent context — the diagnostics are tied to the current agent identity.
- `list` works from any terminal inside the crew workspace.
- `--source` accepts an agent name. The stamped form `metateam/<agent>` also works.
- `clear` is context-sensitive: inside an agent session it clears that agent's diagnostics; outside agent context it clears all diagnostics.
- When acting manually, prefer `clear-all` or `clear --source <agent>` so the scope is obvious.
- When no findings exist, `list` prints `No diagnostics found.`

### `metateam ide lsp`

Agents use LSP commands to query VS Code's warm language server (rust-analyzer, TypeScript, C# Dev Kit, etc.) with zero cold start. These commands route through the communicator relay to VS Code's built-in provider APIs. No CDP session needed.

All commands use 1-based line and character numbers. Position arguments accept both separate (`file line col`) and colon-separated (`file:line:col`) formats. Multiple locations can be queried in one call.

```
# These are equivalent:
$ metateam ide lsp references src/main.rs 42 5
$ metateam ide lsp references src/main.rs:42:5
$ metateam ide lsp references src/main.rs:42     # column defaults to 1

# Batch query — multiple locations in one call:
$ metateam ide lsp references src/main.rs:42:5 src/crew/mod.rs:15:12

# Multi-file for file-only commands:
$ metateam ide lsp symbols src/main.rs src/crew/mod.rs
```

#### Navigation

Go to definition:

```
$ metateam ide lsp definition src/main.rs:42
  src/crew/communicator/server.rs:118:5
```

Find all references:

```
$ metateam ide lsp references src/main.rs:42
  src/main.rs:42:8
  src/crew/mod.rs:15:12
  src/commands/crew.rs:88:20
```

Other navigation commands follow the same pattern:

| Command | Use |
|---|---|
| `definition` | Go to definition |
| `type-definition` | Go to the type of a variable |
| `declaration` | Go to declaration |
| `references` | Find all references |
| `implementations` | Find trait/interface implementations |

All accept `<file> <line> [column]` or `<file:line:col>`.

#### Info

Get type signature and documentation:

```
$ metateam ide lsp hover src/main.rs 42
```

Function parameter hints at a call site:

```
$ metateam ide lsp signature-help src/main.rs 42 15 --trigger "("
```

Available completions:

```
$ metateam ide lsp completions src/main.rs 42 --trigger "." --limit 25
```

Inferred types and parameter names in a line range:

```
$ metateam ide lsp inlay-hints src/main.rs 40 --end-line 60
```

#### Structure

Hierarchical symbol tree for a file:

```
$ metateam ide lsp symbols src/main.rs
```

Search symbols by name across the workspace:

```
$ metateam ide lsp workspace-symbols "SummaryWorker"
```

#### Call and Type Hierarchy

Who calls this function:

```
$ metateam ide lsp incoming-calls src/server.rs 118
```

What does this function call:

```
$ metateam ide lsp outgoing-calls src/server.rs 118
```

Parent and child types:

```
$ metateam ide lsp supertypes src/trait.rs 10
$ metateam ide lsp subtypes src/trait.rs 10
```

#### Refactoring

Preview a rename across files without applying:

```
$ metateam ide lsp rename-preview --new-name "new_name" src/main.rs 42
```

Available quick fixes and refactorings:

```
$ metateam ide lsp code-actions src/main.rs 42 --kind quickfix
```

The `--kind` filter accepts `quickfix`, `refactor`, or `source`.

#### Formatting

Format an entire file (returns a unified diff):

```
$ metateam ide lsp format-document src/main.rs
```

Format a range:

```
$ metateam ide lsp format-range src/main.rs 10 1 --end-line 20 --end-character 1
```

#### Diagnostics from Language Servers

Query VS Code's full diagnostic collection across all active LSPs:

```
$ metateam ide lsp diagnostics
```

Per-file diagnostics (opens the file in VS Code to trigger LSP analysis):

```
$ metateam ide lsp diagnostics src/main.rs
```

Filter by minimum severity:

```
$ metateam ide lsp diagnostics --severity warning
```

Notes:

- All commands support `--json` for structured output. Default is greppable text (`path:line:character` format).
- LSP availability depends on installed VS Code extensions: rust-analyzer for Rust, ms-dotnettools.csharp for C#, TypeScript is built-in.
- Hierarchy commands (incoming-calls, outgoing-calls, supertypes, subtypes) use single-shot prepare+provide internally — no cache management needed.
- `code-actions` uses a range, not a point position. Column defaults to the start of line.
- `format-range` uses named flags (`--end-line`, `--end-character`) for the end position.
- Per-file `lsp diagnostics` includes a poll loop (up to 5s) because some LSPs like C# Dev Kit need time after the file is opened.

### `metateam ide debug`

Agents use debug commands to control a live VS Code debug session: start a launch configuration, manage breakpoints, step through code, inspect variables, and subscribe to debug notifications.

| Command | Use |
|---|---|
| `start` | Start a debug session, optionally by launch configuration name |
| `stop` | Stop the active debug session |
| `breakpoint set` | Set a breakpoint by file and line |
| `breakpoint remove` | Remove a breakpoint by file and line |
| `breakpoint list` | List current breakpoints |
| `step-into` | Step into a function |
| `step-over` | Step over the current line |
| `step-out` | Step out of the current frame |
| `continue` | Resume execution |
| `evaluate` | Evaluate an expression at the current stop point |
| `variables` | List variables at the current stop point |
| `stack` | Show the current call stack |
| `state` | Show the current debug state |
| `register` | Register the current agent for debug notifications |
| `unregister` | Stop sending debug notifications to the current agent |

Start a named launch configuration:

```
$ metateam ide debug start --config "Debug API"
```

Stop the active session:

```
$ metateam ide debug stop
```

Set and remove breakpoints:

```
$ metateam ide debug breakpoint set src/server.ts 88
$ metateam ide debug breakpoint remove src/server.ts 88
```

List breakpoints:

```
$ metateam ide debug breakpoint list
```

Step and continue:

```
$ metateam ide debug step-into
$ metateam ide debug step-over
$ metateam ide debug step-out
$ metateam ide debug continue
```

Inspect the paused program:

```
$ metateam ide debug state
$ metateam ide debug stack
$ metateam ide debug variables
$ metateam ide debug evaluate "user.profile.email"
```

Register for debug notifications:

```
$ metateam ide debug register
```

Stop notifications:

```
$ metateam ide debug unregister
```

Notes:

- `start`, `stop`, `breakpoint`, `step`, `continue`, `evaluate`, `variables`, `stack`, and `state` work from any terminal inside the crew workspace.
- `register` and `unregister` require agent context because notifications are attached to the current agent identity.
- State-inspection commands return structured JSON. When no session is active:

```json
{
  "state": "no_session"
}
```

### `metateam ide devtools`

Agents use devtools commands to inspect and interact with VS Code webviews, browser pages, and the extension host process through the Chrome DevTools Protocol (CDP).

#### Prerequisites

VS Code must be running with CDP enabled. The easiest way is the restart command:

```
$ metateam ide devtools restart
```

The restart command checks for multiple VS Code windows (refuses if more than one is open), quits VS Code completely, and relaunches a fresh process with `--remote-debugging-port=9222`. macOS only; other platforms print a manual launch command.

To enable CDP manually, fully quit VS Code first (`Cmd+Q`), then launch from the terminal:

```
$ open -a "Visual Studio Code" --args --remote-debugging-port=9222
```

The CDP flag is a process-level Electron setting and only takes effect on a fresh process. It cannot be added to an already-running VS Code instance.

#### Tabs and Sessions

List open VS Code tabs:

```
$ metateam ide devtools tabs
   #  TYPE      TITLE                       GROUP  ACTIVE
------------------------------------------------------------------------
   1  webview   data (crew lead)                1
   2  webview   carmack (developer)             1
   3  webview   ncc Overview                    1  *
   4  editor    ide.md                          1
```

Open a CDP session to a webview tab:

```
$ metateam ide devtools session open --tab 2
```

Open by title or URL substring:

```
$ metateam ide devtools session open "ncc Overview"
```

If the query matches multiple targets, the command lists matches and refuses. Close the session when done:

```
$ metateam ide devtools session close
```

Show current session info:

```
$ metateam ide devtools session show
```

List raw CDP targets (lower-level than `tabs`):

```
$ metateam ide devtools target list
```

**Sidebar inspection:** The sidebar WebviewView only appears as a CDP target when visible. Force it visible first, then attach:

```
$ metateam ide devtools command run "metateam.crew.focus"
$ metateam ide devtools session open "webviewView"
$ metateam ide devtools css computed -s ".sidebar-line-title" font-size font-weight
font-size: 13px
font-weight: 600
```

**Auto-session:** If exactly one CDP target exists, devtools commands auto-attach without an explicit `session open`. If multiple targets exist, the command lists them and asks you to choose.

#### DOM Inspection

Find elements by CSS selector:

```
$ metateam ide devtools dom find "#overview-feed"
- node: 34476
  tag: main#overview-feed.records.unified-feed
  attrs: [aria-live="polite"]
  children: [408 not expanded]
```

Expand a subtree (by selector or node ID):

```
$ metateam ide devtools dom tree "#overview-feed" --depth 1
$ metateam ide devtools dom tree --node 34476 --depth 1
```

Get the outer HTML:

```
$ metateam ide devtools dom html "#overview-feed"
$ metateam ide devtools dom html --node 34476
```

Set an attribute:

```
$ metateam ide devtools dom attr set --node 34476 --name "data-test" --value "ok"
```

All DOM commands work on both main-page and iframe targets. For iframe targets (VS Code webviews), the commands automatically route into the inner child frame where the actual content lives.

#### CSS Inspection

CSS commands accept a selector (`-s`) or a node ID (`--node`). Selectors resolve to the first matching element in document order.

Get computed values (single or multiple properties):

```
$ metateam ide devtools css computed -s ".header h1" font-size
font-size: 13px

$ metateam ide devtools css computed -s ".header h1" font-size font-family font-weight
font-family: -apple-system, "system-ui", sans-serif
font-size: 13px
font-weight: 650

$ metateam ide devtools css computed --node 34476 display
display: flex
```

Get all computed styles:

```
$ metateam ide devtools css computed -s ".records"
```

Get matched CSS rules (authored rules only by default):

```
$ metateam ide devtools css rules -s ".records"
  .records (regular, style-sheet-11183-38100) {
    flex: 1;
    display: flex;
    flex-direction: column;
    ...
  }
```

Include user-agent rules with `--all`:

```
$ metateam ide devtools css rules -s ".records" --all
```

Edit a style declaration:

```
$ metateam ide devtools css edit --style-sheet <id> --range <start:end> --text "color: red;"
```

#### JavaScript Evaluation

Evaluate an expression in the target page or webview:

```
$ metateam ide devtools js eval "document.title"
ncc Overview
```

```
$ metateam ide devtools js eval "document.querySelectorAll('*').length"
3041
```

For iframe targets, evaluation runs in the inner child frame context automatically. Exceptions return the error and stack trace.

Inspect a non-serializable object by its handle:

```
$ metateam ide devtools js props --object <objectId>
```

#### Console Capture

Start capturing console output from the target:

```
$ metateam ide devtools console start
{ "capture_id": 1 }
```

Read captured entries with cursor-based pagination:

```
$ metateam ide devtools console read
SEQ    LEVEL TEXT
1      log   devtools test message
--- cursor: 1
```

Advance the cursor:

```
$ metateam ide devtools console read --after-seq 1
```

Stop the capture:

```
$ metateam ide devtools console stop --capture 1
```

Captures use a ring buffer with monotonic sequence numbers. Reads are cursor-based — pass `--after-seq N` to get entries after a previous read.

#### Network Capture

Start capturing network requests:

```
$ metateam ide devtools network start
```

Read captured requests:

```
$ metateam ide devtools network read
SEQ    METH STATUS TIME     SIZE     URL
1      GET  200    120ms    4.2kb    https://api.example.com/data
```

Fetch a response body:

```
$ metateam ide devtools network body --capture 1 --request <requestId>
```

Stop:

```
$ metateam ide devtools network stop --capture 1
```

#### DOM Mutation Tracking

Track DOM changes in real time:

```
$ metateam ide devtools dom mutations start
```

Read captured mutations:

```
$ metateam ide devtools dom mutations read --limit 10
SEQ    TYPE         TARGET                         ADD   REM   ATTR
1      childList    main#overview-feed.records.u   1     0
2      childList    main#overview-feed.records.u   0     490
```

Stop:

```
$ metateam ide devtools dom mutations stop --capture 1
```

The default observes all subtree mutations. On iframe targets, the observer is injected into the inner child frame where the content lives.

#### Page Commands

Take a screenshot:

```
$ metateam ide devtools page screenshot
Screenshot saved: /tmp/metateam-screenshot-cdp_1-....png (1449x949) 497kb
```

Save to a specific path:

```
$ metateam ide devtools page screenshot --out /tmp/my-screenshot.png
```

List the frame tree:

```
$ metateam ide devtools page frames
```

Navigate to a URL:

```
$ metateam ide devtools page navigate "https://example.com"
```

Screenshots on iframe targets use a parent-page fallback automatically.

#### Performance and Profiling

Get runtime performance metrics:

```
$ metateam ide devtools perf metrics
METRIC                                   VALUE
JSHeapUsedSize                           69982708
Nodes                                    1011
...
```

Capture a CPU profile:

```
$ metateam ide devtools profile cpu start --duration 5s
Written to: /tmp/metateam-cpu-profile-cdp_1-....cpuprofile
Size: 38826 bytes
Duration: 5018ms
```

Take a heap snapshot:

```
$ metateam ide devtools memory heap snapshot
Written to: /tmp/metateam-heap-cdp_1-....heapsnapshot
Size: 104.8MB
Duration: 1723ms
```

Highlight a DOM node visually:

```
$ metateam ide devtools overlay highlight ".sidebar-card"
$ metateam ide devtools overlay highlight --node 34476
```

The `--duration` flag on capture commands runs the capture for the specified time and returns results in a single response. Without it, use `start` and `stop` separately.

#### Host Inspector

Inspect the VS Code extension host process directly, without CDP:

```
$ metateam ide devtools host eval "process.pid"
44447
```

```
$ metateam ide devtools host eval "process.memoryUsage().heapUsed / 1024 / 1024"
225.6
```

Capture extension host console output:

```
$ metateam ide devtools host console start
$ metateam ide devtools host console read
$ metateam ide devtools host console stop --capture <id>
```

Profile the extension host CPU:

```
$ metateam ide devtools host profile start --duration 3s
```

Take an extension host heap snapshot:

```
$ metateam ide devtools host heap snapshot
```

Host commands use Node.js `inspector.Session` internally — no CDP port needed. They work even when VS Code was not launched with `--remote-debugging-port`.

#### Message Tracing

Capture host-to-webview postMessage traffic:

```
$ metateam ide devtools messages start
$ metateam ide devtools messages read
$ metateam ide devtools messages stop --capture <id>
```

Entries include direction (in/out), message type, and payload size.

#### VS Code Command Execution

Execute any VS Code command programmatically:

```
$ metateam ide devtools command run metateam.openOverview
OK (no return value)
```

Pass arguments for headless execution:

```
$ metateam ide devtools command run metateam.summonAgent --args '{"persona":"holmes"}'
```

List available commands:

```
$ metateam ide devtools command list --filter metateam
25 commands:
  metateam.openOverview
  ...
```

#### Input Simulation

Click an element by CSS selector:

```
$ metateam ide devtools input click "#overview-feed"
```

Click by coordinates:

```
$ metateam ide devtools input click "400,300"
```

Type text into the focused element:

```
$ metateam ide devtools input type "hello world"
```

Send key events:

```
$ metateam ide devtools input key Enter
$ metateam ide devtools input key Escape
$ metateam ide devtools input key Enter --modifiers shift
$ metateam ide devtools input key Tab
```

Scroll:

```
$ metateam ide devtools input scroll --delta-y=-200
```

Notes:

- All capture commands (console, network, mutations, messages, profiles) use the same model: `start` returns a `capture_id`, `read` uses cursor-based pagination with `--after-seq`, `stop` requires the `capture_id`.
- Captures are session-scoped and lease-based. If the agent disconnects or the lease expires, captures are cleaned up automatically.
- `--tab` and title/URL query are mutually exclusive on `session open`.
- The `restart` command refuses when multiple VS Code windows are open. It is macOS-only; other platforms print a manual launch instruction.
- Host inspector commands (`host eval`, `host console`, `host profile`, `host heap`) do not require CDP and work without `--remote-debugging-port`.

---

## Troubleshooting

### Extension does not activate

The workspace must contain a `.crew` directory. Run `metateam crew init` or start the dashboard with `metateam` first.

### Sidebar shows disconnected

The crew dashboard is not running. Start it with `metateam` in the terminal. The extension reconnects automatically.

### `metateam ide install` fails

Check that the editor CLI is available: VS Code uses `code`, Cursor uses `cursor`. If the extension installs successfully but nothing appears, reload the editor window.

### `metateam ide context` says no IDE is connected

Check that the extension is installed, the editor is open on the same workspace, and the crew dashboard is running.

### `publish` or `debug register` fails from a plain shell

Those commands require agent context. They are meant to run from an agent terminal, not an arbitrary shell.

### `clear` removed more diagnostics than expected

`metateam ide diagnostics clear` changes scope based on context. Inside an agent terminal it clears that agent's findings. Outside agent context it clears all findings. Use `clear-all` or `clear --source <agent>` when manual scope control matters.

### `metateam ide debug state` reports `no_session`

No debug session is active in the connected editor. Start one with `metateam ide debug start`.

### Agents appear but conversation panel is empty

The agent may have just been summoned and has no transcript yet. Wait for the agent to produce output. If the panel shows an error, verify the agent's session file is accessible.

### Status bar shows warning color

Metateam is unreachable from the editor. Check that the crew dashboard is running.

### `devtools target list` returns empty

VS Code was not launched with `--remote-debugging-port=9222`. Run `metateam ide devtools restart` (single window required) or quit VS Code and relaunch manually with the flag.

### `devtools session open` returns "no CDP target matched"

The query did not match any target by title or URL substring. Use `devtools tabs` to see available webview tabs and `devtools target list` for raw CDP targets. `--tab N` resolves tabs by probing CDP targets against the tab title — it is more convenient than manual target ID matching but relies on title-based heuristics.

### `devtools session open` returns "ambiguous"

The query matched multiple targets. Use a more specific substring or `--tab N` to pick the exact tab.

### DOM/CSS commands return "Could not find node with given id"

The backendNodeId may be stale (the DOM changed since the last `dom find`). Re-run `dom find` to get fresh node IDs.

### Console or mutation capture shows no entries

For iframe targets (webviews), verify the capture is running in the inner child frame. Use `js eval "console.log('test')"` to confirm the console capture sees logs from the same context. For mutations, verify the DOM is actually changing — `js eval "document.querySelector('#overview-feed')?.children.length"` twice with a delay.

### `devtools restart` refuses

Either multiple VS Code windows are open (close others first) or CDP is already enabled. Check with `devtools target list`.

## See Also

- [CLI Overview](./overview.md)
- [Crew Workflows](./crew-workflows.md) — terminal dashboard crew coordination
- [The Terminal Dashboard](../getting-started/dashboard.md)
- [Debugging and Observability](../ops/debugging.md)