Emacs Dotfiles Specialist

Expert assistant for working with a personal dotfiles repository that manages development environment configuration across Linux systems using GNU Stow, with a focus on Emacs as the primary development environment with extensive AI integration.

Repository Overview

This dotfiles repository uses **GNU Stow** for symlink-based installation and features a modular Emacs configuration with GPTel/MCP integration for AI assistance, XDG Base Directory compliance, and comprehensive language runtime management.

Installation and Deployment

Deploying Configuration Changes with Stow

When deploying or updating dotfiles:

```bash

stow -d /home/jake/dotfiles/ -t "${HOME}" --no-folding -v emacs

```

**Stow ignore patterns** (`.stow-local-ignore`):

Building Emacs from Source

When building Emacs for native compilation, tree-sitter, and PGTK support:

```bash

CFLAGS='-march=native -O3' \

CC=gcc-14 \

../configure --with-native-compilation=aot \

--with-tree-sitter \

--with-gif \

--with-png \

--with-jpeg \

--with-rsvg \

--with-tiff \

--with-imagemagick \

--with-pgtk \

--with-mailutils \

--with-modules --prefix=/home/jake/.local

```

**Required dependencies**: build-essentials, autoconf, texinfo, libmagickwand-dev, libmagick++-dev, imagemagick, libgccjit0, libgccjit-14-dev, libwebkit2gtk-4.1-dev

Directory Structure

Emacs Configuration (`emacs/.config/emacs/`)

Modular configuration split into focused files:

Other Configuration Directories

Key Architecture Patterns

XDG Base Directory Compliance

All Emacs configuration follows XDG Base Directory specifications:

**When adding new file paths**: Always use `init--state-file` or `init--cache-file` functions to maintain XDG compliance.

Modular Emacs Configuration

Each `init-*.el` file handles a specific domain:

AI Integration Architecture

**GPTel Configuration** (`init-ai.el`):

**MCP Servers**:

**Custom AI Tools** (`init-ai-tools.el`):

Language Runtime Management

Multiple language version managers integrated in `.bashrc`:

Development Workflows

Working with Emacs Configuration

1. **Read the relevant module** before making changes (e.g., `init-ai.el` for AI features)

2. **Maintain XDG compliance** by using helper functions for file paths

3. **Follow use-package patterns** for all package configuration

4. **Test changes** with `M-x eval-buffer` in the modified file

5. **Deploy with Stow** after confirming changes work

Adding New Emacs Packages

1. Add `use-package` declaration to appropriate `init-*.el` module

2. Configure with `:defer`, `:hook`, or `:commands` for lazy loading

3. Set file paths using `init--state-file` or `init--cache-file` if needed

4. Test with `M-x eval-buffer` and restart Emacs

5. Install with `M-x package-install RET <package-name>` if not auto-installed

Working with AI Integration

1. **API keys**: Use `password-store` for secure credential management

2. **Tool definitions**: Define tools in `init-ai-tools.el` following gptel-tool patterns

3. **MCP servers**: Configure new MCP servers in `mcp-hub-servers` alist in `init-ai.el`

4. **Prompts**: Add reusable prompts to `prompts/` directory with clear documentation

Git Configuration

Programming Language Support

Languages configured via `init-prog.el` and tree-sitter:

LSP integration via `eglot` (built-in to Emacs 29+).

Completion and Navigation

**Completion framework** (`init-package.el`):

Email System

Email workflow with local IMAP sync:

Utility Commands

Emacs Development

```elisp

M-x eval-buffer # Reload current configuration file

M-x package-install # Install new package

M-x package-update-all # Update all packages

```

Shell Commands

```bash

~/.local/bin/clean-backups # Remove Emacs backup files recursively

```

Important Constraints

1. **Stow compatibility**: Ensure new files respect `.stow-local-ignore` patterns

2. **XDG compliance**: Never hardcode paths to `~/.emacs.d/` or similar

3. **Module separation**: Keep `init-*.el` files focused on their specific domain

4. **Lazy loading**: Always use `:defer`, `:hook`, or `:commands` in use-package declarations

5. **Password management**: Use `password-store` for all credentials, never hardcode

Examples

Adding a new AI prompt template

1. Create file in `prompts/` directory with descriptive name

2. Write clear prompt instructions

3. Reference in `init-ai.el` if needed for keybindings or automation

Adding a new Emacs module

1. Create `init-<domain>.el` in `emacs/.config/emacs/`

2. Add `(load "init-<domain>")` to `init.el`

3. Structure with `use-package` declarations

4. Test with `M-x eval-buffer`

5. Deploy with Stow

Configuring a new language runtime

1. Add installation instructions for language manager (PyEnv, NVM, etc.)

2. Source in `.bashrc` if needed for shell integration

3. Add Emacs mode configuration to `init-prog.el`

4. Configure LSP integration via `eglot` if available