extension-dev

name	extension-dev
description	Build / F5 / debug the cc-connect VSCode extension. Use when you're iterating on src/ or webview/ in this directory and need to know which command to run, how to inspect runtime state, or how to debug specific subsystems (webview rendering, Claude SDK driver, daemon spawn, log tail, IPC over chat.sock).

cc-connect extension dev — operational skill

When to use this

Invoke whenever the task involves:

• editing src/ (extension host TS) or webview/ (React TS) and needing to compile + reload the dev host
• diagnosing why a change didn't appear (build cache vs dev-host reload vs JS bundle staleness)
• understanding which subsystem owns which behavior (sidebar tree, panel webview, Claude runner, log tail, chat.sock client, daemon orchestrator)
• debugging the Claude Agent SDK plumbing without burning subscription quota

For architecture / design rationale, read ../CLAUDE.md and ../docs/vscode-extension-design.md first — this skill is the operational layer.

The dev loop

# From vscode-extension/
bun install              # one-time
bun run compile          # build host TS + webview bundle
bun run watch            # tsc --watch (host only — webview needs manual rebuild)

F5 in VSCode launches the dev host. The bundled launch config (vscode-extension/.vscode/launch.json) auto-runs bun run compile as a pre-launch task and disables user-installed extensions in the dev host (--disable-extensions flag).

Three layers of "did my change land?" — when something looks stale, check in this order:

1. Host TS (src/ → out/extension.js): F5 always rebuilds via the pre-launch task, but Cmd-R reload inside dev host does NOT. Close + reopen the dev host window after host changes.
2. Webview bundle (webview/ → dist/webview/main.js): NOT rebuilt by F5. Re-run bun run compile (or bun run compile:webview) after every TSX change. Then reload the webview view in dev host (close + reopen the panel).
3. Manifest (package.json contributions): adding commands / views / viewsContainers / activationEvents requires a fresh dev host launch. Cmd-R won't pick those up.

Subsystem map

File	Owns
src/extension.ts	activate() — registers commands + providers
src/sidebar/RoomsProvider.ts	Activity-bar tree of rooms
src/panel/RoomPanelProvider.ts	Bottom-panel webview view (single active room)
src/host/daemon.ts	Spawns / stops cc-connect host-bg + chat-daemon
src/host/log_tail.ts	Tails ~/.cc-connect/rooms/<topic>/log.jsonl
src/host/ipc.ts	Sends to chat-daemon over chat.sock
src/host/claude_runner.ts	Drives @anthropic-ai/claude-agent-sdk
src/host/mention.ts	Decides which messages wake Claude
webview/main.tsx	React root + postMessage bridge
webview/Chat.tsx	Chat panel (input + scrollback)
webview/Claude.tsx	Claude panel (typed event stream)
webview/processClaude.ts	SDK events → typed UI blocks
webview/MarkdownContent.tsx	react-markdown wrapper
webview/ToolCardBody.tsx	Diff view + expandable result
webview/highlightMentions.tsx	@-token regex highlighter
webview/useStickyScroll.ts	Sticky-bottom scroll hook

Smoke tests (zero quota)

bun run probe:sdk        # confirms SDK + OAuth + ~/.local/bin/claude path; aborts at init event

Aborts on the first system:init event so no model call lands. Use this to validate claude_runner.ts changes before doing a full end-to-end test against a real Room.

Inspecting runtime state

# Active daemons (per-machine)
~/.local/bin/cc-connect host-bg list
~/.local/bin/cc-connect chat-daemon list

# Per-Room runtime state
ls ~/.cc-connect/rooms/<topic>/
#   log.jsonl       — message log (the tail watches this)
#   chat.sock       — marker file pointing at the actual /tmp/cc-*.sock
#   chat-daemon.pid — JSON: { pid, topic, ticket, started_at, relay }
#   files/          — dropped blobs (iroh-blobs MemStore copy)

# Hook log (per-machine)
tail -f ~/.cc-connect/hook.log

# Doctor
~/.local/bin/cc-connect doctor

The dev host's "Webview Developer Tools" (right-click webview → Inspect, or Cmd-Shift-I) gives you Chrome DevTools for the React app — use it to inspect post-message traffic, React state, CSS.

Common pitfalls

• "My React change didn't show up" → run bun run compile again, then reload the panel view (close + reopen). Webview bundle isn't rebuilt by F5 alone.
• "Activity Bar icon doesn't show" → manifest change requires full dev host restart. Also confirm View → Appearance → Activity Bar is enabled in the dev host (it inherits the user's setting).
• "Tool calls fail with ZodError" → you tried to use canUseTool instead of permissionMode: 'bypassPermissions'. Some tool paths bypass canUseTool and crash. Stick with bypass for v0; per-tool approval UI is deferred.
• "Send fails with no chat.sock marker" → no chat-daemon running for that topic. Either cc-connect: Start Room (mints a new one) or cc-connect: Join Room… (joins existing) — both spawn chat-daemon as part of the flow.
• "Claude doesn't wake on @<my-nick>" → that's the design (D1). Use @<my-nick>-cc to address your own AI explicitly.
• "Webview is blank after switching rooms" → RoomPanelProvider regenerates HTML on setRoom. If bun build produced a broken bundle, you'll see a blank screen. Check the webview DevTools console for the actual JS error.

When the design needs to change

If you're touching the wire format, hook contract, or webview trust boundary, stop and read ../docs/vscode-extension-design.md §2.1 (Isolation contract) and §9 (Validation results). Anything that loosens the boundary needs a paired update to the design doc + a smoke test.

Related references

• vitest-dev/vscode/CLAUDE.md — well-structured CLAUDE.md from a popular VSCode extension; good template (license: MIT)
• sugyan/claude-code-webui — MIT React UI for Claude CLI streaming; inspired our processClaude.ts architecture (already attributed in the source)