dotfiles

Personal dotfiles for macOS, with Ubuntu 24.x/Linuxbrew support for the shell, tmux, Herdr, and agent-tooling setup.

Quick Start

macOS

git clone https://github.com/mikeastock/dotfiles.git ~/code/personal/dotfiles
cd ~/code/personal/dotfiles
make dot-all

Ubuntu 24.x

Install Homebrew/Linuxbrew first, then:

git clone https://github.com/mikeastock/dotfiles.git ~/code/personal/dotfiles
cd ~/code/personal/dotfiles
make dot-all

make dot-all skips macOS-only defaults on Linux.

Agent Skills / Extensions Tooling

This repo also contains reusable skills, prompt templates, and extensions for Amp, Claude Code, and Pi Coding Agent.

Requirements

• Python 3.11+
• Git
• Homebrew or Linuxbrew for make dot-install

Agent commands

make install                 # install agent skills/prompts/themes/extensions and Amp plugins
make install-tools           # install pinned external agent tools such as dcg and scopey
make setup-tools             # configure installed tools that integrate with agents
make install-skills
make install-amp-plugins
make install-prompts
make install-themes
make install-extensions
make install-configs
make build                   # build agent artifacts only
make clean                   # clean agent build/install artifacts
make plugin-update           # update plugin submodules

External native tools are pinned under [external_tools] in plugins.toml. They are installed into ~/.local/bin without allowing upstream installers to modify agent settings; this repository owns those settings through make install-configs. The full make install workflow installs tools, applies managed configs, then runs any declared tool setup. Scopey therefore installs hooks for Claude, Codex, Grok, Pi, and OpenCode after the managed Codex hook configuration is in place.

Amp plugin development

Personal Amp plugins live in amp-plugins/*.ts. make install-amp-plugins copies them into ~/.config/amp/plugins/. This repo also includes a local TypeScript declaration refresh so plugin files can import PluginAPI from @ampcode/plugin without publishing or installing a separate package.

make amp-plugin-types        # generate types/ampcode-plugin.d.ts from this Amp CLI
make amp-plugin-check        # refresh plugin types and run TypeScript
make install-amp-plugins     # copy amp-plugins/*.ts into ~/.config/amp/plugins/

After changing a plugin, rerun make install-amp-plugins, then run plugins: reload from Amp's command palette or restart Amp. See amp-plugins/README.md for the plugin development loop and example.

Amp config

Amp settings live in amp-configs/settings.json. make install-configs merges those managed settings into ~/.config/amp/settings.json while preserving any other local Amp settings already present.

Managed install behavior

make install preserves manually installed skills, Amp plugins, Pi extensions, prompts, and themes that live beside dotfiles-managed artifacts. The installer tracks top-level managed names in ~/.local/state/dotfiles/agent-install-manifest.json, overwrites those managed artifacts on each install, and removes managed artifacts that are no longer built. If a built artifact conflicts with an existing unmanaged path, the install fails; rerun the underlying build script with --force only when you want dotfiles to claim that path.

Plugin skills can be restricted to explicit user invocation with skills_user_invocable_only in plugins.toml. The build emits disable-model-invocation: true for Claude and Pi, plus policy.allow_implicit_invocation: false in agents/openai.yaml for Codex. The Codex metadata is included in the Pi/shared build because Codex also scans ~/.agents/skills.

Canonical Pi install

pi-install
pi

• Canonical Pi tool: npm:@earendil-works/pi-coding-agent@latest in global mise config
• pi-install installs or updates Pi through mise, runs make install-configs, and applies pi-configs/pi-patch/ to the mise-managed package root
• pi is provided by mise after installation/reshim

Notable custom skills

• receiving-code-review and fetch-ci-build — vendored superpower skills from buildrtech/dotagents
• babysit-pr — GitHub PR monitoring/babysitting workflow imported from openai/codex commit 7e569f1
• editorial-sketches — editorial article illustration skill vendored from helloianneo/ian-xiaohei-illustrations commit 91b5608
• technical-explainer-comic — evidence-backed technical comic workflow with editorial panels, expandable traces, responsive HTML, browser QA, and static publication
• oracle — @steipete/oracle CLI workflow for second-model reviews with selected repo context
• fable-review — trusted Claude Fable code review workflow using claude -p --model claude-fable-5
• grok-review — safe Grok Build review workflow delegating branch and explicit dirty-tree reviews to Grok's native /review skill
• grok-driver — headless Grok as implementation driver for frozen work orders, with the host agent as coordinator (complement of grok-review)
• review-gauntlet — multi-model review → Fable triage → fix loop via the Grok review-gauntlet workflow / code-review-loop CLI (replaces review-council)
• writing-mike-ruby-style — Mike's personal Ruby/Rails style (mirrors his canonical style rules)
• prepare-branch-context — read-only branch diff, commit, and PR context gathering skill vendored from jnsahaj/skills
• simplify — behavior-preserving code and comment simplification skill vendored from bholmesdev/skills
• zmx — guidance for managing persistent background terminal work
• tmux — remote control tmux sessions through the active server, with an agent-neutral fallback socket when no server is running
• buildr-artifacts — publish browser-viewable Buildr artifacts as static S3-hosted HTML/assets or stateful Vite apps served from Codexbox with bld.run URLs
• socratic-quiz — guided Socratic questioning for deep understanding, vendored from pchalasani/claude-code-tools commit 29ae733

Notable plugin skills

• shaping, breadboarding, and breadboard-reflection — explicit-only product shaping and breadboard workflows from rjs/shaping-skills
• prototype, grill-with-docs, teach, and writing-great-skills — workflow and teaching skills from mattpocock/skills
• improve — codebase audit and self-contained implementation planning skill from shadcn/improve
• impeccable — frontend design, critique, polish, and live iteration skill from pbakaus/impeccable
• thermo-nuclear-code-review — strict structural and architectural code review skill from intercom/2x-skills
• effect — opinionated production Effect v4 guide from kitlangton/skills, pinned as a plugin submodule at commit 30dee860

Notable custom Pi prompt templates

• /bdev-qa - run Buildr bdev qa, diagnose failures, and optionally post results to a PR
• /commit - create a focused Conventional Commit from task-related changes
• /merge-main - merge the latest base branch into the current branch with conflict and verification guardrails
• /open-pr - push the current branch and open a PR with summary and verification
• /pr-comments - fetch PR review comments and evaluate them before changing code
• /review-loop - run a parent-orchestrated adversarial review loop

Notable custom Pi extensions

• handoff and session-query — vendored from buildrtech/dotagents commit a484ad4
• openai-fast — mirrors calesennett/pi-codex-fast; /codex-fast toggles priority service-tier requests for supported OpenAI Codex models, with state stored under pi-codex-fast.enabled in Pi settings
• pi-prompt-shelf — local copy of tanishqkancharla/pi-prompt-shelf; shelves editor prompts per session with shortcuts and /shelf
• pi-codex-conversion — local copy of IgorWarzocha/pi-codex-conversion; adds Codex-style tools and prompt adaptation for OpenAI/Codex models in Pi
• full-read-for-paths — upgrades partial read calls to full reads for configured resource-file paths
• revdiff — adds /revdiff to launch the revdiff TUI and send captured annotations back to Pi

Structure

dotfiles/
├── .config/                 # shell/editor/terminal configs
├── skills/                  # custom agent skills
├── amp-configs/             # managed Amp settings
├── amp-plugins/             # custom Amp plugins
├── pi-extensions/           # Pi extensions
├── pi-themes/               # Pi themes
├── prompts/                 # Pi prompt templates
├── plugins/                 # plugin submodules
├── scripts/build.py         # agent build/install system
├── tests/                   # agent tooling tests
└── Makefile                 # dotfiles + agent commands

Ubuntu notes

Recommended apt packages before or after make dot-all:

sudo apt update
sudo apt install -y fish tmux ripgrep fd-find xclip wl-clipboard xsel fonts-firacode

• Linux clipboard integration in tmux uses the first available tool from: wl-copy, xclip, xsel
• Herdr config is symlinked to ~/.config/herdr/config.toml and uses tmux-like Ctrl-a prefix bindings
• tmux-mem-cpu-load is optional; the tmux status bar falls back to uptime
• Install the configured fonts (Fira Code / FiraCode Nerd Font) if you want terminal rendering to match macOS
• If you prefer one package manager across macOS and Linux, install Homebrew/Linuxbrew and use make dot-install

Notes

If having issues with VIM and paths in macOS:

sudo mv /etc/zshenv /etc/zprofile

See: http://stackoverflow.com/questions/13708719/vim-path-configuration-in-os-x