dotfiles

Personal dotfiles for macOS, Omarchy, and Ubuntu 24.x. Machine setup is declared in mise.toml plus mise.home.toml or mise.omarchy.toml, and applied with mise 2026.9.2+. Omarchy setup does not use Homebrew and leaves Omarchy-owned terminal/theme files alone.

Quick Start

Install mise 2026.9.2+ first (curl https://mise.run | sh).

macOS / Ubuntu 24.x

git clone https://github.com/mikeastock/dotfiles.git ~/code/personal/dotfiles
cd ~/code/personal/dotfiles
make install
make dotfiles

make install installs agent skills, prompts, themes, extensions, and Amp plugins. make dotfiles (or make install DOTFILES=1) applies machine files with mise -E home bootstrap: shared links, Ghostty/Alacritty/Starship, brew packages (tmux, tmux-mem-cpu-load, tree-sitter-cli), and macOS screenshot defaults (skipped on Linux).

Omarchy

git clone https://github.com/mikeastock/dotfiles.git ~/code/personal/dotfiles
cd ~/code/personal/dotfiles
make install
make dotfiles

On Omarchy, make dotfiles (or make install DOTFILES=1) uses mise -E omarchy bootstrap --force-dotfiles. It claims home/config links around existing Omarchy files, installs fish and atuin with omarchy pkg add, and switches the login shell to fish. It leaves Ghostty, Alacritty, and Starship on Omarchy's copies, and removes ~/.config/tmux/tmux.conf so ~/.tmux.conf is the only tmux config. A post-update hook drops that XDG file again if omarchy update puts it back.

Do not run Update → Config → Tmux in the Omarchy menu. Log out once after the first install so the fish login shell applies.

A bare mise dot apply from this repo skips the environment-specific files. Unapply with make dotfiles-clean (or scripts/dotfiles.sh clean).

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
• mise 2026.9.2+ for machine files applied by make install

Agent commands

make install                 # agent artifacts only (skills, prompts, themes, extensions, Amp plugins)
make install DOTFILES=1      # agent artifacts plus machine dotfiles (auto-detects Omarchy)
make dotfiles                # machine dotfiles only (auto-detects Omarchy)
make dotfiles-clean          # remove machine dotfile links
make install-skills
make install-amp-plugins
make install-prompts
make install-themes
make install-extensions
make build                   # build agent artifacts only
make clean                   # clean agent build/install artifacts
make plugin-update           # update plugin submodules

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.

bb plugin development

Forked bb plugins live in bb-plugins/<plugin>/, vendored as plain source so they can be modified in place. They are not part of make install; bb loads each one directly from its path in this repo.

cd bb-plugins/bb-plugin-tok-speed
npm install
bb plugin install "$PWD" --yes    # register with bb (once)
npx bb plugin dev                 # watch sources, hot-reload the frontend

A plugin's bb id is its package.json name with the bb-plugin- prefix stripped, and its data lives in ~/.bb/plugins/<id>/, so renaming the package orphans that data. Backend changes (src/server.ts) need npm run build && bb plugin reload <id>. Each plugin keeps upstream pointing at the repo it was forked from; sync by diffing against that remote. Run bb plugin types in the plugin directory after upgrading bb to repin @get-bb/plugin-sdk to the running version.

• bb-plugin-tok-speed — shows a visible provider-output tok/s figure in each assistant message's hover menu. Forked from patleeman/bb-plugins at e275465, with thread-event pages capped at 100 (bb's server limit) instead of 500. Pi threads are measured from the Pi session file bb's Pi bridge writes, because bb prunes the per-turn usage and stream timing from its event log; see bb-plugins/bb-plugin-tok-speed/README.md.
• bb-plugin-t3sidebar — the earlier fork of SawyerHood/bb-plugin-t3sidebar, kept for its auto-settle-on-merge sweep.

Amp / Codex / OpenCode / Pi configs

These are copied by make dotfiles (or make install DOTFILES=1):

• .config/amp/settings.json → ~/.config/amp/settings.json
• .config/opencode/opencode.jsonc → ~/.config/opencode/opencode.jsonc
• .codex/config.toml → ~/.codex/config.toml
• configs/AGENTS.md → ~/.codex/AGENTS.md and ~/.pi/agent/AGENTS.md
• .pi/agent/models.json → ~/.pi/agent/models.json
• .pi/agent/settings.json → ~/.pi/agent/settings.json

OpenCode keeps {env:MODEL_API_KEY} and {env:RUNINFRA_GATEWAY_KEY} in git. A later apply overwrites the live files; capture local edits with mise dot add first. The default OpenCode model is meta/muse-spark-1.2.

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. Custom skills use metadata.user-invocable-only: true in SKILL.md. 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.

Pi

Pi itself is the official experimental managed install under ~/.pi:

curl -fsSL https://pi.dev/install.sh | PI_EXPERIMENTAL=1 sh
pi update

Pi settings and models are copied by make install. Extensions, prompts, and themes install in the same command. pi-configs/pi-patch/ is an optional Ghostty/tmux image patch for the managed Pi install.

Notable custom skills

• agent-browser — fast browser automation CLI for AI agents with CDP accessibility tree snapshots and refs, vendored from vercel-labs/agent-browser commit 44583ac
• before-and-after — attach screenshots and screen recordings to GitHub PR descriptions with formatted Markdown tables and video players, vendored from vercel-labs/before-and-after commit 8306d34
• ui-recording-timeline — turn UI screen recordings into interactive paint timelines with change and movement overlays, vendored from rauchg/skills commit 40f2a05 (requires uv and ffmpeg; Chrome/Chromium for previews)
• 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
• fable-review — trusted Claude Fable code review workflow using claude -p --model claude-fable-5-1
• 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)
• writing-mike-ruby-style — Mike's personal Ruby/Rails style (mirrors his canonical style rules)
• writing-pr — concise PR titles and bodies with diagrams, code examples, and before/after evidence
• reddit-search — Reddit community opinions through Gemini Google Search grounding, with resolved thread links and explicit summary attribution (GEMINI_API_KEY, Python stdlib only)
• prepare-branch-context — read-only branch diff, commit, and PR context gathering skill vendored from jnsahaj/skills
• simplify — code and comment simplification skill vendored from bholmesdev/skills, extended to cut over-engineering and needless defensiveness (explicit invocation only)
• unslop — AI-writing cleanup and human-voice editing skill vendored from cursor/plugins commit 99559f2 (explicit invocation only)
• zmx — guidance for managing persistent background terminal work
• skill-doctor — grade installed skills from real local sessions, then draft skill edits and a report; adapted from warpdotdev/common-skills with the collector rewritten on a bundled Letta trajectory pipeline (each run builds its own throwaway data root: scripts/ingest.sh pnpm-installs @letta-ai/trajectory with a bundled grok-build patch and normalizes recent sessions from every local agent into it) (explicit invocation only)
• 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
• eli5 — dead-simple HTML picture explainer for any topic, vendored from anthropics/claude-plugins-community (eli5@claude-community) commit 863e70d
• bro — restate the last message in plain human language, vendored from dmmulroy/skills commit cbd1929 (explicit invocation only)
• product-description — outside-in, feature-by-feature behavior spec of a product from its code and tests, vendored from steveruizok gist 83ae5c53 revision f9435a3

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
• better-github-skill — agent-optimized gh workflows (PR snapshot, review threads, CI failures) from AVGVSTVS96/better-github-skill
• show-me — concise visual explanations (diagrams, code-shape sketches, HTML artifacts) from humanlayer/skills

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
• /refactor-pass - simplify recent changes
• /simplify - design a simplification plan before implementation

Notable custom Pi extensions

• wafer — Wafer Serverless provider with eight catalog models, reasoning controls, and WAFER_API_KEY authentication

• handoff and session-query — vendored from buildrtech/dotagents commit a484ad4

• openai-fast — OpenAI Fast and Ultrafast service tiers; /openai-fast [off|fast|ultrafast|status] selects speed for supported openai models, with --fast/--ultrafast startup flags and inline ⚡/⚡⚡ indicators. Settings use openai-fast.mode; replaces the Codex-only command and boolean setting.

• pi-prompt-shelf — local copy of tanishqkancharla/pi-prompt-shelf; shelves editor prompts per session with shortcuts and /shelf

• 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/agent configs
├── .codex/                  # Codex user config
├── .pi/agent/               # Pi settings and models
├── mise.toml                # shared mise dotfiles + bootstrap
├── mise.home.toml           # macOS/Ubuntu terminals and brew packages
├── mise.omarchy.toml        # Omarchy-only links, bashrc block, login shell
├── skills/                  # custom agent skills
│   ├── agent-browser/       # fast browser automation CLI for AI agents
│   ├── before-and-after/    # GitHub PR screenshot and video formatting
│   ├── reddit-search/       # Gemini-grounded Reddit search and thread resolution
│   ├── ui-recording-timeline/ # interactive UI recording paint timelines
│   └── writing-pr/          # PR title and body guidance
├── configs/                 # shared AGENTS.md for Codex and Pi
├── amp-plugins/             # custom Amp plugins
├── pi-extensions/           # Pi extensions
│   └── wafer/              # Wafer Serverless model provider
├── pi-themes/               # Pi themes
├── prompts/                 # Pi prompt templates
├── plugins/                 # plugin submodules
├── bb-plugins/              # forked bb plugins
├── scripts/build.py         # agent build/install system
├── scripts/dotfiles.sh      # mise bootstrap wrapper
├── tests/                   # agent tooling tests
└── Makefile                 # dotfiles + agent commands

Ubuntu notes

Recommended apt packages before or after make install:

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
• On macOS/Ubuntu, make dotfiles (or make install DOTFILES=1) installs tmux, tmux-mem-cpu-load, and tree-sitter-cli through mise's brew bootstrap packages

Omarchy notes

• Hyprland config lives in .config/hypr and is claimed on Omarchy
• Ghostty, Alacritty, and Starship stay on Omarchy so theme switches keep working
• tmux is only ~/.tmux.conf; the installer removes ~/.config/tmux/tmux.conf and installs .config/omarchy/hooks/post-update.d/drop-omarchy-tmux.hook
• Conflicting whole-file targets are replaced (mise bootstrap --force-dotfiles); inspect mise dot diff first if you need to keep a local copy

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