Dotfiles

Shared terminal configuration for macOS and Fedora 44, managed with chezmoi.

The repository keeps the same shell, editor, version-control, and Pi workflow on both systems. Package versions and install paths may differ by platform. GUI applications and desktop-environment configuration are not part of the shared contract.

Supported platforms

• macOS on Apple silicon or Intel
• Fedora 44 on x86_64

Other Linux distributions, older Fedora releases, Windows bootstrap, Codespaces, and Linuxbrew are unsupported. Bootstrap stops before applying files on an unsupported platform.

Herdr is the sole configured Pi/subagent multiplexer. See ADR-0006. tmux remains available as an interactive terminal tool, not an agent fallback.

Before bootstrap

The Attamusc/pi-hunk-review and Attamusc/pi-lsp repositories are private. Authenticate Git and GitHub CLI before running the dotfiles installer on a new host. The account must be able to clone both repositories and download the pi-hunk-review release assets.

gh auth login
gh auth setup-git
gh auth status --hostname github.com

Install both Git and gh manually first when the new host lacks them. Fedora can use sudo dnf install gh git. On macOS, install the Command Line Tools for Git (xcode-select --install) and install gh through Homebrew when available or GitHub's supported binary distribution. The bootstrap deliberately fails rather than embedding or prompting for a token.

Bootstrap

Clone the repository, enter it, and run:

./install.sh

install.sh verifies the platform, bootstraps chezmoi, and runs the ordered lifecycle:

1. Install Homebrew when it is missing on macOS.
2. Install native packages from packages/Brewfile or packages/fedora.txt.
3. Configure Fedora's login shell and install TPM.
4. Apply managed files.
5. Install the mise-managed language toolchain and Spin.
6. Install the checksum-verified pi-hunk-review core release.
7. Activate Bob's stable Neovim.
8. Reconcile pinned Pi packages and install Herdr's managed Pi integration.

Package-manager, download, checksum, and command-verification failures stop the responsible stage. Re-running ./install.sh resumes the idempotent stages.

Shared command baseline

The shared workflow includes:

• Shell: zsh, Sheldon, Starship, zoxide
• Core CLI: bat, eza, fd, fzf, ripgrep, jq, just, tree, curl, wget, Spin
• Terminal/editor: Herdr, tmux, TPM, Bob-managed Neovim, Helix
• Version control: Git, gh, jj, delta, tig, ghq, git-filter-repo, lazygit, jjui
• Agents: Pi, OpenCode, Copilot CLI
• Runtime: mise-managed Go, Node, npm, npx, Rust, Cargo, and rustc
• Remote shell: mosh

Herdr project launcher

Press Ctrl+B, then F to find a local project with Television. The herdr-project script combines the same ghq list -p project list as cdr with chezmoi source-path, so dotfiles are included even outside the project root. Duplicate paths appear only once. Selecting a project focuses an existing workspace with a pane in that repository, including its subdirectories, or creates a workspace rooted there. Esc cancels. Projects with the same directory name are matched by path, not label.

Clone projects with ghq get owner/repo to include them in the picker. The launcher runs inside Herdr and uses its current session, including named sessions. The popup runs through mise exec so a long-lived server doesn't use stale tool paths after an upgrade.

Package authority

Capability	macOS	Fedora 44
Native terminal tools	Homebrew	DNF
Go, Node, and Rust	mise	mise
Spin	mise Go backend	mise Go backend
Fedora package gaps	—	mise/Aqua
Pi	mise npm backend	mise npm backend
OpenCode V2	Homebrew anomalyco/tap/opencode-v2	mise npm @opencode/cli@2.0.28
Copilot CLI	Homebrew cask	mise npm backend
Datadog Pup CLI and product skills	Homebrew + ~/.agents/skills/	—
Neovim	Bob stable	Bob stable
Neovim parser toolchain	Xcode compiler + Homebrew tree-sitter CLI	DNF GCC + tree-sitter CLI
pi-hunk-review core	Authenticated release archive	Authenticated release archive

Pi's exact version is pinned in dot_config/mise/config.toml.tmpl for both platforms. To upgrade Pi, change that pin, preview and apply the managed mise config, then run mise install npm:@earendil-works/pi-coding-agent. Use mise for Pi itself, not pi update or a separate global npm install. Pi extension package pins are separate and reconcile only through the per-package setup hook.

The shared mise configuration sets upgrade.auto_prune = false to disable removal scheduling by mise upgrade. Machine-local settings or environment variables can override that default. Deferred removals created by earlier upgrades can still run during ordinary mise commands. Declare required older versions in machine-owned ~/.config/mise/config.local.toml before restoring them. Optional runtimes are not part of the shared auto-install baseline; see Machine-local overlays for retention and default-selection rules.

Bob keeps previously installed Neovim versions as the rollback lane. Removing a package from a manifest does not uninstall it from an existing host.

Machine-local configuration

Ignored local files extend the public baseline without publishing work or machine-specific values:

• .data-private/ — private Pi/MCP settings merged by chezmoi
• .local-skills/ — untracked skills linked into the active skill roots
• ~/.gitconfig.local — credentials, signing, and work-host Git settings
• ~/.localrc — shell additions loaded after shared zsh configuration

These files are not synchronized or backed up by this repository. Back them up separately if they are needed to rebuild a machine. See Machine-local overlays for merge semantics and safe examples.

Specialist packages are also machine-owned: cloud/Kubernetes CLIs, container engines, additional language toolchains and language servers, QMK, Ollama, and OCR/media tooling are outside the automatic shared install baseline. Language-server-backed Pi packages follow the same policy: installing a capability does not guarantee its server executables. See ADR-0008 for the standalone LSP package boundary and optional-server decision.

The pinned pi-lsp 0.3.0 package supports TypeScript/JavaScript, Rust, and Ruby through one tool (contract v3): definitions, references, hover, workspace symbols, and explicit diagnostics where the selected backend supports them. Diagnostics do not run automatically after edits. Rust diagnostics are partial native snapshots, not cargo-check results; Ruby diagnostics are syntax-only and its references are best-effort.

All server runtimes remain optional and machine-owned. TS/JS need typescript-language-server plus TypeScript. Rust needs the tested standalone analyzer and a compatible toolchain/rust-src; Ruby needs an absolute Ruby executable and a dedicated preinstalled gem environment. Ruby's normal Bundler launcher and workspace add-ons are not used. See the package README for exact versions, setup, limits, and PI_LSP_RUST_* / PI_LSP_RUBY_* settings. None are installed by the shared bootstrap. Slow starts can use PI_LSP_TIMEOUT_MS=30000 pi (default 10,000 ms; maximum 120,000 ms).

Datadog is the macOS exception: the official Pup CLI and pinned dd-docs, dd-pup, dd-audit, and dd-apm skills are installed for Pi and OpenCode. Pup defaults to enforced read-only mode, and OAuth credentials remain in Pup's secure machine-local storage. Fedora renders none of this Datadog configuration.

Optional native LSP setup through chezmoi

Native runtime setup is defined here, not by edits to generated home files:

• dot_config/pi-lsp/runtimes.json pins versions, artifact URLs, and SHA-256 hashes.
• dot_local/bin/executable_pi-lsp-setup installs verified runtime artifacts on explicit invocation; no bootstrap hook invokes it.
• dot_local/bin/executable_pi-lsp-rust-analyzer.tmpl selects Rust 1.97.1 only for the analyzer and its children, without changing the shell's toolchain choice.
• dot_config/private_zsh/config/pi-lsp.zsh.tmpl configures Pi's runtime paths and a 30-second LSP deadline through the existing zsh loader.

The setup command requires already-installed Rust 1.97.1, mise-managed Ruby 4.0.1, curl, Python 3, make, and a C compiler for the RBS gem. It does not install toolchains or change their global selection. If needed, provision them explicitly first:

rustup toolchain install 1.97.1 --profile minimal --no-self-update
mise install ruby@4.0.1

Preview and apply only these managed files, then run the opt-in installer:

chezmoi diff --exclude=scripts ~/.config/pi-lsp \
  ~/.config/zsh/config/pi-lsp.zsh ~/.local/bin/pi-lsp-rust-analyzer ~/.local/bin/pi-lsp-setup
chezmoi apply --exclude=scripts ~/.config/pi-lsp \
  ~/.config/zsh/config/pi-lsp.zsh ~/.local/bin/pi-lsp-rust-analyzer ~/.local/bin/pi-lsp-setup
pi-lsp-setup

Artifacts are stored in versioned directories under ~/.local/share/pi-lsp/. The installer verifies downloads before use, isolates Ruby gems from project and user Bundler state, and verifies installed files on reruns. It refuses corrupt or unowned existing targets rather than overwriting them. A pin change that retains the same version-directory name also requires moving that directory aside explicitly before rerunning setup. Source changes belong in this repository; installed artifacts are outputs, not configuration to edit.

Open a fresh shell and start a new Pi process after setup. /reload refreshes extensions but cannot import environment changes into an existing process. Neither the global Ruby gem set nor the ordinary Rust default is changed.

Restart idle Pi peers in Herdr

pi-restart-all previews idle/done Pi peers; pi-restart-all --apply --confirm-empty-editors restarts those peers sequentially. Run inside Herdr with HERDR_ENV=1 and HERDR_PANE_ID set. The calling pane is always excluded. Restrict an approved batch with repeatable --pane 'w1:p1' arguments on both preview and apply. Every selected peer is preflighted before any quit; apply rechecks each identity.

Use apply under supervision: a failure can leave a peer at its shell, requiring manual recovery.

Before applying, confirm that target sessions are at normal chat prompts with empty input editors. Herdr cannot inspect unsent drafts: pasting /quit into a draft could submit it instead of quitting. The helper requires your explicit --confirm-empty-editors acknowledgement and never clears input buffers.

Herdr alone submits /quit and starts Pi in the same pane with the exact saved --session path. A read-only local ps -p PID -o pid= check supplements Herdr's foreground snapshot: the original shell/cwd must return and the old PID must be absent before startup. Within that same exit deadline, the helper also waits for Herdr to clear the old agent/session record and for its name lookup to report agent_not_found. Process exit alone does not prove that Herdr released the name. Background/suspended processes and ambiguous errors stop the run; no signals, trust approvals, layout changes, or automatic retries are used. All Herdr and ps queries are local to the inherited server context; there is no --machine support. Exit, start, and readiness stages default to 30 seconds each (--timeout overrides the stage deadline). Transient foreground children from prompt hooks or startup are waited out; actions still require a verified single foreground process. Session paths containing spaces or shell metacharacters are rejected before quitting because Herdr's shell quoting has not been verified here.

This resumes the saved conversation with currently installed configuration, not invisible original process-only flags or restrictions. Each restarted agent is named restart-<16 hex digits>; any original agent name is not preserved. Default mode includes every eligible Pi peer; it cannot identify persistent controlled peers or name-based coordination. Review the preview before every apply. If those peers are present, use a --pane allowlist containing only the standalone sessions you intend to restart. Do not select controlled or name-coordinated peers. Session contents are never read. On failure, inspect the reported stage, completed count, and recovery identity before taking manual action: a failed or timed-out submission may have occurred. Native Herdr errors include the exit status and bounded, escaped code/message fields; unrelated response fields and unstructured stderr are not dumped. Preview is not a reservation, and apply fails closed if an identity changes.

Fixture-only smoke check (stubs both Herdr and ps; no live session queries):

python3 tests/herdr/test-pi-restart-all.py

Preview and apply

Run the non-mutating repository contract check first:

scripts/check-portability.sh

Then inspect managed host changes:

chezmoi status
chezmoi diff

Apply only after reviewing the diff:

chezmoi apply

The portability check renders isolated macOS and Fedora configurations. It does not install packages or apply home-directory state. Negative tests run only in temporary repositories, and protected ignored state is compared before and after mutation-capable phases.

Pi verification and workflows

The managed Phase 1 verification bundle provides five shared actions for scoped verification, project check definitions, maintenance, impact analysis, and live CLI control. See Pi verification bundle for action selection, evidence semantics, privacy, ownership, unsupported capabilities, and provenance.

The exact pi-workflows package pin and all ten saved workflow dispositions are documented in Pi workflows. The pin remains unapplied until independent gates pass; activation and live smoke are user-only steps.

Observational workstation readiness

From this repository, run the filesystem-only report without installing a helper:

python3 -I -S -B scripts/workstation-readiness.py
python3 -I -S -B scripts/workstation-readiness.py --json

It checks executable candidates and supported-platform metadata without running commands, reading private settings, or changing files. Exit 0 means the required observations are clear; exit 1 means missing/unsupported; exit 2 means inconclusive or an input/internal error. Optional LSP gaps do not fail the baseline.

Presence does not prove compatible versions, configured pins, authentication, package activation, server readiness, or working editors/Herdr. Those checks remain manual. See the readiness contract for privacy boundaries, fixed output fields, and limits. Isolated Python startup ignores environment/site hooks; a trusted interpreter remains a prerequisite.

Focused smoke checks

After apply, open a fresh terminal or reconnect over SSH, then run these in that new login shell:

command -v herdr nvim hx pi opencode copilot gh jj just tv mosh spin go cargo rustc node npm npx
command -v nvim
nvim --headless '+qa'
pi list
gh auth status --hostname github.com
if [[ $(uname -s) == Darwin ]]; then command -v pup; fi

Start Pi inside Herdr, open one child agent in a visible pane, then detach and reattach before considering a new host complete. Fedora runtime and SSH detach/reattach must be verified on the real machine; the Ubuntu-hosted static portability contract check is not a substitute.

Rollback

Configuration rollback is version-control-based: revert the relevant commit and review chezmoi diff before applying it. Do not keep fallback package entries or runtime compatibility shims in the public configuration.

For Neovim, select a previous Bob-managed version with bob use <version>. Package removal and credential changes remain explicit manual operations.