What's inside

What it installs#

Packages come in three Homebrew layers. Brewfile goes on every machine; Brewfile.dev adds the build-machine tools; Brewfile.server is for headless Macs. Anything installed beyond these layers belongs in that machine's file, or map-check reports drift.

The setup itself#

CLI tools Claude reaches for (and I like as well)#

Languages and runtimes#

Shell#

Ops and networking#

Media and documents#

Apps#

macparakeet is Apple-silicon only (macOS 14+); the Brewfile skips it on Intel, and the dictation and transcript pipeline goes with it.

The dev-machine layer#

The server layer#

orbstack is in this layer too, for Bugsink and other self-hosted containers.

VS Code extensions#

Installed from vscode-extensions.txt by setup-tools.sh. Extras on one machine go in that machine's file.

What Homebrew can't install#

setup-tools.sh handles the rest, in idempotent steps you can run one at a time with --only.

Also linked or applied by /setup, not installed: dotfiles/ (zshrc, starship.toml, ghostty.config, gitconfig, gitignore_global, editorconfig) and macos-defaults.sh (keyboard repeat, Finder, Dock, hot corner, screenshots to ~/Pictures/Screenshots, ask for password on wake).

Services it uses#

Accounts come first, before you touch the machine, because every later step that needs a login stalls without one. Costs are only listed where the repo states them, and they were true at time of writing.

Syncthing is peer-to-peer and needs no account. MacParakeet transcribes on the machine; nothing leaves the Mac. There is no Dropbox and no iCloud Drive on working folders: every job they would do is already covered, and a second sync engine brings its own idea of what "deleted" means.

Every value above lives in a Bitwarden item named claude-computer/<service>, listed in docs/SECRETS.md. Losing claude-computer/r2-crypt means losing ~/resources in R2; it cannot be recovered from the bucket.

My fleet#

Five machines and a camera, in two kinds. A manager machine runs Claude Code and keeps a clone of the brain at ~/claude-computer; it writes its own docs/machines/<host>.md and nobody else's. A headless box has no brain: a manager reaches it over Tailscale and SSH, and afterwards writes that box's file onto it at /etc/claude-computer/machine.md, so the box can still say what it is if the repo goes stale.

Every one of my manager machines clones the same private repo — I called mine sys-admin. What makes a machine itself isn't the repo name, it's the hostname: Claude reads scutil --get LocalHostName and keeps docs/machines/<host>.md for it, and tags every commit [<host>]. So name your machines what you want to see in that path — sudo scutil --set LocalHostName mini — and keep the clone at ~/claude-computer on every one of them, because the hooks and permission rules assume that path. See docs/INSTALL.md § One repo for the whole fleet.

That's my fleet; yours will differ. A machine that is not in docs/FLEET.md is out of scope until you add it — nothing is managed implicitly.

One more thing on the fleet that has no operating system:

Camera — a dumb device: it takes pictures and hands over a card. Claude does everything after the shutter except the creative edit. Card in → camera-ingest copies RAW and video into ~/library/camera/YYYY/YYYY-MM-DD_<shoot>/, renames each file by capture time and frame number, writes SHA256SUMS, adds one exiftool row per file to index.csv, pushes a cold copy to R2, and never deletes anything from the card. From there it finds photos by metadata and darktable ratings, exports with darktable-cli, restores a pruned folder from R2, and regenerates INDEX.md. The brain draws its own line here: Claude doesn't make creative edits and doesn't delete photos — ratings, culling and edits happen in darktable, by hand.

Folder structure#

Top-level folders are containers, not repos — except claude-computer and vault. Repos live one level down. Nothing is ever nested.

~/
  claude-computer/     the fleet brain — a private repo made from the template
  projects/            active work — one repo per project (+ _scratch/, disposable)
  products/            projects that graduated to production — one repo each
  personal/            finance, personal projects — one repo each
  vault/               Obsidian second brain — a repo
  archive/             cold storage staging — pushed to R2, then removed
  library/             camera (RAW workflow), books and comics (Calibre)
  resources/<person>/  family key documents — encrypted two-way sync

Any folder that needs automation gets a CLAUDE.md — a brain — and a TASKS.md. Folders that just hold files have no brain. The vault is laid out for cheap capture and for Claude's retrieval, not for browsing — the second brain has its own section below.

The repo itself#

The second brain#

Obsidian, over a git repo, with Claude doing the filing. Capture is free; filing, linking and retrieval are Claude's job.

vault/
  inbox/        everything lands here — dictation, web clips, quick notes
  daily/        one note per day, drafted from tasks
  notes/        flat. atomic ideas, meetings, decisions. no subfolders
  people/       one note per person who keeps coming up
  projects/     one hub note per brain
  sources/      transcripts, articles, feed digests
  maps/         maps of content, all tasks, weekly reviews
  _templates/   Templater templates

Structure lives in properties, not folders. Every note carries the same frontmatter, and Claude enforces it when it files.

How things get in#

What Claude does with it#

• /inbox — empties inbox/: classifies, fixes frontmatter, files, links, routes tasks.
• /transcripts — a five-line summary with decisions and open questions, people linked, action items routed, the raw transcript filed.
• /today — the daily note, drafted from tasks rather than the calendar.
• /review — the weekly pass; it empties ## Unassigned first.

Rules that keep it sane#

• Tasks live with their brain; the vault gets copies. tasks-sync writes read-only copies into maps/tasks.md and each project hub. Ticking a box in Obsidian changes nothing — you change a task by telling the brain that owns it.
• Generated and authored content never mix. Scripts write only between tasks-sync markers or in notes marked generated. Everything else is yours, and no script overwrites it.
• ## Unassigned has an exit. Action items no brain owns sit at the top of the task map; every weekly review gives each one an owner or drops it to ## Later; once there are more than ten, tasks-sync sends one Telegram alert a day.
• Nothing leaves the Mac to become text. MacParakeet transcribes on the machine.

Why not PARA#

PARA was designed for a human doing the filing. It asked me to decide where a note belonged at the moment I had the least context to decide. With Claude filing, the right structure is an inbox, a flat notes folder and properties — and the discipline moves from "file correctly" to "capture everything."

What it needs#

The obsidian cask, and macparakeet (Apple silicon, macOS 14+ — the Brewfile skips it on Intel, and without it there is no dictation or transcript pipeline). vault-setup creates the vault and installs Obsidian Git, Dataview and Templater (third-party code; versions recorded). The Web Clipper is a browser extension: install it by hand and point it at inbox/.

Every script#

Everything in bin/ is on the PATH, answers --help, and returns an exit code rather than prose: 0 ok, 1 failed, 2 usage, 3 a tool is missing, 4 Bitwarden is locked, 5 missing config or secret.

The process#

Four forms, one rule: if it can be a script, it is a script. A slash command is for a step that needs judgment; it orchestrates scripts rather than reimplementing them. A hook is for what must happen every time without asking. A scheduled job is for what must happen with no session open.

Slash commands#

Linked into ~/.claude/commands/ from claude-global/commands/.

Hooks#

These run every session, without asking. That is the point: the syncing does not depend on discipline.

Permissions come from the same folder. claude-global/settings.json sets defaultMode: auto, puts git push, rm, brew uninstall, rclone, sudo, archive-push, resources-sync and new-app on the ask list, and puts force-push, bw get/list/export, the Keychain commands, .env files, SSH private keys, rclone.conf and the browse profiles on the deny list. Ask prompts even in auto mode; deny blocks in every mode. Neither is a sandbox.

Scheduled jobs#

Installed as launchd user agents by bin/schedule, prefixed local.claude-computer., logging to ~/Library/Logs/claude-computer/. map-check treats an unrecorded job as drift.

daily-note is the only job that runs Claude with nobody to answer a prompt, so it is fenced twice: ~/vault is its working directory and the only tree it can edit, and --allowedTools is Read, Edit, Write, Glob, Grep and git status/add/commit. Everything else is refused outright.

A normal day#

1. 06:00 — feeds-sync writes the reading digest into vault/sources/feeds/.
2. 06:30 — daily-note drafts vault/daily/<today>.md from the task picture, unattended.
3. You open a session. The SessionStart hook pulls the fleet repo, says whether Bitwarden is unlocked, exports any new transcript, and refreshes the vault's task copies.
4. /today — review the draft, add what you know, and every task you mention goes to the TASKS.md of the brain that owns it, not into the note.
5. Work. Claude reads the machine file first, uses the bin/ wrappers instead of MCP servers, and asks before anything destructive, credential-touching or billable.
6. 09:00 — map-check runs; if the machine and the map disagree, Telegram says so, and fixing it is this session's job.
7. After a meeting — transcripts-sync drops the transcript in the inbox; /transcripts writes the summary, links the people and routes every action item to an owning brain.
8. Every turn ends with the Stop hook committing and pushing docs/, so the next machine starts from a true picture. Once a week, /review empties ## Unassigned.

Getting it#

The template is on GitHub: narendranag/claude-computer. You need a Mac, a GitHub account and a Claude Max subscription; the quick start is the short version. One line, pasted into Terminal:

/bin/bash -c "$(curl -fsSL https://claude-computer.com/install.sh)"

It asks one question — what your private repo should be called — then installs whatever you're missing and hands over. Want a different name, the same on every machine? Pass it explicitly: -- --name sys-admin --dir ~/claude-computer. docs/INSTALL.md covers the installer end to end — flags, exit codes, and the by-hand equivalent — and how to read it before you run it. What the setup does not protect against is written down too — the Trust section of the README is the part to read closely.