ai-deroot-pre-commit 0.0.9
A pre-commit hook for managing symlinks to AI configuration files stored in a hidden directory
License: Apache-2.0
Requires Python: >=3.10
Keywords: pre-commit, symlinks, ai, llm, claude, gemini, configuration, git

# ai-deroot-pre-commit

[![image](https://img.shields.io/pypi/v/ai-deroot-pre-commit.svg)](https://pypi.python.org/pypi/ai-deroot-pre-commit)
[![image](https://img.shields.io/pypi/l/ai-deroot-pre-commit.svg)](https://pypi.python.org/pypi/ai-deroot-pre-commit)
[![image](https://img.shields.io/pypi/pyversions/ai-deroot-pre-commit.svg)](https://pypi.python.org/pypi/ai-deroot-pre-commit)

A [pre-commit](https://pre-commit.com) hook for managing symlinks to AI configuration files stored in a hidden directory.

## Overview

Many AI tools (Claude Code, Gemini, etc.) require configuration files like `CLAUDE.md`, `GEMINI.md`, and project-specific files like `specs/`, `templates/`, and `memory/` to be present at the repository root. However, committing these files directly to your main branch can clutter your repository and create merge conflicts when working across branches.

This pre-commit hook solves this by:

1. **Storing master files** in a hidden directory (e.g., `.llm/`)
2. **Creating symlinks** from the repository root to the hidden directory
3. **Managing `.gitignore`** to prevent accidental commits of symlinked files
4. **Validating symlinks** to ensure they're always properly configured
5. Optional: **Migrating existing files** at the repo root into your hidden directory (copy or move) before creating the symlinks

## Usage

Add this to your `.pre-commit-config.yaml`:

```yaml
repos:
  - repo: https://github.com/shyndman/ai-deroot-pre-commit
    rev: v0.0.9  # Use the ref you want to point at
    hooks:
      - id: setup-managed-symlinks
      - id: check-managed-symlinks
      - id: update-gitignore-for-symlinks
```

### Full Configuration Example

```yaml
repos:
  - repo: https://github.com/shyndman/ai-deroot-pre-commit
    rev: v0.0.9
    hooks:
      # Sets up symlinks after checkout/merge
      - id: setup-managed-symlinks
        args:
          - --hidden-dir=.llm
          - --files=CLAUDE.md,GEMINI.md,specs,templates,memory
          - --migrate=move  # or copy

      # Validates symlinks during normal commits
      - id: check-managed-symlinks
        args:
          - --hidden-dir=.llm
          - --files=CLAUDE.md,GEMINI.md,specs,templates,memory

      # Ensures .gitignore includes symlinked files
      - id: update-gitignore-for-symlinks
        args:
          - --hidden-dir=.llm
          - --files=CLAUDE.md,GEMINI.md,specs,templates,memory
```

## Hook Details

### `setup-managed-symlinks`

**When it runs:** `post-checkout`, `post-merge`

Creates symlinks from the repository root to files in your hidden directory. This ensures that after switching branches or pulling changes, your LLM configuration files are always available where tools expect them.

**Features:**
- Creates missing symlinks automatically
- Fixes incorrectly pointing symlinks
- Creates the hidden directory if it doesn't exist (supports any dot-dir like `.ai`, `.llm`, etc.)
- Optional migration: copy or move existing root files into the hidden dir before creating symlinks

### `check-managed-symlinks`

**When it runs:** `pre-commit` (when hidden directory or `.gitignore` changes)

Validates that all expected symlinks exist and point to the correct locations. Prevents commits when symlinks are broken or missing.

**Features:**
- Validates symlink targets
- Detects broken symlinks
- Ensures source files exist
- Provides clear error messages with fix instructions

### `update-gitignore-for-symlinks`

**When it runs:** `pre-commit`

Automatically adds symlinked files to `.gitignore` to prevent accidental commits. This hook will modify `.gitignore` and require you to stage the changes.

**Features:**
- Adds missing entries to `.gitignore`
- Preserves existing `.gitignore` content
- Adds descriptive comments
- Only runs when changes are needed

## Configuration Options

### `--hidden-dir`

Specifies the directory where master files are stored.

- **Default:** None (required parameter)
- **Example:** `--hidden-dir=.llm`
- **Note:** Can be any directory name, doesn't need to start with `.`

### `--files`

Comma-separated list of files/directories to manage as symlinks.

- **Default:** None (required parameter)
- **Example:** `--files=CLAUDE.md,GEMINI.md,specs,templates,memory`
- **Note:** Supports both files and directories

## Workflow Example

1. **Initial setup:**
   ```bash
   # Create your hidden directory and files
   mkdir .llm
   echo "# Claude Configuration" > .llm/CLAUDE.md
   mkdir .llm/specs

   # Install pre-commit hooks
   pre-commit install-hooks
   
   # Create initial symlinks
   pre-commit run --hook-stage post-checkout setup-managed-symlinks
   ```

2. **After setup, symlinks are created automatically:**
   ```bash
   git checkout main
   # setup-managed-symlinks runs automatically
   # Creates: CLAUDE.md -> .llm/CLAUDE.md
   #          specs -> .llm/specs
   ```

3. **The `.gitignore` is updated automatically:**
   ```bash
   git add file.py
   git commit -m "Add feature"
   # update-gitignore-for-symlinks runs
   # Adds entries to .gitignore if needed
   ```

## Important Notes

### File Conflicts

If you have existing files at the target locations, the `setup-managed-symlinks` hook will warn you and not overwrite them. You'll need to manually resolve these conflicts by either:

- Moving the existing file to the hidden directory
- Removing the existing file if it's no longer needed
- Updating your `.gitignore` if the file should be tracked

### Hook Stages

The hooks are designed to run at specific stages:

- **`setup-managed-symlinks`**: `post-checkout`, `post-merge` - Ensures symlinks exist after branch operations
- **`check-managed-symlinks`**: `pre-commit` - Validates before commits (only when relevant files change)
- **`update-gitignore-for-symlinks`**: `pre-commit` - Updates `.gitignore` before commits

### Updating File Lists

When you add or remove files from the `--files` argument, you must also update the `files` regex in the `check-managed-symlinks` hook configuration to ensure it runs at the appropriate times.

## Troubleshooting

### Broken Symlinks

If you see errors about broken symlinks:

```bash
# Run the setup hook manually
pre-commit run --hook-stage post-checkout setup-managed-symlinks

# Or use pre-commit's built-in command
pre-commit install --hook-type post-checkout
```

### Permission Issues

If you encounter permission issues with symlinks, ensure your filesystem supports symbolic links and that you have appropriate permissions in the repository directory.

### Git Ignore Not Updating

If `.gitignore` entries aren't being added automatically:

```bash
# Run the gitignore hook manually
pre-commit run update-gitignore-for-symlinks
git add .gitignore
git commit -m "Update .gitignore for managed symlinks"
```

## Packaging

This project uses the `uv_build` PEP 517 build backend (pure Python). The package is kept at the repository root (no `src/` layout) via:

```
[build-system]
requires = ["uv_build>=0.9.3,<0.10.0"]
build-backend = "uv_build"

[tool.uv.build-backend]
module-root = ""
module-name = "ai_deroot_pre_commit"
```

pre-commit installs this hook using its Python language backend by building and installing the package in an isolated environment.

## License

Licensed under the Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0).
### `--migrate`

Optionally migrate existing root files into the hidden directory before creating symlinks.

- Values: `copy` or `move`
- `move` relocates the file/dir into the hidden directory
- `copy` duplicates into the hidden directory; the original is replaced by a symlink

Notes:
- Migration only occurs when the source does not yet exist in the hidden directory and the target exists as a real file/dir.
- If both source and target exist, migration is skipped with a warning.