# Dotfiles for a Keyboard-First, AI-Assisted macOS Setup

This repo is the development environment I actually use: a macOS-first shell, editor, and terminal stack built around fast navigation, tmux/dmux multiplexing, Zed editing, and workflow automation for Claude, Codex, and Wiggum. It is opinionated, personal, and tuned for my own habits, but it is also meant to be readable. Steal the parts that are useful.

## Why This Repo Exists

- `t` is the tmux entrypoint, with device-aware behavior and a keyboard-first workflow.
- [`joshvera/dmux`](https://github.com/joshvera/dmux) is the active multiplexing layer around tmux.
- `z` opens Zed; Zed is the active editor path in this setup.
- `zsh` is tuned for fast completion, `fzf-tab`, autosuggestions, and predictable PATH setup.
- Claude, Codex, Oh My Codex, GStack, and Wiggum are wired into the environment with tracked commands, hooks, skills, and automation scripts.

Zellij and VS Code are deprecated in this setup. Their configs remain in the repo as historical/reference material, but new workflow docs should treat tmux/dmux and Zed as the current path.

## Quick Start

This repo assumes a macOS machine with Homebrew available. The bootstrap scripts default to `"$HOME/github/dotfiles"`, so clone it there unless you plan to override `DOTFILES_DIR`.

```bash
git clone https://github.com/joshvera/dotfiles.git "$HOME/github/dotfiles"
cd "$HOME/github/dotfiles"

brew bundle --file Brewfile

# Optional but useful if you want the fuller dev environment
brew bundle --file Brewfile.dev

# Optional GUI/workstation apps
brew bundle --file Brewfile.desktop

git submodule update --init --recursive

./scripts/bootstrap-core.sh

# Optional strict bootstrap: installs dev deps, validates plugins, Java 21,
# and checks that interactive zsh starts cleanly
./scripts/bootstrap-strict.sh
```

If you clone this repo somewhere else, run the bootstrap scripts with `DOTFILES_DIR` set explicitly:

```bash
DOTFILES_DIR="/path/to/dotfiles" ./scripts/bootstrap-core.sh
```

### Bootstrap Modes

| Script | What it does | Use it when |
| --- | --- | --- |
| `scripts/bootstrap-core.sh` | Backs up existing non-symlink dotfiles, installs or updates Oh My Codex from `joshvera/oh-my-codex`, installs GStack, links core shell/git/tmux files, repairs Claude runtime links, links shared `~/.agents/skills`, mirrors Claude skills to the shared skill root, and links Codex skills plus `~/.codex/AGENTS.md`. | You want the normal setup path for this environment. |
| `scripts/bootstrap-strict.sh` | Installs `Brewfile` and `Brewfile.dev`, syncs submodules, runs core bootstrap, verifies `fzf-tab`, checks for Java 21, and validates interactive `zsh` startup. | You want a fail-fast bootstrap that enforces the expected environment. |

## What Gets Linked By Default

`scripts/bootstrap-core.sh` links or repairs:

- `~/.zshrc`
- `~/.zprofile`
- `~/.zshenv`
- `~/.tmux.conf`
- `~/.gitconfig`
- `~/.fzf.zsh`
- selected repo-managed Claude files inside `~/.claude`
- `~/.agents/skills`
- `~/.claude/skills`
- `~/.codex/skills`
- `~/.codex/AGENTS.md`

The Claude setup is intentionally file-by-file. `bootstrap-core.sh` keeps `~/.claude` as a runtime directory and links the repo-managed Claude files into it instead of replacing the whole directory with a symlink.

### About `.claude/`

The tracked `.claude/` tree contains useful shared configuration such as commands, hooks, agents, `settings.json`, and `mcp.json`. It also has ignored runtime state on a real machine, such as history, sessions, caches, shell snapshots, and plugin data.

Do not treat `ln -s "$HOME/github/dotfiles/.claude" "$HOME/.claude"` as the default setup. Full-directory linking is an advanced/manual choice if you understand which parts are portable config and which parts are machine-local state.

## Daily Drivers

These are the commands that define the day-to-day workflow.

### `t`: tmux/dmux Multiplexing

`t` launches tmux through the repo wrapper. The active multiplexing setup is tmux plus [`dmux`](https://github.com/joshvera/dmux), with dmux providing the higher-level workflow around tmux sessions and integrations.

```bash
t
t --show-detection
t attach -t main
```

More detail: [tmux/README.md](tmux/README.md)

### `z`: Zed

`z` opens Zed from the shell.

```bash
z .
z README
z "$HOME/github/dotfiles"
```

Zed config lives in `zed/`, including editor settings and the Solarized theme.

### `tmux-obsidian-sync`: Session Sync From Notes

`tmux-obsidian-sync` creates missing tmux sessions and windows from Obsidian project notes. It is conservative by default and only does cleanup when you ask for it.

```bash
tmux-obsidian-sync --today
tmux-obsidian-sync --note "$HOME/github/aleph/Projects/Software - bankroll/README.md" --cleanup
```

### Legacy Zellij Helpers

`zt` and the scripts under `zellij/` are legacy Zellij workflow helpers. They are kept for reference and migration history, but they are not the active daily-driver path.

## What's In Here

| Path | What it does |
| --- | --- |
| `zsh/` | Shell behavior, custom functions, completion tuning, `fzf-tab`, autosuggestions, and the core interactive UX. |
| `tmux/` | The active terminal multiplexer config and the `t` wrapper; used with dmux. |
| `zed/` | The active editor config, including Zed settings and theme files. |
| `zellij/` | Deprecated Zellij configs and helpers retained as historical/reference material. |
| `vscode/` | Deprecated VS Code settings and keybindings retained as historical/reference material. |
| `nvim/` | A `lazy.nvim`-based Neovim config with modular options, keymaps, and plugin specs. |
| `.agents/skills/` | Shared repo-backed skills for model-agnostic agent workflows. |
| `.claude/` | Tracked Claude Code commands, hooks, agents, skills, MCP config, and shared settings. |
| `.codex/` | Codex-specific guidance and skill links, including `AGENTS.md` and `.codex/skills/`. |
| `hooks/` | Wiggum hooks for plan review, task review, notifications, final tests, and PR creation. |
| `scripts/` | Bootstrap scripts and setup utilities. |

Deeper docs:

- [tmux/README.md](tmux/README.md)
- [zellij/README.md](zellij/README.md)
- [docs/hooks.md](docs/hooks.md)

## AI Tooling

This repo is not just shell config. It also carries a lot of workflow automation for LLM-driven development.

### `.claude/`

The tracked Claude setup includes:

- command definitions under `.claude/commands/`
- reusable agents under `.claude/agents/`
- hook scripts under `.claude/hooks/`
- Claude settings and MCP wiring in `.claude/settings.json` and `.claude/mcp.json`
- shared guidance in `.claude/CLAUDE.md`

The hooks are operational, not decorative. For example, this repo wires in idle detection, notification delivery, and TDD guard behavior.

### `.agents/skills/` and `.codex/skills/`

Hand-maintained shared skills live under `.agents/skills/`, while `.codex/skills/` provides the Codex-facing view and generated Codex-specific skills. Package-managed skills from tools such as Oh My Codex and GStack should not be mirrored back into `.agents/skills/`; Claude Code gets shared skills through `.claude/skills/`, which may also contain ignored host-managed package links.

Current shared examples include:

- GitHub review comment handling
- Qodo PR finding resolution
- semantic impact analysis
- Codex plan and review helpers

### `hooks/`

The top-level `hooks/` directory is where Wiggum-oriented automation lives. That includes:

- `review-plan.sh` to send plans through Codex review
- `review-task.sh` to review implementation diffs against task specs
- `notify.sh` to send task notifications
- `create-pr.sh` to open a GitHub PR after a build completes
- `run-final-tests.sh` for end-of-task validation

If you want the deeper Claude hook model specifically, start with [docs/hooks.md](docs/hooks.md).

## Notes

- This repo is macOS-first and Homebrew-first.
- tmux/dmux and Zed are the active terminal/editor path.
- Zellij and VS Code are deprecated here but preserved as reference configs.
- I prefer a small number of sharp tools over a huge kitchen-sink setup, so the repo is intentionally opinionated.
- Existing subsystem docs are the source of truth for lower-level details; the top-level README is the map.