Skip to content

How to set up VS Code + Claude Code + Obsidian for the eco|monetize™ operating system

Your primary desktop stack on Mac. This playbook assumes: VS Code already installed, Claude Code already installed, Obsidian already installed and the Claude vault opened at least once at /Users/rhartley/Claude/. If any of those aren't true, install them first (VS Code from code.visualstudio.com, Claude Code per Anthropic's docs, Obsidian from obsidian.md).

When to use this playbook

  • First time wiring VS Code into the operating system stack
  • Switching from Termius or another terminal to VS Code as your Mac daily driver
  • Onboarding a new Mac (device migration, new team member in the future)
  • Troubleshooting when clickable file paths, obsidian:// links, or parallel Claude Code sessions aren't working as expected

Prerequisites

  • macOS (Apple Silicon or Intel, though Apple Silicon strongly preferred)
  • /Claude/ vault exists at /Users/rhartley/Claude/
  • Rick's Claude subscription + Claude Code authentication already set up
  • 1Password CLI (op) installed and authenticated (for any scripts that resolve secrets)

Phase 1 — Open the vault as a workspace in VS Code (2 min)

  1. Launch VS Code
  2. File → Open Folder… (or Cmd+O)
  3. Navigate to /Users/rhartley/Claude/
  4. Click Open
  5. VS Code may ask "Do you trust the authors of the files in this folder?" — click Yes, I trust the authors. This enables language services, debuggers, and extensions for vault content.
  6. The Explorer sidebar on the left now shows the full vault tree. You should see CLAUDE.md, inbox/, knowledge/, missions/, operations/, sessions/, system/, etc.
  7. Tip: pin the vault to the recent workspaces list for quick reopening — VS Code remembers recent folders in File → Open Recent.

Phase 2 — Install the essential extensions (10 min)

Open the Extensions sidebar: Cmd+Shift+X (or click the Extensions icon in the left rail).

Shortcut: the vault's .vscode/extensions.json already lists all recommended extensions. On first open of the /Claude/ workspace, VS Code prompts you to install them as a batch — click Install All and skip to Phase 3. The sections below document each extension's purpose so you know what you're accepting and can troubleshoot selectively if one fails to install.

The approved extension list below was rebuilt 2026-04-15 after review by Rick + chief.staff + project.manager. It supersedes the original 5 + 4 list chief.staff seeded on 2026-04-14.

Claude & remote work (core to the stack)

  1. Claude Code for VS Code (anthropic.claude-code, publisher: Anthropic) — runs Claude Code sessions inside VS Code's extension panel with richer UI than a terminal can offer. Inline chat pane, diff preview, one-click apply/reject, Cmd+Esc to send selected code to Claude. Matches the desktop app experience while keeping the CLI alongside.
  2. Remote - SSH (ms-vscode-remote.remote-ssh, publisher: Microsoft) — drive a remote workspace (iPad via Tailscale, second Mac, future team member) as if local. Pairs with the existing Tailscale setup.
  3. GitHub Copilot Chat (github.copilot-chat) — pre-existing. Kept from original seed.

Markdown & Obsidian-compatibility (vault authoring)

  1. Foam (foam.foam-vscode) — replaces the Obsidian MD extension from the original chief.staff seed. Better Obsidian-compatibility story: wikilink navigation ([[CLAUDE]], [[project.manager]]), backlinks panel, graph view, note templates, link references auto-maintained. Closer to Obsidian's mental model than the Obsidian MD extension.
  2. Markdown All in One (yzhang.markdown-all-in-one) — keyboard shortcuts for headings, lists, tables, TOC generation, formatting. Solid daily driver.
  3. Markdown Preview Enhanced (shd101wyy.markdown-preview-enhanced) — richer preview than VS Code's built-in: Mermaid diagram rendering, math formulas, embedded HTML, export to HTML/PDF. Good for the schema docs with tables and the mission diagrams.
  4. YAML (redhat.vscode-yaml, publisher: Red Hat) — frontmatter validation for all --- blocks in SOPs, task briefs, status reports, QA reports, handoffs. Catches malformed YAML before save. This is load-bearing for the 5-doc-type system in CLAUDE.md Section 6.

Git & history

  1. GitLens (eamodio.gitlens, publisher: GitKraken) — per-line inline git blame, commit graph, history navigation. Useful even without a GitHub remote once the vault is git-init'd (Phase 7).

Shell & scripting (for launcher work like aifactory-menu)

  1. Bash IDE (mads-hartmann.bash-ide-vscode) — format, hover docs, go-to-definition for .sh/.zsh files. Caught issues in the aifactory-menu v1.2 rewrite.
  2. ShellCheck (timonwong.shellcheck) — static analysis for shell scripts. Catches quoting bugs, unused variables, subshell pitfalls. Runs on-type. .vscode/settings.json has this configured.

Python (for monday_sync.py + code.platform work)

  1. Python (ms-python.python, publisher: Microsoft) — IntelliSense, linting, debugging, environment management. Standard.
  2. Pylance (ms-python.vscode-pylance) — fast type checker and language server. Pairs with Python extension. Set to basic type-checking mode per .vscode/settings.json.
  3. Ruff (charliermarsh.ruff) — extremely fast Python linter and formatter. Configured as default Python formatter with organize-imports on save in .vscode/settings.json. Replaces Black + isort + flake8 with one tool.

Quality of life (reduces friction across all file types)

  1. Error Lens (usernamehw.errorlens) — inline diagnostic display next to the offending line. Errors, warnings, info all visible without opening the Problems panel. Configured in .vscode/settings.json to show all three levels.
  2. Code Spell Checker (streetsidesoftware.code-spell-checker, publisher: Street Side Software) — catches typos in markdown (useful for long governance docs). Domain vocab pre-populated in .vscode/settings.json (eco|monetize, Jordan, launchd, Supabase, Cloudflare, Tailscale, Obsidian, ~60 terms) so it doesn't redline legitimate domain language. Ignores archive/, venvs, node_modules.

Also useful (not currently in extensions.json, install manually if you want them)

  • Path Intellisense (christian-kohler.path-intellisense) — autocomplete for file paths when typing markdown links. Seeded in chief.staff's original list; not in the approved batch but harmless to add.
  • Todo Tree (gruntfuggly.todo-tree) — surfaces TODO:/FIXME:/NOTE: comments across the vault in a sidebar. Useful for tracking in-progress work signals in code files.

What changed from the 2026-04-14 seed

Original (chief.staff) 2026-04-15 approved Why
Obsidian MD Foam (replacement) Foam is a better Obsidian-compatibility story — wikilinks + backlinks + graph, closer to Obsidian's model
(not listed) Remote - SSH added Enables iPad/remote Mac workflows via Tailscale without leaving VS Code
(not listed) YAML (Red Hat) added Frontmatter validation is load-bearing for the 5-doc-type system
(not listed) Bash IDE + ShellCheck added Shell script authoring quality (aifactory-menu, monday-sync-launcher, future hooks)
(not listed) Python + Pylance + Ruff added monday_sync.py maintenance and future code.platform work
Core = 5, Optional = 4 Batch = 15, plus 2 "also useful" Superset — chief.staff's list was the floor, approved list is the ceiling

The .vscode/extensions.json at the vault root now lists all 15 approved extensions so VS Code auto-prompts on first workspace open. Companion .vscode/settings.json has workspace-wide exclusions (archive, venvs, node_modules, synthetic meeting factory venv), Python/YAML/shell/markdown tuning, domain spell-check vocab, git + terminal + explorer tuning, and markdown validation. Both files were shipped to the vault on 2026-04-14 by project.manager.

This is the critical step that eliminates the Termius friction. VS Code's integrated terminal supports OSC 8 hyperlinks AND clickable custom URL schemes natively, but it needs one small preference tweak to handle obsidian:// URLs without prompting.

  1. Open VS Code Settings: Cmd+,
  2. Search for: terminal.integrated.allowChords
  3. Confirm it's enabled (it is by default — leaves Cmd-click working)
  4. Search for: terminal.integrated.enableMultiLinePasteWarning
  5. Set to: never (prevents a popup every time you paste multi-line URLs or content)

For obsidian:// URLs specifically: VS Code's terminal will render them as clickable. Cmd-click on any obsidian://open?vault=Claude&file=... URL in chat output and VS Code routes through macOS's open command, which launches Obsidian directly — no browser popup, no copy-paste step.

Test it: 1. Open the integrated terminal: **Ctrl+** (backtick) or **Terminal → New Terminal** 2. Run:echo "Click me: obsidian://open?vault=Claude&file=CLAUDE"` 3. Cmd-click the URL in the terminal output 4. Obsidian should launch and open CLAUDE.md

If it works — you're done with this phase. If it doesn't, fall back to copy-paste (triple-click the URL to select the whole line, Cmd+C, paste into Spotlight or browser).

Phase 4 — Launch Claude Code inside VS Code (5 min)

Two options:

Option A — Terminal-based (matches your Termius workflow)

  1. Open the integrated terminal: Ctrl+`
  2. Change directory to your target agent's cwd. For chief.staff: cd /Users/rhartley/Claude/system/agents/executive
  3. Run claude to start a Claude Code session in that cwd
  4. The session runs in the terminal with full Claude Code CLI features

Option B — Extension-based (new workflow, richer UI)

  1. Open the Command Palette: Cmd+Shift+P
  2. Type: Claude Code: Start (or similar — depends on extension's current command names)
  3. Select your vault or agent cwd
  4. The session runs in a dedicated VS Code panel with richer UI (tool calls rendered as cards, diffs inline, file references clickable)

Recommendation: start with Option A since it matches your current Termius workflow, then experiment with Option B once you're comfortable. Option B is more powerful but the learning curve is real.

Phase 5 — Set up parallel agent sessions (5 min)

One of VS Code's biggest advantages over Termius is running multiple Claude Code sessions in split panes within the same window.

  1. Open the integrated terminal (Ctrl+`)
  2. Click the split terminal icon in the terminal top-right (or right-click the terminal tab and select Split)
  3. In the new pane, cd into a different agent's cwd. Example: cd /Users/rhartley/Claude/sessions/project.manager && claude
  4. You now have chief.staff in one pane and project.manager (Jordan) in the other — side by side, visible simultaneously
  5. Tab between panes: Cmd+Down (focus editor), Ctrl+(focus terminal), Cmd+Shift+P →Terminal: Focus Next Terminal Group`

Phase 6 — Enable markdown preview workflows (2 min)

You can read any vault markdown file with live preview in VS Code without launching Obsidian.

  1. Open any .md file in the Explorer (e.g., CLAUDE.md)
  2. Cmd+Shift+V — opens VS Code's built-in markdown preview in a side pane
  3. Cmd+K V — opens preview side-by-side with source
  4. For richer preview (Mermaid, math, export): right-click the file → Open Preview using Markdown Preview Enhanced

When to use VS Code preview vs. Obsidian: - VS Code preview — quick reads, editing workflows, when you're already in VS Code and don't want to context-switch - Obsidian — deep reading, graph view, backlink exploration, dashboards with Dataview queries (Dataview only renders in Obsidian, not VS Code)

Phase 7 — Git-init the vault (optional, 3 min)

Even without a GitHub remote, local git gives you rollback, history, blame, and diff — plus VS Code's built-in git integration lights up with inline diffs as you edit.

cd /Users/rhartley/Claude
git init
git add .gitignore 2>/dev/null || true  # if .gitignore exists
echo ".DS_Store
.obsidian/workspace*.json
.obsidian/plugins/*/data.json
.claude/cache/" > .gitignore
git add -A
git commit -m "Initial v1.2 state 2026-04-14"

After this: - VS Code's Source Control sidebar (Cmd+Shift+G) shows changed files - GitLens shows inline blame - Any edit to vault files is trackable, rollback-able, and diff-viewable

Remote / GitHub sync is a separate decision — chief.staff recommends deferring until a secrets audit (gitleaks scan) is done. File as a decision record when ready.

Phase 8 — Verify the full flow (5 min)

Acceptance test — if all of these work, setup is complete:

  1. ✅ Open /Claude/ as workspace in VS Code, see full vault tree in Explorer
  2. ✅ Open integrated terminal, run claude inside it, see Claude Code session start
  3. ✅ Split terminal into 2 panes, run separate Claude Code sessions in each
  4. ✅ Cmd-click an obsidian:// URL in terminal output, Obsidian launches directly
  5. ✅ Cmd-click an absolute file path (e.g., /Users/rhartley/Claude/knowledge/tools/monday-com.md) in terminal output, opens in VS Code editor
  6. ✅ Cmd+Shift+V on any .md file shows live preview
  7. ✅ GitLens sidebar shows file history (if Phase 7 complete)
  8. ✅ Dataview queries render in Obsidian when you click an obsidian:// link (confirms Obsidian side still works independently)

Troubleshooting

Clickable obsidian:// URLs don't work in terminal: - Verify you're on a recent VS Code version (1.80+) - Check Terminal → Settings → Link Detection is enabled - Fall back to copy-paste: triple-click line, Cmd+C, paste to browser

Claude Code extension command not found: - Extension may not be published under that name — search the marketplace for "Claude Code" or "Anthropic" - Fall back to terminal-based workflow (Phase 4, Option A)

Parallel sessions collide: - Each Claude Code session must run in a DIFFERENT cwd so memory namespaces don't overlap - Verify with pwd in each pane before launching

Obsidian doesn't launch from Cmd-click: - Check macOS → System Settings → Privacy & Security → Extensions → App Extensions → Obsidian is allowed to handle obsidian:// URLs - Test by pasting a URL into Spotlight (Cmd+Space) — if that works, the URL scheme is registered; the issue is VS Code terminal not routing clicks

"Do you trust the authors?" popup on every VS Code launch: - In the popup, check "Trust all files in parent folder" or Don't ask again for this workspace - Then reopen the folder

Verification

After Phase 8 passes, you're in the primary desktop stack. Day-to-day flow:

  1. Launch VS Code (Cmd+Space → "Visual Studio Code")
  2. File → Open Recent → /Users/rhartley/Claude
  3. Open integrated terminal (Ctrl+`)
  4. cd to target agent cwd and run claude
  5. Work — Cmd-click file paths to open in editor, Cmd-click obsidian:// URLs to read in Obsidian
  6. Split terminal panes for parallel agent sessions as needed
  • [[claude-code]] — tool page
  • [[obsidian]] — tool page
  • [[tool-selection-policy-v1.0]] — wiki canonical home decisions
  • [[user_rick_tooling]] (chief.staff memory) — Rick's tooling context
  • [[feedback_obsidian_launch_links]] (chief.staff memory) — URL format preference

Notes

  • iPad stays on Termius. This playbook is for Mac desktop only. VS Code's iPad story is weaker; Termius is still the right tool for mobile CLI work.
  • Replaces the Termius + One Markdown workflow — previously Rick had to navigate in Finder and open .md files with a third-party viewer. VS Code's integrated preview + clickable paths eliminate that.
  • No HTML generation needed — previously Rick generated parallel HTML versions of markdown files using Tailwind to get better rendering. Obsidian's reading mode + VS Code's Markdown Preview Enhanced cover that need, so the duplicate-document problem goes away.
  • This playbook will rot as tools update. Re-verify quarterly per the /knowledge/playbooks/ convention.