dotfiles

Personal shell and terminal setup.

Includes

• zsh_stuff
• AGENTS.md
• CLAUDE.md
• config/agents/AGENTS.md
• config/agents/pipelines/
• config/claude/agents/
• .ignore
• .tmux.conf
• config/nvim
• config/atuin
• config/starship/starship.toml
• config/git/ignore
• config/ghostty/config.ghostty
• config/lazygit/config.yml
• config/codex/tmux-hooks.json
• config/claude/tmux-hooks.json
• scripts/remote_run
• scripts/tm
• scripts/tmux-ai-attention
• scripts/tm.local.example
• install.sh
• setup
• setup-luis
• docs/tm-shortcuts.md
• OS package hints under os/

AI Agent Notes

Repo AGENTS.md is the shared map for agents working inside this dotfiles checkout. CLAUDE.md exists only as Claude's repo entry point and points back to AGENTS.md, so repo guidance stays in one place.

config/agents/AGENTS.md is the global high-level agent instruction source for Luis' computer. The installer links it to ~/AGENTS.md, then links ~/CLAUDE.md, ~/.codex/AGENTS.md, and ~/.claude/CLAUDE.md back to ~/AGENTS.md.

config/agents/pipelines/ contains the portable routing layer for non-trivial work outside a project with its own workflow. It supports local, remote, and cloud execution without coupling task coordination to a specific agent UI or provider. Its research route separates evidence collection, synthesis, and local pattern-fit before a proposed change is planned. Its challenge route uses bounded, evidence-driven skepticism and adjudication for material assumptions and results.

config/claude/agents/ provides user-level Claude Code subagents with explicit model selection and supported effort settings for the universal pipeline. The installer links each definition into ~/.claude/agents/ without taking ownership of unrelated personal subagents.

Install

git clone https://github.com/Octobr26/dotfiles.git ~/dev/dotfiles
cd ~/dev/dotfiles
./setup

Use ./setup for general/shared machines. Use ./setup-luis for Luis' personal setup.

The installer detects macos, linux, wsl, or windows.

• first, it runs git pull --ff-only in the dotfiles repo so setup uses the latest checkout when possible
• prints a before/after tool check with installed paths and versions
• installs packages automatically unless DOTFILES_SKIP_PACKAGES=1 is set
• ./setup prompts before installing optional tools: Codex, Claude, and spotify_player
• ./setup-luis installs those optional tools without prompting
• updates existing supported tools by default; set DOTFILES_UPDATE_TOOLS=0 to only install missing Linux release/script tools
• macOS uses brew bundle
• Linux/WSL uses apt-get, dnf, or yum; this covers Amazon Linux on EC2 through dnf/yum
• Linux installs or updates Neovim from the official release archive under ~/.local/opt, avoiding older distro packages
• Amazon Linux enables an EC2 compatibility path: it checks for low disk or inode headroom, cleans package caches and old journal entries when needed, installs current Rust/Cargo through rustup, installs a pinned Zig release into ~/.local/bin, builds tree-sitter-cli locally into ~/.local/bin, and points Mason's tree-sitter shim at that local binary to avoid glibc-mismatched prebuilt releases
• Amazon Linux also writes managed ~/.bashrc and ~/.inputrc blocks so default EC2 bash sessions see ~/.local/bin, Up/Down history, Mac Delete/backspace, and forward-delete escape sequences
• Neovim config prefers Zig for Treesitter parser builds by setting CC="zig cc" and CXX="zig c++" when zig is available
• Linux installs or updates ripgrep (rg) and fd from official release archives when distro packages are missing or stale
• Linux also installs or updates lazygit, starship, zoxide, and Atuin through upstream install scripts/releases when packages are not available
• Mutagen installs through Homebrew on macOS or from its official release archive on Linux/WSL
• pnpm installs/updates through npm into $HOME/.local
• Codex and Claude CLIs install/update through npm into $HOME/.local only when selected
• spotify_player installs through Homebrew on macOS when available, or through Cargo on Linux/WSL
• pnpm defaults to pnpm@10 to avoid pnpm@11 requiring Node >=22.13; override with DOTFILES_PNPM_SPEC=pnpm@latest
• Rust installs through rustup on Linux so Amazon Linux does not use its older repo rustc; the default minimum is 1.74.1, override with DOTFILES_RUST_MIN_VERSION
• tree-sitter-cli defaults to 0.22.6; override with DOTFILES_TREE_SITTER_CLI_VERSION or DOTFILES_TREE_SITTER_CLI_VERSIONS
• Zig defaults to 0.13.0 for Amazon Linux compatibility; override with DOTFILES_ZIG_VERSION
• after package work, it reports any remaining Homebrew, Linux package-manager, or npm global updates it can see
• links .ignore to ~/.ignore
• links global agent instructions through ~/AGENTS.md for Codex and Claude entrypoints
• merges tmux lifecycle handlers into ~/.codex/hooks.json and ~/.claude/settings.json without replacing other hooks
• requires Python 3.9 or newer for the tmux AI attention watcher and hook merger
• links the universal Claude pipeline agents individually under ~/.claude/agents/
• macOS/Linux/WSL: links .tmux.conf
• macOS: links Ghostty and lazygit from their ~/Library/Application Support/... locations
• Linux/WSL: links Ghostty and lazygit under ~/.config/...
• Windows: skips tmux because native Windows does not match tmux/zsh behavior well
• zsh setup is automatic: install.sh adds a managed block to ~/.zshrc
• that block adds this repo's scripts/ folder to PATH and sources zsh_stuff
• Existing files are moved to ~/.dotfiles-backup/<timestamp>/
• If symlinks are unavailable, the installer copies files instead

zsh

This repo does not own ~/.zshrc. The installer adds this managed block:

export PATH="/path/to/dotfiles/scripts:$PATH"
source "/path/to/dotfiles/zsh_stuff"

zsh_stuff also keeps scripts/ and $HOME/.local/bin in PATH when sourced directly.

Theme

Ghostty, tmux, Neovim, Atuin, Starship, and bat use Gruvbox Dark. Lazygit and fzf inherit the current terminal's ANSI palette rather than maintaining duplicate theme definitions.

tm Shortcuts

scripts/tm is public and generic. It supports tm <path> for any project directory, and it loads ignored private shortcuts from scripts/tm.local when that file exists.

To add machine-specific shortcuts without publishing repo names or paths:

cp scripts/tm.local.example scripts/tm.local

Then edit scripts/tm.local. See docs/tm-shortcuts.md for the shortcut contract and an AI prompt you can reuse on another machine.

List running Codex and Claude panes, or jump to one by list number, exact tmux target, pane ID, or unique text match:

tm agent list
tm agent jump 1

AI Attention in tmux

scripts/tmux-ai-attention keeps each pane's always-visible header current with its pane number, tool, optional role, and AI attention state; the focused project appears once in the top status bar. The active pane uses a peach header and border. Pane headers show ! INPUT, ● working, ✓ done, or ○ idle; AI window tabs aggregate those states as ! for input, ● for working, and ✓ when no pane needs attention. It starts automatically from .tmux.conf and only sounds for background panes when they transition to input or done. Codex and Claude state comes from supported JSON lifecycle hooks; Stop and SubagentStop mark the pane done, while their corresponding start events mark it working. These are attention states, not proof that a model is actively generating or that all background work has finished. Visible-screen matching remains only as a compatibility fallback for older or unhooked panes. Codex asks once to review newly installed hooks; after they are trusted, new Codex panes use structured state automatically. Use tmux-ai-attention test to verify the notification sounds. Ctrl-a a opens tmux's window picker. Ctrl-a y opens lazygit, Ctrl-a Ctrl-s opens spotify_player, and Ctrl-a t opens a login shell in a popup rooted at the focused pane's directory. Ctrl-a N toggles AI request and completion sounds without disabling visual state tracking. Ctrl-a R sets an optional role such as implement, review, or commands on the focused pane; submit a blank role to hide it.

Remote Commands

msync safely creates a one-way synchronization session from the current local Git repository to the matching project directory on an SSH host. rfr executes a remote command after flushing that session, while rr skips only the explicit flush.

Defaults:

REMOTE_RUN_SSH_HOST=dev
REMOTE_RUN_PROJECTS_DIR=/home/ec2-user/dev/projects

Override either variable in private shell configuration when a machine uses a different SSH alias or remote project root. Clone the same repository locally and remotely, check out the same commit, and run this from anywhere inside the local repository:

msync

rfr si resources/TableExport-Tabs/events/exclude-entity.json -b
rr pytest resources/Controls/tests/test_controls.py -v

See docs/mutagen-remote-workflow.md for the safety checks, endpoint mapping, and macOS setup.

Current local links

~/.tmux.conf -> ~/dev/dotfiles/.tmux.conf
~/.ignore -> ~/dev/dotfiles/.ignore
~/AGENTS.md -> ~/dev/dotfiles/config/agents/AGENTS.md
~/CLAUDE.md -> ~/AGENTS.md
~/.codex/AGENTS.md -> ~/AGENTS.md
~/.claude/CLAUDE.md -> ~/AGENTS.md
~/.claude/agents/pipeline-collector.md -> ~/dev/dotfiles/config/claude/agents/pipeline-collector.md
~/.claude/agents/pipeline-maker.md -> ~/dev/dotfiles/config/claude/agents/pipeline-maker.md
~/.claude/agents/pipeline-skeptic.md -> ~/dev/dotfiles/config/claude/agents/pipeline-skeptic.md
~/.claude/agents/pipeline-adjudicator.md -> ~/dev/dotfiles/config/claude/agents/pipeline-adjudicator.md
~/.claude/agents/pipeline-deep-agent.md -> ~/dev/dotfiles/config/claude/agents/pipeline-deep-agent.md
~/.config/nvim -> ~/dev/dotfiles/config/nvim
~/.config/atuin -> ~/dev/dotfiles/config/atuin
~/.config/git/ignore -> ~/dev/dotfiles/config/git/ignore
~/.config/starship.toml -> ~/dev/dotfiles/config/starship/starship.toml
~/Library/Application Support/com.mitchellh.ghostty/config.ghostty -> ~/dev/dotfiles/config/ghostty/config.ghostty
~/Library/Application Support/lazygit/config.yml -> ~/dev/dotfiles/config/lazygit/config.yml

Not Synced

• lazygit state.yml, because it stores recent repos, PRs, and command history
• Atuin history database, keys, and session files
• spotify-player cache, logs, and auth credentials
• GitHub auth and global .gitconfig
• private tmux shortcuts in scripts/tm.local

Packages

macOS:

brew bundle --file ~/dev/dotfiles/os/macos/Brewfile

Linux/WSL:

cat ~/dev/dotfiles/os/linux/apt-packages.txt
cat ~/dev/dotfiles/os/linux/dnf-packages.txt

Windows:

Get-Content ~/dev/dotfiles/os/windows/winget-packages.txt

For the closest Windows setup, install WSL and run install.sh inside WSL.