Here are my dotfiles, I will be adding to it and explaining along the way.
A journey begins.
Paste this in Terminal — it installs Homebrew + git, clones the repo (HTTPS), and runs make setup:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" \
&& eval "$(/opt/homebrew/bin/brew shellenv 2>/dev/null || /usr/local/bin/brew shellenv)" \
&& brew install git \
&& git clone https://github.com/maxmaxou2/dotfiles.git ~/dotfiles \
&& cd ~/dotfiles \
&& make setupFrom inside the cloned repo (~/dotfiles):
make setup
This runs make xcode-clt, make brew, make stow, make jaynalerts, make context-mode,
make agentmemory, make litellm, make pi, make codex, make tmux-plugins, make verify-symlinks
(see Makefile for all targets).
The repo does not have to live at ~/dotfiles — make stow passes
--dir=$(CURDIR) --target=$(HOME), so any clone location works.
make brew # symlinks .Brewfile into $HOME, then `brew bundle --global`
make stow # stow --restow --dir=<repo> --target=$HOME <STOW_PACKAGES>
STOW_PACKAGES is defined at the top of the Makefile; edit it there rather
than keeping a second list in this README.
make jaynalerts
Clones git@github.com:jaynlabs/jaynalerts.git into ~/src/jaynalerts. It is a
private repo, so this step needs an SSH key already registered with GitHub and
access to the jaynlabs org — it is the one part of make setup that cannot run on
a bare machine. Override the source with make jaynalerts JAYNALERTS_REPO=....
make setup in jaynalerts does bun link (puts jaynalerts on PATH) and
jaynalerts init --claude-code --opencode --shell-rc ~/.zshrc, which installs the
Claude Code hooks, the opencode plugin, compiles the Swift notifier, and writes its
managed block into ~/.zshrc — i.e. into zsh/.zshrc here, since that path is
stowed. make jaynalerts depends on stow so the symlink exists first.
Replaces the older stay-alert. jaynalerts notifies through its own Swift
UNUserNotification helper and is focus-aware on its own (transient when the
terminal is focused, sticky when it is not), so the Hammerspoon hook that used to
clear alerter notifications on Ghostty focus — and the alerter dependency
itself — are gone.
make pi # npm install -g @earendil-works/pi-coding-agent, then check the stowed config
make verify-symlinks
pi reads everything from ~/.pi/agent/, which mixes config with machine-local state,
so the pi stow package owns only two paths:
pi/.pi/agent/settings.json— provider/model defaults, theme, steering mode. pi rewrites this file in place (e.g.lastChangelogVersionafter an upgrade), and since it is a symlink those writes land in this repo. That is intentional.pi/.pi/agent/extensions/jaynalerts.ts— the notification extension, written byjaynalerts init --pithrough the symlink. Same managed-file deal as the jaynalerts block inzsh/.zshrc.
Everything else in ~/.pi/agent stays machine-local and is kept out both by
pi/.stow-local-ignore and by the root .gitignore: auth.json (credentials),
models-store.json (~110KB provider cache), sessions/, and a vendored fd binary
under bin/.
Skills are not duplicated per agent: pi and Codex both read ~/.agents/skills,
which is populated with symlinks into claude/.claude/skills — one copy serves
Claude Code, Codex and pi.
make codex # npm install -g @openai/codex, then check the stowed config
make verify-symlinks
Like pi, ~/.codex mixes config with a lot of runtime state, so the codex package
stows only the declarative half:
codex/.codex/config.toml— model, reasoning effort, TUI/status line, MCP servers, plugins and marketplaces. Expect churn: Codex appends a[projects."<path>"] trust_levelblock every time you trust a new directory, and rewrites[hooks.state]trusted_hashvalues and[marketplaces]revisions on its own. Those are machine-local by nature but live in the same file as the real config, so they ride along in the diffs.codex/.codex/hooks.json— the code-review-graphPostToolUse/SessionStarthooks and the jaynalertsPermissionRequesthook.codex/.codex/rules/default.rules— the command allowlist. Codex appends aprefix_rule(...)here each time you approve a command, so this file grows through the symlink into this repo.
Everything else stays machine-local and is excluded by codex/.stow-local-ignore
plus the root .gitignore: auth.json, the sqlite databases
(thread_history_1, logs_2, state_5, queue_1, memories_1, goals_1),
sessions/, history.jsonl, plugins/ cache, shell_snapshots/ and
context-mode/.
~/.codex/agents and ~/.codex/rules are folded by stow into directory symlinks,
so anything Codex writes there is version controlled automatically.
make context-mode # npm install -g context-mode
make verify-symlinks # sanity-check ~/.claude/* and opencode.json symlinks
- opencode: registered via
plugin: ["context-mode"]inopencode/.config/opencode/opencode.json. Plugin is loaded in-process — no MCP entry needed. Routing rules live inopencode/.config/opencode/AGENTS.md. - Claude Code and Codex: not installed. The plugin, its marketplace, and the
context-mode-cache-heal.mjsSessionStarthook were removed fromclaude/.claude/settings.jsonand~/.codex/config.toml.
make agentmemory # npm install -g @agentmemory/agentmemory, launchd autostart, claude plugin
make verify-symlinks
Persistent memory that auto-captures sessions/tools and recalls context into future sessions. A local REST server runs on http://localhost:3111 (viewer: http://localhost:3113).
- Server:
make agentmemoryinstalls the@agentmemory/agentmemorynpm package and rendersagentmemory/ai.agentmemory.plist.ininto~/Library/LaunchAgents/ai.agentmemory.plistso the server autostarts at login (KeepAlive). launchd plists take no variable expansion, so the template's@HOME@/@PATH@/@AGENTMEMORY_BIN@are substituted at install time — nothing user-specific is committed. - Provider keys: on a fresh machine
agentmemory initseeds~/.agentmemory/.env. Fill in the LLM + embeddings keys there — this file holds secrets and is not committed. Verify withagentmemory status(Provider/Embeddings should be ✓). - Claude Code: marketplace
rohitg00/agentmemoryis declared underextraKnownMarketplacesand enabled viaenabledPlugins["agentmemory@agentmemory"]inclaude/.claude/settings.json. The plugin registers 12 hooks, 8 skills, and auto-wires the@agentmemory/mcpserver via its own.mcp.json— no manualmcpServersentry needed.make agentmemoryrunsclaude plugin marketplace add rohitg00/agentmemory && claude plugin install agentmemory@agentmemory; if the CLI step fails, run/plugin install agentmemoryinside Claude Code. - opencode: wired declaratively in
opencode/.config/opencode/opencode.json— manualmcp.agentmemoryentry (opencode does NOT auto-wire MCP) plusplugin: ["./plugins/agentmemory-capture.ts"]. The plugin (plugins/agentmemory-capture.ts, 22 auto-capture hooks) and/recall+/remembercommands (commands/) are stowed by theopencodepackage viamake stow. - Verify:
curl http://localhost:3111/agentmemory/healthandagentmemory status. - MCP shim: set
AGENTMEMORY_URL=http://localhost:3111andAGENTMEMORY_FORCE_PROXY=1in~/.agentmemory/.envso the MCP server (Claude Codememory_*tools, opencode/recall) always proxies to the daemon instead of silently falling back to a throwaway standalone db when the daemon was briefly down at shim start. - LLM compression (optional, richer summaries) is routed through a LiteLLM proxy → Vertex/Gemini — see next section.
make litellm
agentmemory's AGENTMEMORY_AUTO_COMPRESS runs an LLM on observations for richer memories. agentmemory has no native Vertex support (its Gemini path only hits AI Studio), so a local LiteLLM proxy bridges it: agentmemory speaks OpenAI → LiteLLM → Vertex AI (Gemini 2.5 Flash) using a GCP service account, billed to the jayn-dev project / europe-west4.
agentmemory ──OpenAI API──▶ LiteLLM (localhost:4000) ──SA auth──▶ Vertex AI / Gemini 2.5 Flash
- Install/run:
make litellminstalls the proxy viauv(withgoogle-cloud-aiplatform+google-auth) and renderslitellm/ai.litellm.plist.ininto~/Library/LaunchAgents/ai.litellm.plist(autostart,KeepAlive). - Config:
litellm/.config/litellm/config.yamlis committed and stowed to~/.config/litellm/config.yaml. It holds no secrets and no absolute paths — every machine-specific value (master_key,vertex_project,vertex_credentials,database_url) is anos.environ/Xlookup the proxy resolves at startup from~/.config/litellm/.env, which the launchd job sources before exec. That.envis rendered fromlitellm/.config/litellm/.env.exampleonmake litellmand is gitignored (so is*-sa.json). - Secrets (manual on a fresh machine, never committed):
- Place the Vertex service-account JSON at
~/.config/litellm/vertex-sa.json(chmod 600). - Fill
LITELLM_MASTER_KEY,GITHUB_TOKEN,OPENCODE_API_KEYandVERTEX_PROJECTin~/.config/litellm/.env.make litellmwarns for each one left empty. - Point agentmemory at it in
~/.agentmemory/.env:OPENAI_API_KEY=<the litellm master_key> OPENAI_BASE_URL=http://localhost:4000 OPENAI_MODEL=gemini-flash EMBEDDING_PROVIDER=openai # route embeddings through litellm too OPENAI_EMBEDDING_MODEL=vertex-embed OPENAI_EMBEDDING_DIMENSIONS=768 AGENTMEMORY_AUTO_COMPRESS=true MAX_TOKENS=1024 - Restart:
launchctl kickstart -k gui/$(id -u)/ai.agentmemory. - For the opencode→LiteLLM provider (the
architect-geminiagent), export the samemaster_keyin~/.zshrc_private(gitignored, sourced byzsh/.zshrc):opencode resolvesexport LITELLM_MASTER_KEY=<the litellm master_key>{env:LITELLM_MASTER_KEY}at launch; without it the provider sends an empty bearer and Vertex calls 401.make litellmwarns if it's unset.
- Place the Vertex service-account JSON at
- opencode provider:
opencode/.config/opencode/opencode.jsondeclares alitellmprovider (@ai-sdk/openai-compatible→localhost:4000/v1) so any opencode agent can target a LiteLLM model vialitellm/<model_name>. Thearchitect-geminiagent (agents/architect-gemini.md) useslitellm/gemini-3-pro→ Vertexgemini-3.1-pro-preview(global endpoint). Add a model = onemodel_listentry inconfig.yaml+ one line under the provider'smodels. - Why these choices:
reasoning_effort: disable(Gemini 2.5 thinking wastes output tokens on compression); both LLM (gemini-2.5-flash) and embeddings (gemini-embedding-2, top MTEB, 768-dim) run on Vertex credits. - Embedding-2 quirk: it's global-endpoint only (
vertex_location: global) — 404s on a regional location likeeurope-west4. - Switching embedding provider/dims after data exists crashes the worker (
persisted vector index has wrong dimension). Recovery: addAGENTMEMORY_DROP_STALE_INDEX=trueto~/.agentmemory/.env, restart, then remove the line (rebuilds from live observations). - Verify:
curl http://localhost:4000/health/liveliness→ 200; live test:KEY=$(grep '^LITELLM_MASTER_KEY=' ~/.config/litellm/.env | cut -d= -f2-); curl -s localhost:4000/v1/chat/completions -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"model":"gemini-flash","messages":[{"role":"user","content":"ping"}],"max_tokens":50}'
make backup # restic, launcher, ~/.config/restic skeleton, hourly launchd job
restic-backup init # once per machine, creates the encrypted repository
caffeinate -i restic-backup # first full upload, keeps the Mac awake
backup/restic-backup.sh backs up $HOME every hour and, once a week, prunes old
snapshots and downloads 5% of the repository to verify it. Snapshots are kept hourly
for 2 days, daily for 2 weeks, weekly for 2 months and monthly for a year, counted
from the latest snapshot so a Mac that sits closed for weeks keeps its history.
What is skipped is in backup/excludes.txt: ~/Library, toolchains, package caches,
node_modules/.venv, anything tagged CACHEDIR.TAG, and logs.
- Nothing secret is committed.
~/.config/restic/(mode 700) holdsenv(repository, fixed host name, healthchecks URLs; template inbackup/env.example),password(generated bymake backup) andexcludes.local(personal paths). The storage box login is aHost storagebox-backupblock in~/.ssh/configwith its own key,~/.ssh/id_ed25519_storagebox. - The repository password is the one thing that must outlive the Mac. Keep a copy in a password manager; without it the backup cannot be decrypted.
- Full Disk Access goes to
~/.local/bin/restic-backup-launcher, a small C program that launchd starts instead of the script. macOS charges a launchd job's file reads to the job's own binary, so the grant lives on the launcher and survives restic upgrades. Without it the job cannot read Desktop, Documents or Downloads. - Alerts come from healthchecks.io by email: no successful backup for 3 days, or no successful maintenance for 9. A failed run is only logged there, since a laptop is often offline. restic's exit code 3 (some files unreadable, typically a lost Full Disk Access grant) counts as a failure.
- Runs never overlap. A run that starts while another is still going (the first full upload, a manual run) exits straight away and leaves the next hour to catch up.
- Logs:
~/.local/state/restic-backup/(backup.log,maintain.log,history.log).
Restore:
restic-backup snapshots
restic-backup restore latest --target /tmp/restore --include "$HOME/src/some-repo"
restic-backup mount /tmp/restic # browse every snapshot (needs macFUSE)
Adding a Mac (each machine gets its own Storage Box sub-account, repository and password):
- Storage Box owner, Hetzner Console: create a sub-account with its own folder, SSH support and external reachability on, not read-only.
- New Mac: FileVault on, then
make backupfrom a clone of this repo (notmake setup). The clone must stay where it is: the launchd job runs the script from it. - Grant Full Disk Access to
~/.local/bin/restic-backup-launcher; save~/.config/restic/passwordin a password manager. ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_ed25519_storagebox, and add to~/.ssh/config:Host storagebox-backup HostName uXXXXXX-subN.your-storagebox.de User uXXXXXX-subN Port 23 IdentityFile ~/.ssh/id_ed25519_storagebox IdentitiesOnly yes ServerAliveInterval 60 ServerAliveCountMax 240- Install the key:
cat ~/.ssh/id_ed25519_storagebox.pub | ssh storagebox-backup install-ssh-key(asks for the sub-account password). Only accept the host key if its fingerprint is one Hetzner publishes; for ED25519 that isSHA256:XqONwb1S0zuj5A1CDxpOSuD2hnAArV1A3wKY7Z3sdgM. - Fill
~/.config/restic/env:RESTIC_HOSTand two healthchecks.io checks (backup: period 1 day, grace 2 days; maintenance: period 7 days, grace 2 days). restic-backup init, then preview what would be uploaded and add personal paths to skip to~/.config/restic/excludes.local:restic-backup backup "$HOME" --dry-run -vv --one-file-system --exclude-caches \ --exclude-file backup/excludes.txt --exclude-file ~/.config/restic/excludes.localmake backupagain to schedule the hourly job, thencaffeinate -i restic-backupfor the first full upload (mains power, lid open).
Two files hold per-machine state and are deliberately not committed:
~/.zshrc_private— secrets, work aliases, tokens. Sourced byzsh/.zshrcif present.~/.claude/settings.local.json— Claude Code user settings that are machine- or employer-specific, notably theautoModeblock (trusted repo, org, prod-command deny list). It is a real file, not stowed, and is globally gitignored. The committedclaude/.claude/settings.jsonholds only portable settings.
-
Karabiner :
- Open Karabiner-Elements from your Applications folder.
- Grant necessary permissions in System Preferences > Security & Privacy (Input Monitoring and Accessibility).
-
Postgres related :
createuser --superuser $USER -U postgres
createdb $USER -U $USER
- Add scripts calling general commands for setup
My Neovim setup is designed for a modern development experience with a focus on productivity and ergonomics. Here's a breakdown of the key plugins and their purposes:
- LazyVim - Plugin manager and configuration framework
- Catppuccin - A soothing pastel theme for Neovim
- Telescope - Fuzzy finder for files, buffers, and more
- With
telescope-fzf-nativefor better performance
- With
- Treesitter - Advanced syntax highlighting and code navigation
- With
nvim-treesitter-contextfor showing code context - With
playgroundfor debugging syntax highlighting - With
nvim-treesitter-textobjectsfor smart text objects
- With
- Mason - Package manager for LSP servers
- mason-lspconfig - Auto enabling of mason lsp servers
- blink-cmp - Completion engine with blink effect
- nvim-lspconfig - Native LSP configuration
- conform - Formatter plugin, lightweight yet powerful
- Harpoon2 - Quick file navigation between frequently used files
- Leap - Quick motion plugin for faster navigation
- nvim-surround - Easy text surrounding operations
- nvim-autopairs - Automatic bracket pairing
- nvim-ufo - Modern folding experience
- vim-tmux-navigator - Seamless navigation between Vim and tmux splits
- vim-test - Testing support
- avante.nvim - AI-powered coding assistant
- bigfile - Better handling of large files
- yeet - Quick file operations
- persistence - Session management
- vim-be-good - Neovim training game
- cellular-automaton - Fun animations
- Azerty Layout Support - Custom configuration for AZERTY keyboard layout
- Custom Keymaps - Personalized key mappings for improved workflow
This configuration is continuously evolving as I discover new tools and better ways to work with Neovim. Feel free to explore and adapt any parts that you find useful!
My Hammerspoon setup includes several productivity-enhancing features:
- Displays active key presses in real-time
- Toggle with
ctrl + cmd + k - Useful for presentations and debugging keyboard inputs
- Cycles through predefined positions before disabling
- Fast application switching using keyboard shortcuts
- Mapped to
ctrl + cmd + [number] - Common applications mapped to numbers (7,8,9, etc.)
- Provides instant access to frequently used applications
- Application window maximization (fake fullscreen) using ctrl + cmd + F
- Move the focused window to the next display (maximized) with
ctrl + cmd + m
This setup provides quick access to applications and keyboard input visualization when needed.
<Space>- Leader key<leader>e- Open file explorer (Ex)<C-s>- Save file (works in normal, insert, and visual modes)
<C-Up/Down/Left/Right>- Resize windows<C-w>qor<C-w><C-q>- Close split and navigate left (Tmux aware)<leader>gd- Open definition in vertical split<leader>gg- Open references in vertical split<leader>gr- Open LSP references in vertical split
<leader>y- Copy to system clipboard<leader>Y- Copy line to system clipboard (from cursor to end)<leader>yy- Copy whole line to system clipboard<leader>p- Paste from system clipboard<leader>P- Paste before from system clipboard<leader>yp- Copy full file path to clipboard<leader>yn- Copy filename to clipboard<leader>yd- Copy parent directory path to clipboard
<C-d>- Scroll down (centered)<C-u>- Scroll up (centered)<C-j>- Go down a pane (Tmux aware)<C-k>- Go up a pane (Tmux aware)<C-h>- Go left a pane (Tmux aware)<C-l>- Go right a pane (Tmux aware)
<S-Tab>- Unindent (normal and insert mode)<Tab>- Indent (visual mode)<S-Tab>- Unindent (visual mode)
<leader>bp- Insert Python breakpoint<leader>bd- Insert Dagster debugger breakpoint<leader>T- Launch nearest test, test file or test class<leader>S- Launch nearest test, test file or test class while updating snapshots
<C-p>- Find files (git files if in repo, all files otherwise)<leader>ps- Grep with input prompt<leader>pf- Live grep<leader>w- Fuzzy find in current buffergr- Find LSP referencesgd- Go to LSP definition<leader>gr- Go to LSP references in a new v-split<leader>gd- Go to LSP definition in a new v-split
<leader>dv- Opens up telescope git branches listing and show diffview for the selected, quit diffview if already opened<leader>df- Toggles file tree display
ctrl + cmd + F- Make focused window fullscreen (custom fullscreen)
ctrl + cmd + k- Toggle key logger displayctrl + cmd + m- Screen swapping functionality
Note: Additional Hammerspoon keybindings for application quick launch (ctrl + cmd + [number]) are configured but not explicitly listed in the configuration files.
This cheatsheet will be continuously updated as new keymaps are added to my configuration.