My personal machine setup — feel free to use, copy, clone, and contribute.
Targets Apple Silicon on current macOS. No prerequisites: Homebrew installs the Xcode Command Line Tools itself if they are missing.
git clone git@github.com:smarkovik/mac-setup.git
cd mac-setup
./mac-setup.shOr straight from the terminal:
cd /tmp && curl -fsSL -o mac-setup.zip https://github.com/smarkovik/mac-setup/archive/refs/heads/main.zip && unzip -oq mac-setup.zip && cd mac-setup-main && ./mac-setup.shEvery step is idempotent and reports when it has nothing to do, so this is meant to be run repeatedly — not just once on a fresh laptop.
./mac-setup.sh --dry-run # show what would change, change nothing
./mac-setup.sh --list # list the steps
./mac-setup.sh --only macos-defaults # run one step
./mac-setup.sh --force # re-apply steps that would be skippedThe macOS defaults step compares every setting against its live value and writes
only what differs, so it converges: change something in System Settings and
the next run puts it back. Dock, Finder and SystemUIServer are restarted only
when something actually changed, so a run with no drift closes none of your
Finder windows. --force rewrites every setting regardless of its current
value.
This is meant to be pushed to and re-run over time, not just for a fresh
laptop, so a step that fails is reported and skipped rather than stopping
everything after it - a broken Brewfile cask shouldn't block git, ssh,
zsh, or opencode from doing their job. Each step also prints which
number it is and how long it took:
==> [2/10] packages
...
===> step 'packages' failed after 41s (exit 1) - continuing with the remaining steps
===> once it is fixed, re-run just that step:
===> ./mac-setup.sh --only packages
==> [3/10] python
...
===> finished in 96s with 1 step(s) needing attention:
===> - packages (re-run: ./mac-setup.sh --only packages)
brew bundle itself already keeps installing the rest of the Brewfile past
one bad cask - this is the same idea one level up, across steps. A cask that
fails because of something already in /Applications (a version mismatch,
usually) needs a manual look, not automatic deleting - rm -rf the app
yourself, then --only packages again.
| Path | What it is |
|---|---|
mac-setup.sh |
Orchestrator: flags, step ordering |
Brewfile |
The package list — source of truth for what gets installed |
scripts/lib.sh |
Shared logging, dry-run and defaults comparison helpers |
scripts/10-homebrew.sh |
Install Homebrew, put it on PATH |
scripts/20-packages.sh |
Apply the Brewfile |
scripts/25-python.sh |
Put Homebrew's CPython ahead of Apple's on PATH |
scripts/30-dirs.sh |
Home folder structure |
scripts/40-git.sh |
Global git config |
scripts/50-ssh.sh |
SSH key for GitHub |
scripts/60-zsh.sh |
oh-my-zsh |
scripts/65-opencode.sh |
Link OpenCode's config into this repo |
scripts/70-macos-defaults.sh |
macOS UI preferences |
scripts/80-local-code.sh |
Link local-code into ~/bin |
config/opencode/opencode.json.tmpl |
The OpenCode config — edit this (source of truth) |
bin/opencode-config |
Generates opencode.json from the template with only installed models |
config/opencode/prompts/ |
System prompts for the planner/architect/debugger/reviewer agents |
config/opencode/AGENTS.md |
Always-on global guidance OpenCode loads every session |
bin/local-code |
Control panel: pull/run/wipe/sync the local coding models |
scripts/90-passwordless-sudo.sh |
Opt-in, see below |
tools/validate-brewfile.sh |
Check every Brewfile token exists |
tools/audit-defaults.sh |
Find which key macOS really uses for a setting |
Edit the Brewfile and re-run. Removing a line does not uninstall anything;
do that yourself with brew uninstall / brew uninstall --cask.
Do not reach for
brew bundle cleanup. It lists everything installed that is not in theBrewfile— which is not drift, it is the rest of your machine. On a real install it proposed removinggh,awscli,ansible,pipxandngrok. TheBrewfileis the subset this repo manages, never an inventory of everything you have.
Before committing a new entry, check the token exists:
./tools/validate-brewfile.shbrew bundle fails the entire file on one bad token, so a single typo
takes every other package with it. CI runs this on a macOS runner for the same
reason.
config/opencode/opencode.json is generated from
config/opencode/opencode.json.tmpl (the committed source of truth) by
bin/opencode-config, then symlinked into ~/.config/opencode. The generator
copies the template but keeps only the ollama models you have actually
downloaded, so OpenCode's picker matches ollama list (see local-code
below). Edit the template, then re-run the step — or local-code sync — to
regenerate:
./mac-setup.sh --only opencodeIf you already have a config there, it is moved aside to
opencode.json.backup-<timestamp>, never overwritten. To keep those settings,
merge them into the template and re-run.
It points at local model servers, not a cloud provider. Both entries use
@ai-sdk/openai-compatible against an OpenAI-shaped endpoint on localhost, so
neither needs an API key:
| Provider | baseURL |
Served by |
|---|---|---|
ollama |
http://localhost:11434/v1 |
ollama serve |
llamacpp |
http://127.0.0.1:8080/v1 |
llama-server |
The ollama models are managed for you: local-code downloads the tiers and
regenerates the config so only the ones you have appear. The llamacpp entry's
single local model is whatever you point llama-server -m at. OpenCode sends
the ID through verbatim, so a model not actually being served fails at request
time, not at load time.
There are no credentials here to protect. If you ever do add a cloud provider,
put the key in ~/.local/share/opencode/auth.json via opencode auth login —
a directory this repo never reads, writes or links — or reference it rather than
embedding it, since OpenCode resolves {env:VAR} and {file:path} at load time:
"apiKey": "{env:ANTHROPIC_API_KEY}"JSON has no comments, so the notes live here rather than in the file. Full key
reference — model, agent, mcp, permission, formatter, lsp — is at
opencode.ai/docs/config.
Three quant tiers of one model (unsloth/Qwen3-Coder-30B-A3B-Instruct-GGUF) —
same weights, trading size and RAM for a little quality:
| Tier | Quant | ~Size | Ollama tag |
|---|---|---|---|
small |
IQ4_XS | 16 GB | qwen3-coder:small |
mid |
Q5_K_M | 22 GB | qwen3-coder:mid |
big |
Q6_K | 25 GB | qwen3-coder:big |
local-code (symlinked to ~/bin by scripts/80-local-code.sh) drives them —
local-code help prints the full summary:
local-code list # tiers, which are downloaded, disk free
local-code pull mid # download a tier (or: small | big | all)
local-code run big # pull if needed, start ollama, launch OpenCode
local-code wipe small # delete a tier to free disk (or: mid | big | all)
local-code sync # rebuild opencode.json to match what's downloadedThe picker shows only what you've downloaded. OpenCode can't auto-detect
ollama models, so pull, wipe and sync regenerate opencode.json from
ollama list — any installed tag is included, using the template's
name/context-limit if it has an entry there, otherwise a generic one. Pulling
a model outside the three tiers (e.g. another ollama.com model) needs no repo
edit — just ollama pull it, then local-code sync.
Tiers download, they aren't ollama pulled. Hugging Face serves the GGUF
blobs from a separate CDN host via a redirect ollama pull refuses ("blocked
redirect to a different host"), so local-code fetches the file with curl
(resumable) and builds the tag locally with ollama create.
The context window is baked in at 32k (PARAMETER num_ctx), not left to
ollama's ~4k default. Override per pull if you have the RAM:
LOCAL_CODE_NUM_CTX=65536 local-code pull bigpull/wipe are the point: at 25 GB for the largest tier, pull what you need,
run it, wipe it when done rather than let three quants sit on disk. Q8_0 isn't
offered — on 48 GB it leaves almost no KV-cache headroom for a quality jump
that's the flattest part of the curve on a sparse MoE.
Four agents in config/opencode/opencode.json, each scoped to one job with
its own model and permissions, prompts in config/opencode/prompts/:
| Agent | Mode | Model | Edit | Bash |
|---|---|---|---|---|
planner |
primary | qwen3-coder:big |
deny | ask |
architect |
primary | qwen3-coder:big |
deny | ask |
debugger |
subagent | qwen3-coder:mid |
ask | allow |
reviewer |
subagent | qwen3-coder:big |
deny | deny |
planner, architect and reviewer cannot edit files - they read and
reason, so a bad call costs nothing. debugger can run commands and edit,
because reproducing a failure and fixing it needs both.
The big/mid split is a quantization/RAM tradeoff of the same 30B model,
not a capability tier: big (Q6) keeps a little more fidelity where there is
no tight loop to stay fast for; debugger runs mid (Q5) because that loop is
interactive and lighter matters more than the marginal quality of a higher
quant. What actually differentiates the agents is their prompt and permissions,
not the model behind them.
planner breaks a spec into small, vertically-sliced tasks before any code;
architect reviews or designs structure; debugger reproduces and fixes;
reviewer reads a diff for real, most-severe-first findings.
Invoke a subagent with @debugger or @reviewer in OpenCode, or switch to
planner or architect as your primary agent.
config/opencode/AGENTS.md is symlinked into ~/.config/opencode and loaded
by OpenCode on every session, so its guidance applies to every agent. It holds
the default working style - lazy in the good way: YAGNI, reuse before writing,
stdlib and native platform features before dependencies, the shortest change
that actually works, root-cause over symptom. Edit it to change how every
agent behaves by default.
This repo's AI setup lives entirely in OpenCode - agents, prompts and
AGENTS.md, all underconfig/opencode/- not in Claude Code..claude/is gitignored.
scripts/66-opencode-platform.sh (the step after opencode) symlinks three
more things from config/opencode/ into ~/.config/opencode, so they install
automatically on every ./mac-setup.sh and stay version-controlled here:
- Markdown agents (
agents/{builder,tester,security}.md) — agents defined as markdown with frontmatter, alongside the JSONplanner/architect/… ones. - Skills (
skills/<name>/SKILL.md) — reusable task playbooks OpenCode invokes on its own via the built-inskilltool, matching on each skill'sdescription. Four ship here: feature-development, production-debugging, pull-request-review, security-review. bin/github-mcp-via-gh.sh— the GitHub MCP, run throughgh(no Docker, no PAT env; needsgh auth login).
Add a skill — create a folder and a SKILL.md; no config change needed:
config/opencode/skills/my-skill/SKILL.md
---
name: my-skill # lowercase-hyphens, matches the folder
description: Use when <the exact trigger situation>. # what the model matches on
---
# My skill
1. Step one…
It goes live on the next ./mac-setup.sh (or --only opencode-platform) via
the skills symlink. Keep the description sharp and trigger-y — a local model
only reaches for a skill when it clearly matches the situation.
Per-project rules — OpenCode also reads an AGENTS.md at the root of
whatever project you open, in addition to the global one above. Drop an
AGENTS.md in a repo and it applies there automatically; nothing to configure.
Check it all — opencode-doctor (installed to ~/bin) verifies the
symlinks, config, agents, skills, gh auth, and which model tiers are pulled.
"lsp": trueTurns on every language server OpenCode ships built-in support for, each
activating only when its own project already satisfies it (a typescript
dependency, pyright installed, and so on) - this repo doesn't install any
of them for you. Gives every agent real go-to-definition and references
instead of grepping for text, which matters most for architecture and
review: "what else calls this" is a structural question, not a text search.
"mcp": {
"github": {
"type": "local",
"command": ["docker", "run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "-e", "GITHUB_TOOLSETS=repos,issues,pull_requests,actions,code_security", "ghcr.io/github/github-mcp-server"],
"environment": { "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_PERSONAL_ACCESS_TOKEN}" },
"enabled": false
}
}Lets the reviewer agent look at a real PR - diffs, check runs, existing
review threads - instead of only a local diff. Disabled by default. The
runtime it needs is in the Brewfile (colima + docker); to turn it on:
colima start- starts the container daemon (once per boot).- Create a GitHub PAT and export
GITHUB_PERSONAL_ACCESS_TOKEN. - Flip
enabledtotrueinconfig/opencode/opencode.json.
Sentry MCP (@sentry/mcp-server) is a reasonable second addition if you use
Sentry, for the same reason - direct issue/error lookup instead of pasting
stack traces in by hand - but it authenticates via an OAuth flow per
account, so it isn't pre-wired here; add it the same way once you've looked
at github.com/getsentry/sentry-mcp.
defaults write succeeds against a key nothing reads, so a setting can be dead
for years without any error — com.apple.menuextra.battery ShowPercent sat in
here long after the battery item moved to Control Center in Big Sur. Reading the
value back cannot detect that; only watching what the system itself writes can.
./tools/audit-defaults.sh # watch the domains we touch
./tools/audit-defaults.sh com.apple.dock # or specific onesIt snapshots the domains, waits while you change one thing in System Settings, then diffs and names the key macOS actually writes today. Worth a pass after each major macOS release — there is no reliable published source for this, and the usual reference (macos-defaults.com) has no macOS 26 data at all.
brew "python" tracks whatever Homebrew currently calls current, so this
follows new releases rather than pinning a version.
python3 resolves to Homebrew's automatically, because the brew shellenv line
puts /opt/homebrew/bin ahead of /usr/bin. Homebrew deliberately does not
link an unversioned python/pip, so scripts/25-python.sh adds the formula's
libexec/bin to PATH — that is what makes plain python and pip work.
Apple's remains at /usr/bin/python3 if you need it explicitly.
Fork it. Three things are mine and you will want to change them:
- git identity in
scripts/40-git.sh. It only fills in what is not already set, so it will not overwrite yours — but on a fresh machine you would get mine. Override withGIT_USER_NAME/GIT_USER_EMAIL, or just edit the file. - macOS defaults in
scripts/70-macos-defaults.share my preferences, includingen_GB/EUR/Centimeters locale settings. - The
Brewfileis the set of apps I actually run. It is a plain list — delete the lines you do not want.
Not part of the default run. Nothing in this repo needs it — Homebrew prompts
for its own sudo, and every defaults write here is user-level.
./mac-setup.sh --only passwordless-sudo # enable
sudo rm /private/etc/sudoers.d/$(whoami) # undoIt is permanent until you remove that file.