Visual Studio Code

Purpose

Rick's desktop and laptop daily driver for working in the /Claude/ vault. Replaces Termius on Mac (Termius is iPad/mobile only as of 2026-04-15). VS Code is where the grid N agent-grid launcher fires, where vault files are edited, and where Claude Code sessions run side-by-side in a multi-pane layout.

How we use it

• Agent grid launcher (grid N) — six Claude Code sessions launched in parallel, one per executive agent, each pre-scoped to that agent's sessions/{agent.id}/ cwd for memory isolation. See full details below.
• Vault file browsing — the Explorer sidebar surfaces the /Claude/ 4-bucket architecture (system/, operations/, knowledge/, content/) for quick navigation while working in a chat pane.
• Markdown preview — Cmd+Shift+V renders vault markdown similar to Obsidian's reading mode.
• Git integration — the Source Control sidebar is the audit trail view for vault changes.
• Clickable file paths and obsidian:// links — VS Code's integrated terminal supports both natively. Cmd+click a path in terminal output to open the file; Cmd+click an obsidian:// URL to launch Obsidian directly.
• Claude Code VS Code extension — surfaces a Sessions panel on the right side for resume-previous-session workflows.

Setup & credentials

No credentials. Install via Homebrew or direct download. Shell integration (the code command on PATH) should be installed via VS Code's own "Shell Command: Install 'code' command in PATH" Command Palette entry — the grid zsh function depends on it.

The grid N agent-grid launcher

Rick's canonical way to open VS Code on the vault is the grid zsh function in ~/.zshrc. As of 2026-04-21 it delegates named presets and custom invocations to a dedicated launcher script, while still supporting the legacy numeric sizes:

grid() {
  local arg="${1:-6}"
  case "$arg" in
    4|6|8)
      local ws="$HOME/Claude/.vscode/grid-${arg}.code-workspace"
      if [[ ! -f "$ws" ]]; then
        echo "grid: no workspace for size '${arg}'." >&2
        return 1
      fi
      code "$ws"
      ;;
    *)
      "$HOME/Claude/scripts/agents/grid-launch.sh" "$@"
      ;;
  esac
}

The delegated launcher at /Claude/scripts/agents/grid-launch.sh generates a fresh .code-workspace file in /tmp/ per invocation (with $$ PID suffix) and opens it via code -n, so multiple simultaneous windows don't collide.

Named presets (canonical since 2026-04-21)

Command	Panes	Agents
grid execs	6	Chief of Staff, Project Manager, CRO, CMO, COO, CDO
grid dev	8	code.platform, revenue.os, mining.mind, qa.testing, qa.visuals, qa.dataquality, qa.applications, documentation.engineering
grid ops	4	sop.manager, legal.exec, security.ops, financial.research
grid rev	2	sales.ops, customer.success
grid mktg	1	category.positioning
grid qa	4	qa.testing, qa.visuals, qa.dataquality, qa.applications
grid council	3	Chief of Staff, Project Manager, qa.testing (add rotating peer via custom)
grid custom <csv>	N	Ad-hoc, comma-separated agent IDs (min 2)
grid list	—	Show available presets

Convention: execs launch once via grid execs; department team grids exclude their manager. Running both grid execs and grid dev with CDO in both would open two live Claude Code sessions for the same agent and race on memory-notes.md at session end. The preset definitions enforce this — grid dev, grid ops, grid rev, grid mktg each drop their exec.

Legacy numeric variants (still supported)

Variant	Grid	Agents
grid 4	2x2	Chief of Staff, Project Manager, CDO, CMO
grid 6	2x3	Chief of Staff, Project Manager, CMO, CDO, COO, CRO
grid 8	2x4	Chief of Staff, Project Manager, CMO, CDO, COO, CRO, QA Testing, SOP Manager

These open the static .code-workspace files at /Claude/.vscode/grid-{4,6,8}.code-workspace. Kept for backward compatibility; for new work prefer the named presets.

Persistent sessions is disabled across both modes because it produces zombie terminals on reload when paired with type: "process" task terminals — see the "Persistent sessions: why it's off" section below.

Why each variant is per-monitor-size

Different physical monitors benefit from different grid densities. Rather than one layout that cramps on a laptop or wastes space on a 27" external, pick the grid size that matches the current monitor. All three variants start with the same top-left agent (Chief of Staff) so muscle memory transfers between them.

Why claude directly, not aifactory-menu

Inside VS Code, tasks bypass the aifactory-menu launcher and spawn claude directly via type: "process" tasks. This is a deliberate VS Code carve-out from the menu-unification rule. Reasons: 1. Running the menu as a task command drops into a non-interactive subshell where the menu's read -k1 breaks 2. VS Code's Python extension injects source .venv/activate into new terminals, colliding with the menu's input handling 3. The whole point of grid N is "one command → N agent sessions ready" — routing through the menu adds 6 extra keystrokes per launch and breaks the value proposition

Manual terminals Rick opens inside VS Code (Terminal → New Terminal) also skip the menu, via a [[ "$TERM_PROGRAM" != "vscode" ]] guard on the source aifactory-menu line in ~/.zshrc. External terminals (Termius, Terminal.app, SSH) still run the menu unchanged — the guard's condition doesn't trip there.

Required settings in .vscode/settings.json

Three vault-wide settings support the grid workflow:

"editor.accessibilitySupport": "off",
"terminal.integrated.enablePersistentSessions": false,
"task.allowAutomaticTasks": "on",
"python.terminal.activateEnvironment": false,
"python.terminal.activateEnvInCurrentTerminal": false,

• editor.accessibilitySupport: "off" — critical. When this is "on" (Screen Reader Optimized mode), VS Code's terminal strips ANSI styling, making Claude Code's inline code spans render as blank text. See feedback_vs_code_accessibility_gotcha.md in chief.staff memory.
• terminal.integrated.enablePersistentSessions: false — deliberately off. See the "Persistent sessions: why it's off" section below.
• task.allowAutomaticTasks: "on" — skips the "Allow automatic tasks?" prompt so grid tasks fire silently on folder open.
• python.terminal.activate* — disables the Python extension's venv auto-injection that otherwise collides with terminal startup.

Persistent sessions: why it's off

VS Code's terminal.integrated.enablePersistentSessions is intended to revive interactive shell terminals across window reloads. It does not play well with type: "process" task terminals for several reasons:

1. Double-firing on reload: when the workspace reopens, runOn: "folderOpen" fires the 6 (or 4/8) tasks again AND persistent sessions tries to revive the previous task terminals. Result: 12 tabs where you expected 6, half of them zombie-broken.
2. Process revival semantics don't apply to Claude Code: each claude process has its own conversation state that's not designed to be serialized and revived by VS Code. When persistent sessions "revives" a grid pane, you can end up with a broken shell or a session pointing at the wrong history.
3. Editor group layout and terminal revival are separate mechanisms: even if we could revive the terminals cleanly, VS Code may not restore them into the same editor groups you arranged. The 2x3 layout would be lost anyway in many cases.

Accepted tradeoff: each grid N launch opens the workspace fresh with all panes stacked in a single editor group. You drag them into the target 2x2 / 2x3 / 2x4 grid manually (~30 seconds with muscle memory). In exchange you get deterministic launches, zero zombies, and no arcane reload rituals.

Followup opportunity: a VS Code extension like "Terminals Manager" (or similar workspace-layout savers) could script the grid arrangement on startup, eliminating the manual re-arrange. Parked in Rick's inbox under the VS Code section — pick up when convenient.

Per-workspace settings

Each grid-N.code-workspace file overrides one additional setting inline:

"settings": {
  "terminal.integrated.defaultLocation": "editor"
}

This sends task terminals to the editor area (not the bottom panel), so they can be arranged as a full 2D grid. Scoped to the workspace only, so opening the folder directly keeps normal panel-terminal behavior.

Editor layout: arranging the grid

VS Code doesn't ship a native 2x3 or 2x4 preset — those layouts are built by dragging tabs to edges. Mental model:

• Each tab lives inside an editor group (a cell in the grid)
• To create a new cell, drag a tab to an edge of an existing cell
• Right edge → creates a new column
• Bottom edge → creates a new row
• Center of the cell → stacks tabs inside the same cell (don't want this for the grid)

While dragging, VS Code shows a blue highlight. A narrow strip at the edge = split; a big rectangle filling the cell = stack. Aim for the strip.

Building a 2x3 from a single-group, 6-tab starting state

1. Drag tab 2 to the right edge of the editor area → 2 columns
2. Drag tab 3 to the right edge of column 2 → 3 columns
3. Drag one tab in each column to the bottom edge of that same column → each column splits into 2 rows
4. Result: 3 columns × 2 rows = 6 cells, each with one Claude Code session

Building a 2x2 from grid 4

View → Editor Layout → Grid (2x2). One click — VS Code ships the preset.

Building a 2x4 from grid 8

Same technique as 2x3, but split into 4 columns first, then split each column into 2 rows.

Equal column/row widths

After arranging, Command Palette → "View: Reset Editor Group Sizes" evens all cells in both dimensions. There's also "View: Even Editor Group Widths" (horizontal only) and "View: Even Editor Group Heights" (vertical only) if one axis already looks right. No default keybinding — can be bound manually if used often.

Sidebar recommendations

The 6-pane grid competes for screen real estate with sidebars. Recommended defaults:

• Explorer (left sidebar) — open and narrow (~180px). Toggle with Cmd+B. Useful for browsing vault files while in a chat pane. The narrow width barely eats into the grid.
• Sessions panel (right sidebar, from Claude Code VS Code extension) — keep open if you actively use Resume-previous-session; close otherwise via the panel's toggle or "View: Toggle Auxiliary Bar". Rick uses Resume frequently, so keep it open.
• Both closed gives maximum terminal space (~33% horizontal × 50% vertical per pane in 2x3) — use on smaller monitors or when you need every pixel.

Sidebar state (open/closed, width) is saved per-workspace by VS Code independently of terminal persistence, so your sidebar preferences survive grid N relaunches even with persistent sessions off. Adjust once, and the next launch opens with the same sidebar configuration.

Resume-previous-session and grid panes

The Claude Code VS Code extension's Sessions panel lists past sessions. Clicking Resume opens that session in a new editor tab — separate from any terminal-spawned claude in the grid.

Important: Claude Code sessions are not multi-client safe. If you Resume a session while another copy of it is still running in a grid pane, you'd have two processes both reading from and appending to the same session history file. Avoid doing this — close the grid pane first (or let it exit naturally) before Resuming the same session elsewhere. The Sessions panel is intended for sessions that are not currently open.

Setup on a new Mac (MacBook Air, other desktop, etc.)

Rick's desktop (Mac Studio) is the canonical setup. When bringing a second machine online — for example, the MacBook Air he travels with — follow these steps in order. The checklist assumes Obsidian Sync has already delivered the /Claude/ vault to the new machine (which it does automatically for devices logged into Rick's info@ecomonetize.com Obsidian account).

1. Install VS Code

Download from https://code.visualstudio.com/ or via Homebrew: brew install --cask visual-studio-code. Launch once to let macOS accept the Gatekeeper prompt.

2. Install the code shell command

Inside VS Code: Cmd+Shift+P → "Shell Command: Install 'code' command in PATH". This adds code to /usr/local/bin/ (or /opt/homebrew/bin/ on Apple Silicon Macs), which the grid zsh function depends on. Verify with which code in a new terminal — should return a real path.

3. Install Claude Code CLI

Claude Code is distributed via npm. On the new machine: npm install -g @anthropic-ai/claude-code (or whatever the current install command is — check https://docs.anthropic.com/en/docs/claude-code). Verify with which claude. If npm isn't installed, install Node.js first via brew install node or NVM.

4. Copy the aifactory-menu script

The menu lives at ~/.local/bin/aifactory-menu on the desktop. It's NOT in the /Claude/ vault (it's machine-local), so it needs to be copied manually:

# On the desktop Mac Studio, in a plain shell:
cat ~/.local/bin/aifactory-menu
# Copy the output.

# On the MacBook Air:
mkdir -p ~/.local/bin
# Paste the content into ~/.local/bin/aifactory-menu via a text editor, then:
chmod +x ~/.local/bin/aifactory-menu

Or, if you prefer file-based copy: use AirDrop, iCloud Drive, or scp to move the file directly between machines.

5. Update ~/.zshrc on the new machine

Add three blocks to ~/.zshrc (or merge with existing content if these lines already exist):

# Put ~/.local/bin on PATH so aifactory-menu is found
export PATH="$HOME/.local/bin:$PATH"

# Source aifactory-menu, but skip inside VS Code integrated terminal
# (VS Code uses `grid N` + direct claude instead of the menu)
[[ "$TERM_PROGRAM" != "vscode" ]] && source "$HOME/.local/bin/aifactory-menu"

# eco|monetize™ /Claude/ vault grid launcher
# Usage: grid [4|6|8]              — legacy static workspaces
#        grid <preset>             — named preset (execs, dev, ops, rev, mktg, qa, council)
#        grid custom <csv>         — ad-hoc comma-separated agent IDs
#        grid list                 — show presets
#        grid                      — defaults to 6 panes (legacy)
grid() {
  local arg="${1:-6}"
  case "$arg" in
    4|6|8)
      local ws="$HOME/Claude/.vscode/grid-${arg}.code-workspace"
      if [[ ! -f "$ws" ]]; then
        echo "grid: no workspace for size '${arg}'." >&2
        return 1
      fi
      code "$ws"
      ;;
    *)
      "$HOME/Claude/scripts/agents/grid-launch.sh" "$@"
      ;;
  esac
}

Open a new terminal (or source ~/.zshrc in an existing one) so the changes take effect.

6. Confirm the vault is synced

ls ~/Claude/.vscode/grid-*.code-workspace
# Should list grid-4.code-workspace, grid-6.code-workspace, grid-8.code-workspace

If these files are missing, Obsidian Sync hasn't finished delivering the vault — wait for the sync indicator in Obsidian to show "Fully synced".

7. Disable Screen Reader Optimized mode (belt and suspenders)

First time you open VS Code on the new machine, the accessibility setting MAY have defaulted to "on" (depends on system accessibility state). The vault's .vscode/settings.json already sets editor.accessibilitySupport: "off" so once you open the vault workspace this gets applied automatically — but if you see garbled terminal output before opening a vault workspace, fix it immediately per feedback_vs_code_accessibility_gotcha.md in chief.staff memory.

8. Test grid N

Open a plain shell (Terminal.app, or a VS Code terminal) and run:

grid 6

A new VS Code window should open with 6 Claude Code sessions stacking as tabs in the editor area. If they land in the bottom panel instead of the editor area, something in .vscode/settings.json didn't sync — re-check step 6.

9. One-time grid arrangement

Drag the 6 tabs into your preferred grid layout (2x3 for grid 6, 2x2 for grid 4, 2x4 for grid 8). Use the drag-to-edge technique documented above in the "Editor layout" section. Persistent sessions is off, so you'll re-arrange every launch — ~30 seconds with muscle memory. The followup to eliminate this manual step (a Terminals Manager extension) is parked in /Claude/inbox/inbox.md.

10. Laptop-specific considerations

• MacBook Air screen size: grid 4 (2x2) or grid 6 (2x3) are the practical options; grid 8 will feel cramped on a 13" display.
• Battery: each claude pane is a live process talking to Anthropic's API. Six sessions idle is modest power draw, but if you're on battery and not actively using all six, consider grid 4 to save cycles.
• External monitor workflow: when docked to an external display, you can switch to grid 8 by closing the current grid window and running grid 8 from a shell — the new workspace is a different file, so its layout doesn't interfere with grid 4 or grid 6.

Owner

chief.staff — as the meta-agent that owns Rick's executive tooling and operating system. The grid N launcher and all .vscode/ config are maintained here. Any changes to grid-N workspace files or the grid zsh function need chief.staff oversight.

Related

• [[claude-code]] — the CLI that runs in each grid pane
• [[obsidian]] — the other half of Rick's vault workflow; VS Code complements Obsidian's read/edit modes
• [[claude-anthropic]] — the model provider
• /Claude/.vscode/grid-{4,6,8}.code-workspace — the three workspace files
• /Claude/.vscode/settings.json — vault-wide VS Code config
• ~/.zshrc — grid function and VS Code aifactory-menu guard
• [[vscode-claude-obsidian-setup]] — detailed setup playbook (at /Claude/knowledge/playbooks/)

Notes

• The .zshrc guard ([[ "$TERM_PROGRAM" != "vscode" ]] && source aifactory-menu) is scoped specifically to VS Code's integrated terminal. VS Code sets TERM_PROGRAM=vscode automatically — no additional config needed on VS Code's side.
• First-launch quirk: persistent sessions may revive broken terminal tabs from an earlier failed launch. One-time cleanup: close any zombie tabs, kill any stray panel terminals, arrange the real grid, reload once. From then on, launches are clean.
• Screen Reader Optimized mode is the #1 thing to check if inline code spans render blank in a VS Code terminal. See feedback_vs_code_accessibility_gotcha.md for the diagnosis and one-line fix.
• grid (the zsh function) vs claude (the CLI) — deliberately different names. claude is reserved for the Claude Code CLI binary; grid is the VS Code vault launcher. Do not conflate.