Skip to content

AGENTS.md

Latest commit

 

History

History
194 lines (129 loc) · 3.97 KB

AGENTS.md

File metadata and controls

194 lines (129 loc) · 3.97 KB

AGENTS.md

This file provides guidance for AI coding agents working in this repository.

Repository Overview

This is a macOS machine setup repository containing:

  • Dotfiles managed with GNU Stow
  • Packages via Homebrew (Brewfile)
  • System preferences via shell script

This is a config-only repository - there are no build steps, tests, or linting to run.

Quick Reference Commands

Package Management

# Install all packages from Brewfile
brew bundle

# Regenerate Brewfile from currently installed packages
brew bundle dump --force --no-restart --no-vscode

Dotfiles Management

Stow packages are located in the dotfiles/ subdirectory.

# Apply a dotfile package (creates symlinks to home directory)
stow -d dotfiles -t ~ <package>

# Remove a dotfile package
stow -d dotfiles -t ~ -D <package>

# Preview what stow would do (dry run)
stow -d dotfiles -t ~ -n -v <package>

macOS Configuration

# Apply macOS system preferences
bash scripts/macos-config.sh

Stow Package Structure

Each stow package is a directory inside dotfiles/. The internal structure mirrors the home directory layout.

Current Packages

git, kitty, lazydocker, lazygit, nvim, opencode, ssh, tmux, zshrc

Adding New Dotfiles

To add a new config file to the repository:

  1. Create a directory inside dotfiles/ matching the application name
  2. Inside, recreate the path from home directory
  3. Move the config file into this structure
  4. Run stow -d dotfiles -t ~ <package> to create the symlink

Example: Adding ~/.config/foo/config.yml

dotfiles/
  foo/
    .config/
      foo/
        config.yml

Git Conventions

Commit Message Format

This repository uses conventional commits.

File Operations

Deleting Files

Use trash instead of rm for safety (allows recovery):

# Preferred
trash ~/.config/old-app

# Only for dependencies
rm -rf node_modules

Protected Files

Never modify these files directly:

  • .env files (anywhere in the repo)
  • .zsh_secrets (contains private tokens/keys)

Sensitive Information

Gitignored Files

These patterns are ignored and should stay that way:

.DS_Store
**/.env
.zsh_secrets
/dotfiles/lazygit/Library/Application Support/lazygit/state.yml

Privacy Considerations

When adding configs that reference personal or work-related identifiers:

  • Rename or anonymize identifiers before committing
  • Use generic names (e.g., clbrt-* instead of full company names)

Shell Script Style

Shell scripts in this repository follow these conventions:

Format

  • Shebang: #!/bin/bash
  • Use shfmt for formatting (included in Brewfile)
  • Section separators with comment blocks

OpenCode Plugin Development

The dotfiles/opencode/.config/opencode/ directory contains TypeScript plugins.

Plugin Structure

dotfiles/opencode/.config/opencode/
  plugin/           # TypeScript plugins
  command/          # Custom slash commands (markdown)
  instructions/     # System instructions (markdown)
  opencode.jsonc    # Main configuration

Plugin Style (TypeScript)

When modifying plugins:

  • Use async/await over promise chains
  • Use named imports: import { foo } from "bar"
  • Use const over let
  • No any type - use proper types or unknown
  • No code comments

Directory Structure

dotfiles/
  Brewfile              # Homebrew packages
  README.md             # User documentation
  scripts/
    macos-config.sh     # macOS system preferences
  dotfiles/             # Stow packages directory
    git/                # Stow package
    kitty/              # Stow package
    lazydocker/         # Stow package
    lazygit/            # Stow package
    nvim/               # Stow package (LazyVim)
    opencode/           # Stow package (AI agent config)
    ssh/                # Stow package
    tmux/               # Stow package
    zshrc/              # Stow package