dotfiles

Terminal setup for agentic engineering: Ghostty + Starship + zsh, wired up for Claude Code and pi.

Install

git clone https://github.com/npatten/dotfiles.git ~/dotfiles
cd ~/dotfiles
./install.sh

Then set your identity in ~/.gitconfig.local and open a fresh Ghostty window.

The installer is idempotent — re-run it any time. Anything it would overwrite gets moved to ~/.dotfiles-backup/<timestamp>/ first.

Installing only some of it

Bare ./install.sh installs everything. To take just the terminal setup and leave the agent configs alone:

./install.sh --skip claude,pi        # everything except those groups
./install.sh --only shell,terminal   # only those groups
./install.sh --list                  # show the groups

Group	What it links
brew	Homebrew, then everything in the Brewfile (--no-brew still works)
shell	zshrc, zshenv, zprofile, and the ~/.zshrc.local stub
terminal	starship prompt, ghostty config
git	gitconfig, global ignore, and the ~/.gitconfig.local stub
tools	mise (node version), eza theme
scripts	newai → ~/.local/bin
claude	Claude Code statusline, keybindings, settings.json
claude-hooks	the .env guard + dangerous-git hooks
pi	pi AGENTS.md and settings.json

claude-hooks is a subset of claude, so you can keep the statusline without the guardrails — --skip claude-hooks also strips the hooks block out of the copied settings.json, since leaving it in would point Claude Code at a hook script that isn't there. Skipping claude skips the hooks too.

It only narrows in --skip, though. The hooks are configured inside settings.json, which belongs to claude and also points at the statusline script, so they can't install on their own — --only claude-hooks pulls the parent in and is just a longer way of writing --only claude.

A selection that resolves to nothing (--only shell --skip shell, or skipping every group) is an error rather than a silent no-op.

What you get

Piece	Notes
Ghostty	Ayu Mirage, JetBrains Mono Nerd Font 15pt, quick terminal on `ctrl+``
Starship	Two-tone powerline prompt, git branch/status, command duration, clock
zsh	Shared history, autosuggestions (Tab accepts), syntax highlighting, fzf, zoxide
Claude Code	Statusline matching the Starship palette, .env guard hook, dangerous-git hook
pi	Codex provider, model list, AGENTS.md style guide
newai	One command to bootstrap a new AI project — see below

The prompt draws a dim ─ ─ ─ separator line between commands. That's precmd() in shell/zshrc — delete it if you hate it.

$EDITOR is VS Code if code is on your PATH, otherwise nano — VS Code isn't in the Brewfile, so on a clean machine you get nano until you install one. Set your own in ~/.zshrc.local and it wins either way.

newai — bootstrap a project

newai my-project              # creates ~/Projects/my-project, opens your GUI editor
newai my-project --no-open    # skip the editor
newai my-project --root ~/work

It seeds AGENTS.md (with CLAUDE.md and GEMINI.md symlinked to it, so every agent reads the same instructions), runs git init, and sets up clew for work tracking. The seeded AGENTS.md ends with a setup-interview section: point Claude Code or pi at the fresh project and it walks you through scoping it, then deletes that section.

Set NEWAI_ROOT in ~/.zshrc.local to change the default project directory. Noisy setup output lands in setup.log inside the new project; it's safe to delete.

Key bindings worth knowing

• Tab — accept the ghost-text autosuggestion if there is one, else complete
• Ctrl-R / Ctrl-T / Alt-C — fzf history / files / dirs
• `Ctrl-`` — Ghostty quick terminal (global, works from any app)
• z <partial-dir> — jump to a directory you've visited before
• In Claude Code: Ctrl-L model picker, Ctrl-K clear input

Layout

shell/      zshrc, zshenv, zprofile, zshrc.local.example
starship/   starship.toml
ghostty/    config.ghostty
git/        gitconfig (shared), ignore
claude/     settings.json, statusline, keybindings, hooks/
pi/         settings.json, AGENTS.md
bin/        newai            -> symlinked to ~/.local/bin
share/      agents-template.md (seeded by newai)
mise/       config.toml (node version)
eza/        theme.yml

Skills (not included)

Third-party Claude Code skills aren't vendored here — clone them yourself so you get updates and the original license:

git clone https://github.com/mattpocock/skills.git ~/Projects/skills
ln -s ~/Projects/skills/skills/productivity/teach ~/.claude/skills/teach

Note that Claude Code now ships research and comparison-chart as built-ins, so you don't need to install those separately.

Most files are symlinked from this repo into $HOME, so editing them here takes effect immediately and the repo never goes stale.

The two exceptions are claude/settings.json and pi/settings.json, which are copied, not linked. Both apps rewrite their own settings file at runtime (the Claude model picker, pi's changelog tracker), which would either clobber a symlink or silently drift the repo. Copies keep that blast radius contained. Re-running install.sh won't overwrite your local edits unless you pass --force-settings. If you change something in those files and want it in the repo, copy it back by hand.

The local-override pattern

Nothing personal lives in this repo. Two gitignored files hold anything machine-specific, and both are sourced/included automatically if present:

• ~/.zshrc.local — secrets, API key loaders, host aliases, editor choice. Start from shell/zshrc.local.example.
• ~/.gitconfig.local — your name and email.

If you're adding to this repo, ask: would this be wrong on someone else's machine? If yes, it goes in a .local file.

Prerequisites the installer handles

Homebrew, then everything in Brewfile. The agents themselves are npm packages and are not in the Brewfile, because each needs an interactive login:

npm i -g @anthropic-ai/claude-code      # then: claude
npm i -g @earendil-works/pi-coding-agent # then: pi

Neither this repo nor the installer carries credentials. ~/.pi/agent/auth.json and ~/.claude.json are deliberately excluded — log in yourself.