Dotfiles

Development environment configuration for macOS and AWS devbox (Ubuntu), managed with GNU Stow.

• ghostty - GPU-accelerated terminal emulator
• zsh - Shell with Oh My Zsh, Powerlevel10k, and plugins
• tmux - Terminal multiplexer with Catppuccin theme and TPM
• neovim - LazyVim distribution with AI coding assistance
• aerospace - Tiling window manager for macOS
• starship - Cross-shell prompt
• herdr - Agent-aware terminal multiplexer used by Neovim Sidekick
• gh-dash - GitHub dashboard with Herdr pull-request worktree integration
• tuicr - Vim-first terminal code review with agent-aware sessions
• hunk - Review-first diff viewer with live agent annotations
• omarchy - User theme overrides for Omarchy/Hyprland

Setup

Option A: macOS (local)

git clone https://github.com/aviralmansingka/dotfiles ${HOME}/dotfiles
cd ${HOME}/dotfiles/
./install.sh

The script installs dependencies via Homebrew, deploys configurations with stow, sets up shell plugins, installs Neovim via bob, and installs pinned Herdr Flash, Annotate Lite, and a pinned, patched local reviewer. A failed reviewer build or missing Flash executable stops the installation.

Ctrl+a f opens Herdr Flash: search visible pane text, jump by label, select with v/V and Vim motions, then yank with y. This supplements built-in copy mode (Ctrl+a [ or Ctrl+a i); it does not provide Neovim text objects or full-scrollback search.

For manual package and configuration deployment (excluding installer-managed integrations and plugins):

brew bundle
gh extension install dlvhdr/gh-dash
stow nvim tmux zsh ghostty git starship gh-dash tuicr agents pi herdr launchd
stow --no-folding hunk

On Linux (systemd) systems, deploy the user services with:

stow systemd

On Omarchy systems, deploy the user Omarchy theme overrides with:

stow omarchy

For a minimal stow deployment without agent configuration, omit agents and pi.

Option B: AWS Devbox

A fully provisioned Ubuntu 24.04 EC2 instance with all tools pre-installed. AMIs are built with Packer and the instance is managed with Terraform.

Prerequisites: AWS credentials configured, Terraform installed, an SSH key pair.

cd ops/devbox
terraform init
terraform apply \
  -var="devbox_enabled=true" \
  -var="ssh_public_key=$(cat ~/.ssh/id_ed25519.pub)"

Then SSH in:

ssh aviralmansingka@$(terraform -chdir=ops/devbox output -raw devbox_public_ip)

The devbox comes with: zsh + Oh My Zsh, tmux + TPM, Neovim via bob, Rust toolchain, Go, Node.js, Python, kubectl, k9s, lazygit, Claude Code, and all dotfiles stowed.

To tear down:

terraform -chdir=ops/devbox destroy \
  -var="devbox_enabled=true" \
  -var="ssh_public_key=$(cat ~/.ssh/id_ed25519.pub)"

Stow Packages

Package	Description
aerospace	AeroSpace tiling window manager
agents	Shared agent skills
blinksh	Blink Shell (iOS terminal) config
claude	Claude AI context files
code	Code snippets (Golang, Lua)
ghostty	Ghostty terminal emulator
gh-dash	GitHub dashboard config and PR worktree launcher
herdr	Agent workspaces, notifications, and sound configuration
hunk	Review-first terminal diff configuration
git	Git configuration
kube	Kubernetes configuration
launchd	macOS user LaunchAgents (vault and dotfiles auto-sync)
neovide	Neovide (Neovim GUI) config
nvim	Neovim with LazyVim
omarchy	User Omarchy theme overrides
starship	Starship prompt
systemd	User systemd units (vault/dotfiles auto-sync, Pi/WhatsApp/Telegram bridges, flight check-in reminders)
pi	Pi agent config, packages, themes, and messaging daemons
terminfo	Custom terminfo entries
tmux	Tmux configuration
tmuxinator	Tmuxinator session templates
tuicr	Terminal pull-request review configuration
zsh	Zsh shell configuration

gh-dash PR worktrees

Run ghd to open gh-dash. In the pull-request view, press H to review the selected PR's diff in Hunk; quitting Hunk returns to gh-dash. The stowed config resolves owner/repo to /Users/aviral/:repo. Press O to check out the selected PR as pr/<number> in a Herdr worktree, focus it, and start tuicr in the new worktree. Pressing O again focuses the existing workflow-owned worktree; a conflicting local branch is left untouched.

Sidekick / Herdr view sizing

Sidekick releases its local writable Herdr attachment on Neovim FocusLost and reattaches the same running agent on FocusGained. Herdr can then size the agent for its own pane, including its sidebar and splits; returning to Neovim sizes it for the Sidekick window. Hidden Sidekick windows also release their attachments. Views in other Neovim tabs reopen when you return while the tab still exists. A tab whose Sidekick view was its only window closes during handoff and is not restored. No durable agent is stopped or restarted.

If your terminal does not forward focus events, run :SidekickRelease before switching to Herdr, then use <C-.> or the session picker to reopen the view in Neovim. Manual release cancels automatic reopening. Handoff recreates the local terminal buffer, so local scrollback/selection is not retained; the server-owned agent and its conversation remain running. This is a direct-client detach/reattach workaround, not the planned Herdr attachment-lease controller. Float size remains unchanged at 80%; the active surface owns the actual grid.

Regression check (installed Sidekick required; no live Herdr calls): nvim --headless -u NONE -l scripts/test-sidekick-view-focus.lua.

Herdr scrollback in Neovim

Ctrl+a e opens the focused pane's scrollback through $EDITOR (currently bob run stable; that version must be installed). helpers/herdr_scrollback.lua recognizes Herdr's temporary files and re-captures the original pane via HERDR_ACTIVE_PANE_ID using ANSI, unwrapped output.

Tree-shaped rows are grouped into ansi fences; prompts and output remain ordinary text outside them. The capture is stored in ~/.local/share/herdr/captures/conversation-<hash>.md (respecting XDG_DATA_HOME). The hash uses Herdr's reported conversation identity, not the pane, timestamp, or worktree: each capture updates the same file for that conversation. Missing or changing conversation identity aborts the capture rather than mixing unrelated sessions.

Neovim decodes ANSI to highlights so hidden bytes do not break wrapping or contaminate yanks. :write serializes tree colors back into the Markdown file; reopening a saved capture works without a running Herdr session. Files are private (0600), written atomically, and survive :q. Saving stale edits refuses to overwrite a newer capture unless explicitly forced with :write!. A fresh capture replaces the previous snapshot, including manual edits; save annotations separately.

Soft wrapping follows each window's width. Terminal padding is removed, but indentation and hard line breaks remain. This is a terminal snapshot, not a reconstructed transcript: it cannot undo application-inserted line breaks or recover discarded history. Only capture buffers get wrapping overrides and disabled diagnostics/modelines. Failed reads leave the previous capture intact.

Checks: scripts/verify-nvim herdr-scrollback and scripts/verify-nvim markdown-ansi.

Herdr Annotate pilot

./install.sh installs upstream Annotate Lite for terminal comments and a separate local annotate-review plugin for Markdown/reply reviews. The local reviewer adds syntax highlighting and mouse-hover y to copy a whole code block; upstream plugin updates cannot replace it. Rebuild with ./scripts/install-herdr-annotate. See the installation and update runbook.

Key	Action
prefix+a	Annotate terminal text
prefix+Shift+a	Copy annotations as agent context
prefix+m	Manage annotations
prefix+o	Review Markdown changed from local main
prefix+Shift+o	Review the last agent reply

Herdr server handoff

When replacing a Herdr server from a Codex tool subprocess, run:

herdr-clean-handoff

This performs a live handoff, preserving the repository workspace, exact worktree pane, and resumed Codex session. It removes Codex's inherited NO_COLOR only from the replacement Herdr server; the invoking process and its other subprocesses keep their existing environment.

Git auto-sync services

The shared implementation is scripts/auto-git-sync. It fetches and merges the remote branch before committing local edits, then asks Pi to resolve Git conflict files if a merge or stash apply leaves conflicts.

Manage Linux user services:

systemctl --user daemon-reload
systemctl --user enable --now vault-auto-sync.service dotfiles-auto-sync.service
systemctl --user status vault-auto-sync.service dotfiles-auto-sync.service

Manage macOS user agents:

stow launchd
launchctl bootstrap "gui/$UID" ~/Library/LaunchAgents/com.aviral.vault-auto-sync.plist
launchctl bootstrap "gui/$UID" ~/Library/LaunchAgents/com.aviral.dotfiles-auto-sync.plist
launchctl print "gui/$UID/com.aviral.vault-auto-sync"
launchctl print "gui/$UID/com.aviral.dotfiles-auto-sync"

Pi agent

Pi config and shared skills are deployed with:

stow pi agents

The shared vault skill supports explicit project and knowledge-base lookup, note summaries, project overviews, and Wayfinder overviews. It preserves the vault's Project → Theme → Feature → Task ontology without installing an execution workflow. Neovim's <leader>vf picker remains a read-only navigation surface for active vault work.

Use /hunk to open or focus a watched Hunk diff in a sibling pane. In Herdr, the sibling pane closes automatically when Hunk exits. Opening Hunk never starts a review. When you want an isolated asynchronous review, run /hunk-review [focus]; detailed findings are anchored in Hunk and only a terse completion summary returns to the parent session.

The checked-in Pi config intentionally excludes auth.json, sessions, caches, and runtime state. MCP credentials should be provided out of band.

Install/update Pi packages and the local web-fetch dependencies:

cd ~/.pi/agent/npm && npm install
cd ~/.pi/agent/extensions/web-fetch && npm ci --ignore-scripts

Pi surfaces No Mistakes runs in the shared activity widget without replacing the attached TUI. See the interactive-subagents status documentation for display, scoping, and fallback behavior.

In Herdr-backed TUI sessions, an active Pi UI prompt reports the agent as blocked until the prompt closes, so Sidekick shows that Pi is waiting for user input.

For Pi over WhatsApp, copy ~/.config/pi-whatsapp.env.example to ~/.config/pi-whatsapp.env, fill in the allowed chat IDs, then enable the user services:

systemctl --user daemon-reload
systemctl --user enable --now whatsapp-bridge.service pi-whatsapp.service

For Pi over Telegram, create a bot with @BotFather, copy ~/.config/pi-telegram.env.example to ~/.config/pi-telegram.env, fill in the bot token and allowed chat IDs, and set PI_TELEGRAM_PREFIX= if you want normal prefixless chat. Telegram replies default to openai-codex/gpt-5.6-luna:high via PI_TELEGRAM_MODEL, with PI_FAST_MODE=1 selecting the priority service tier; PI_TELEGRAM_TYPING_INTERVAL_SECONDS controls the typing indicator refresh while Pi is generating. Photos/screenshots and image documents are downloaded and passed to Pi as image attachments; captions follow the existing prefix rules, while bare images are accepted. PI_TELEGRAM_MAX_IMAGE_BYTES (default 10 MiB) caps the accepted size. Then enable the user service:

systemctl --user daemon-reload
systemctl --user enable --now pi-telegram.service

The flight-checkin-reminders.timer user unit (every 12h) scans Gmail for upcoming flight check-in windows via Pi and sends Telegram reminders. It runs %h/vault/scripts/flight-checkin-reminders.py through an explicit /usr/bin/python3 because the vault checkout does not guarantee the executable bit; direct execution fails with status=203/EXEC. Enable it with systemctl --user enable --now flight-checkin-reminders.timer.

Retired reminder timers, kept out of the tracked units on purpose:

• honeymoon-message-drafts.timer — built for the July 2026 honeymoon message plan; the trip is over, so the live unit was retired (see the disable/remove commands in the PR that tracked these notes).
• aug18-trip-flight-reminder.timer — its script self-disables after its 2026-08-18 cutoff; remove the live unit after that date.

Infrastructure

AMIs and cloud infrastructure are managed in ops/:

• Packer (ops/packer/) - Builds Ubuntu 24.04 devbox AMIs with full development toolchain
• Terraform (ops/terraform/) - Manages shared AWS infrastructure (IAM, DNS, GitHub OIDC)
• Devbox (ops/devbox/) - Manages the devbox EC2 instance

CI/CD workflows automatically build AMIs and apply infrastructure changes on push to main.

LICENSE

Copyright (c) 2012-2022 Scott Chacon and others

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.