dotfiles/README.md

# Dotfiles

A cross-platform dotfiles repository managed with GNU Stow, compatible with both
Debian Trixie and macOS. This repository contains configuration files for
various development tools and applications to create a consistent environment
across different systems.

## Overview

This dotfiles repository uses [GNU Stow](https://www.gnu.org/software/stow/) to
manage symlinks.

## Directory Structure

```
dotfiles/
├── alacritty/     # Alacritty terminal emulator config
├── curl/          # curl configuration
├── git/           # Git configuration
├── nvim/          # Neovim configuration
├── nvidia-power-tray/ # GPU power-state tray indicator (Debian/GNOME only)
├── scripts/       # Utility scripts
├── tmux/          # tmux configuration
└── zsh/           # ZSH shell configuration
```

## Dependencies

### Fonts

- [Jetbrains Mono Nerd Font](https://www.nerdfonts.com/font-downloads)

### Core Tools

- **Terminal**: [Alacritty](https://github.com/alacritty/alacritty)
- **Shell**: [ZSH](https://www.zsh.org/)
  - [zsh-syntax-highlighting](https://github.com/zsh-users/zsh-syntax-highlighting)
  - [zsh-autosuggestions](https://github.com/zsh-users/zsh-autosuggestions)
      (submodule)
  - [zsh-completions](https://github.com/zsh-users/zsh-completions)
      (submodule)
- **Package Manager**: [Homebrew/Linuxbrew](https://brew.sh/)
- **Dotfile Management**: [GNU Stow](https://www.gnu.org/software/stow/)

### Development Tools

- [Rust](https://www.rust-lang.org/) toolchain (including rust-analyzer)
- [Go](https://go.dev/)
- [Neovim](https://neovim.io/)
- [tmux](https://github.com/tmux/tmux) +
  [tmux-plugin-manager](https://github.com/tmux-plugins/tpm)
- [Terraform](https://www.terraform.io/)
- python3-libtmux
  - Installed via `apt` in Debian. Remember to run `brew unlink python3` to
      prevent conflicting Python environments.
- gdb
- reattach-to-user-namespace (macOS only)
- [Claude Code](https://claude.com/claude-code) CLI, plus the
  `@agentclientprotocol/claude-agent-acp` bridge used by agentic.nvim

### Language Servers & Linters

- Lua: lua-language-server, stylua, luacheck
- JavaScript/TypeScript: prettier, prettier-plugin-go-template
- Shell: shfmt, shellcheck, bash-language-server
- Terraform: terraform-ls, tflint
- Python: ruff
- Go: gopls, golangci-lint (v1.64), gofumpt
- Markdown: markdownlint-cli2

### Extras

- pipx
- awsume
- podman
- wl-clipboard (Debian only)
- secret-tool (Debian only)
- fzf
- tree-sitter-cli
- lesspipe
- cbonsai
- `nvidia-power-tray` (Debian/GNOME only): `python3-gi`,
  `gir1.2-gtk-3.0`, `gir1.2-ayatanaappindicator3-0.1` and the
  [AppIndicator support](https://extensions.gnome.org/extension/615/appindicator-support/)
  GNOME extension. See `nvidia-power-tray/README.md`.

## Installation

### Prerequisites

1. **Install Rust**

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup component add rust-analyzer
```

1. **Install Homebrew**

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

1. **Install the Claude ACP bridge**

agentic.nvim talks to Claude over ACP and does not manage the binary itself.
Install it globally, then authenticate once with the Claude Code CLI — no API
key is needed:

```bash
npm i -g @agentclientprotocol/claude-agent-acp
claude /login
```

1. **Install tmux-plugin-manager**

```bash
mkdir -p ~/.tmux/plugins
git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
```

### Platform-Specific Setup

#### Debian Trixie

1. **Install Terraform**

```bash
wget -O - https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com bookworm main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install terraform
```

1. **Install Dependencies**

```bash
# System packages
sudo apt install alacritty zsh tmux stow zsh-syntax-highlighting less python3-libtmux cbonsai shfmt shellcheck lua-check libsecret-tools wl-clipboard podman qemu-system-x86 qemu-utils virtiofsd gvproxy gdb

# Homebrew packages
brew install neovim stylua lua-language-server bash-language-server prettier terraform-ls tflint ruff markdownlint-cli2 fzf tree-sitter-cli

# Node packages
npm install --save-dev prettier prettier-plugin-go-template

# Prevent Python conflicts
brew unlink python3
```

#### macOS

```bash
# Core tools
brew install curl git alacritty zsh tmux stow zsh-syntax-highlighting lesspipe cbonsai reattach-to-user-namespace

# Development tools
brew install neovim stylua lua-language-server bash-language-server prettier terraform-ls tflint ruff fzf tree-sitter-cli podman gdb

# Node packages
npm install --save-dev prettier prettier-plugin-go-template
```

### Setup

1. **Clone this repository**:

```bash
git clone --recurse-submodules https://github.com/yourusername/dotfiles.git ~/dotfiles
cd ~/dotfiles
```

1. **Deploy configurations using Stow**:

```bash
stow zsh tmux git nvim curl alacritty wallpaper

# Debian/GNOME only, then enable the user service
stow nvidia-power-tray
systemctl --user daemon-reload
systemctl --user enable --now nvidia-power-tray.service
```

1. Change the default shell

```bash
chsh -s /bin/zsh
```

1. **Set up tmux plugins**:

    - Start a tmux session
    - Press `C-b I` to install plugins

2. **Git configuration**:
    - Create a `~/.gitconfig.local` file with personal config
    - See `~/.gitconfig.local.example` for reference

## Updating

To update the dotfiles repository and all submodules:

```bash
cd ~/dotfiles
git pull
git submodule update --init --recursive
```