feat(mods): add mods/ and the git-aware-file-explorer Claude Code mod

AGENTS.md

@@ -189,11 +189,14 @@ ai-dev/
 │   ├── opencode/            # OpenCode config for the Matrix Topology
 │   ├── opencode-lane/       # OpenCode config for the Lane Topology
 │   └── opencode-samples/    # Sample OpenCode configs readers copy (standard, modular, MCP)
+├── mods/                    # Client interface mods (one folder per client)
+│   └── claude/              # Claude Code mods: one folder per mod (plugin.json + hooks module)
 ├── skills/                  # Installable skill definitions (GitHub CLI discoverable)
 │   └── <skill-name>/        # Each skill: SKILL.md + README + references/
 ├── docs/                    # MkDocs source — PUBLICATION ONLY, not directives
 │   ├── agents/              # Agent catalog pages (links to agents/ at root)
 │   ├── skills/              # Skills catalog (index.md) + one lightweight overview page per skill
+│   ├── mods/                # Mods catalog (index.md) + one lightweight overview page per mod
 │   ├── harness/             # Claude Code, OpenCode, VS Code configuration guides
 │   └── mcp/                 # MCP server documentation
 ├── agent-output/            # Legacy output folder — gitignored
@@ -214,7 +217,7 @@ topologies are independent patterns and changes do not propagate between them.
 
 ## Documentation Synchronization
 
-The artifact directories `agents/`, `skills/`, and `harness/` are covered by the
+The artifact directories `agents/`, `skills/`, `mods/`, and `harness/` are covered by the
 documentation site. Whenever an item in one of these directories is added,
 removed, renamed, or updated, update the corresponding content page or pages
 under `docs/` in the same change. Keep catalog entries, descriptions, links,
@@ -366,6 +369,17 @@ as local files.
 4. Add the skill to `skills/README.md` and `cerebro-catalog.yaml`.
 5. Run `python scripts/validate_artifact_sync.py`.
 
+### Adding a new mod
+
+1. Create `mods/<client>/<name>/` with the client's plugin layout (for Claude Code:
+   `.claude-plugin/plugin.json`, `hooks/hooks.json`, the hooks module, and tests).
+2. Create the lightweight overview page `docs/mods/<name>.md` (what the mod does, how to load
+   it, and a link to `mods/<client>/<name>/` in the GitHub repo; no embedded mod code) and add
+   it to the `nav:` tree in `mkdocs.yml` under its client.
+3. Add the mod to the catalog table in `docs/mods/index.md` and to the client's harness page
+   (for Claude Code, `docs/harness/claudecode/index.md`).
+4. Run `python scripts/validate_artifact_sync.py`; it fails when a mod is missing from any of these.
+
 ### Adding a new agent
 
 - **Domain specialist** (single `.agent.md` at repo root): create the file under
@@ -417,7 +431,7 @@ mkdocs serve
 
 Run the relevant topology validators, the artifact synchronization validator, and
 the strict documentation build before committing changes to `agents/`, `harness/`,
-`skills/`, or `docs/`. Resolve every failure before committing.
+`skills/`, `mods/`, or `docs/`. Resolve every failure before committing.
 
 ---
 

README.md

@@ -12,6 +12,7 @@ Practical configurations and working examples for AI-powered development tools.
 
 - **[Agents](agents/)** — Installable AI agent definitions (Lane Topology, Matrix Topology, and domain specialists), discoverable via GitHub CLI
 - **[Skills](skills/)** — Installable domain-specific instruction sets, discoverable via GitHub CLI
+- **[Mods](docs/mods/index.md)** — Client interface additions, such as a git-aware Files pane for Claude Code
 - **[Harness](docs/harness/index.md)** — Claude Code, OpenCode CLI, and VS Code configurations with examples
 - **[MCP Servers](docs/mcp/index.md)** — Model Context Protocol integration examples
 
@@ -29,7 +30,7 @@ Practical configurations and working examples for AI-powered development tools.
 
 **Claude Code:**
 
-- [Claude Code](docs/harness/claudecode/index.md) — Skills, the Matrix Claude mirror, and Google Cloud Vertex AI setup
+- [Claude Code](docs/harness/claudecode/index.md) — Skills, mods, the Matrix Claude mirror, and Google Cloud Vertex AI setup
 
 **OpenCode CLI:**
 
@@ -52,11 +53,13 @@ ai-dev/
 │   ├── lane-topology/          # Lane Topology (OpenCode + Copilot)
 │   └── *.agent.md              # Domain specialist agents
 ├── harness/                    # Client harness configs and OpenCode sample configs
+├── mods/                       # Client interface mods, one folder per client
 ├── skills/                     # Installable skill definitions (GitHub CLI discoverable)
 │   └── <skill-name>/           # Each skill: SKILL.md + README + references/
 ├── docs/                       # MkDocs documentation source (catalog & guides only)
 │   ├── agents/                 # Agent catalog pages
 │   ├── skills/                 # Skills catalog + one overview page per skill
+│   ├── mods/                   # Mods catalog + one overview page per mod
 │   ├── harness/                # Claude Code, OpenCode, & VS Code guides
 │   └── mcp/                    # MCP server documentation
 ├── .agent-output/              # Temporary agent output (gitignored)

docs/harness/claudecode/index.md

@@ -22,6 +22,15 @@ body from the canonical OpenCode definitions and translates the frontmatter to C
 aliases. The mirror is in
 [`agents/matrix-topology/claude/`](https://github.com/CowboyLogic/ai-dev/tree/main/agents/matrix-topology/claude).
 
+## Mods
+
+Mods change Claude Code's own interface. The [mods catalog](../../mods/index.md) lists them and
+explains how to load one.
+
+| Mod | Use it to |
+|---|---|
+| [Git-Aware File Explorer](../../mods/git-aware-file-explorer.md) | Browse the workspace with changed files marked and see a file's diff beside the tree |
+
 ## Provider setup
 
 - [Claude Code with Google Vertex AI](claudecode-vertexai.md): run Claude Code against Claude models served through a Google Cloud project

docs/index.md

@@ -18,6 +18,7 @@ This site complements the vendors' own documentation with ready-to-use configura
 
 - **[Agents](agents/index.md)**: two multi-agent topologies, Lane and Matrix, plus a roster of domain specialist agents (API, architecture, security, testing, and more).
 - **[Skills](skills/index.md)**: structured instruction sets that teach AI agents domain-specific tasks.
+- **[Mods](mods/index.md)**: additions to a client's own interface, such as a git-aware Files pane for Claude Code.
 - **[Harness](harness/index.md)**: configurations and guides for Claude Code, OpenCode, and VS Code.
 - **[MCP Servers](mcp/index.md)**: working examples for Model Context Protocol server integrations.
 

docs/mods/git-aware-file-explorer.md

@@ -0,0 +1,54 @@
+# Git-Aware File Explorer
+
+A Files pane for Claude Code that knows about git. It joins the workspace file browser and the
+list of changes into one pane: the tree marks what changed, and selecting a file shows its diff
+in a panel beside the tree.
+
+- **Mod name:** `git-aware-file-explorer`
+- **Client:** Claude Code (desktop app and terminal)
+- **Source:** [mods/claude/git-aware-file-explorer](https://github.com/CowboyLogic/ai-dev/tree/main/mods/claude/git-aware-file-explorer)
+
+---
+
+## What it does
+
+- **Branch bar.** The current branch, the lines added and deleted across all changes, and a count of
+  changed files. The count is a toggle that narrows the tree to changed files only. New files count
+  as added lines; past 200 new files, or for a new file over 512 KB or one that cannot be read, the
+  added total is marked as a minimum (`+1234+`). When git's output passes 4 MB it is cut, or git cannot read a changed file, and the counts drawn from it are marked the same way.
+- **Git-aware tree.** Files and folders with icons, a status letter on each changed file, and a mark
+  on every folder that holds a change. Ignored files are dimmed and deleted files struck through.
+  A filter box narrows the tree by name; it does not search inside ignored folders, and says so.
+  Outside git, searches stop after discovering 20,000 files and folders and report that limit.
+- **Diff panel.** Selecting a changed file shows its diff against `HEAD`, with added and deleted lines
+  tinted and the file's own line counts in the header. Selecting an unchanged file shows a preview.
+  Smaller previews show the full file; larger previews use fixed sections retained across scrolls.
+  The branch bar, filter, tree and file content share one native scrollbar and move together.
+  Selecting a file brings the pane back to the top to show its header and first lines.
+- **Stays current.** The pane rescans the workspace every few seconds and after each tool call that
+  can change files. Between changes, scrolling reuses the prepared tree and open file: it does not
+  run git, list folders or reread the file. Diff counts are prepared when the diff is loaded.
+
+## Where it applies
+
+Use it in a git repository when you want to watch an agent's changes land file by file without
+switching between the Files and Changes views. Outside a repository it works as a plain file browser.
+
+The pane opens at the start of each session. `/git-files` reopens it after it is closed.
+
+> [!NOTE]
+> The header and both columns scroll together in this version. Native scrolling avoids the desktop
+> movement and snap back caused by trying to keep a mod's header fixed. Platform support for fixed
+> headers and independent scrolling is tracked in [Anthropic issue #99449](https://github.com/anthropics/claude-code/issues/99449).
+
+---
+
+## Install
+
+Load the mod's folder as described in [Installing a Claude Code mod](index.md#installing-a-claude-code-mod),
+with `<mod-name>` set to `git-aware-file-explorer`.
+
+### Verify installation
+
+Start a session in a git repository. The **Files** pane opens with the branch bar at the top. If it
+does not, run `/git-files`.

docs/mods/index.md

@@ -0,0 +1,49 @@
+# Mods
+
+Mods change an AI client's own interface: panes, panels, status lines, and slash commands that
+the client does not ship with. Where a skill teaches an agent how to do a task, a mod changes
+what you see and use while working with that agent.
+
+All mod files live at the root of the repository under
+[`mods/`](https://github.com/CowboyLogic/ai-dev/tree/main/mods), in one folder per client.
+
+---
+
+## Claude Code
+
+Claude Code mods are plugins built on function hooks: a `plugin.json` manifest and a TypeScript
+hooks module that draws into the client's surfaces. They live under
+[`mods/claude/`](https://github.com/CowboyLogic/ai-dev/tree/main/mods/claude).
+
+| Mod | What it does |
+|---|---|
+| [Git-Aware File Explorer](git-aware-file-explorer.md) | A Files pane that marks changed files in the tree and shows a file's diff beside it |
+
+### Installing a Claude Code mod
+
+Clone the repository, then load the mod's folder into Claude Code.
+
+```bash
+git clone https://github.com/CowboyLogic/ai-dev.git
+```
+
+For a terminal session, pass the folder on the command line. The mod loads for that session only.
+
+```bash
+claude --plugin-dir /path/to/ai-dev/mods/claude/<mod-name>
+```
+
+For every session, including those the desktop app starts, name the folder in the `env` block of
+`~/.claude/settings.json`. Separate several folders with `:` (`;` on Windows).
+
+```json
+{
+  "env": {
+    "CLAUDE_CODE_PLUGIN_DIRS": "/path/to/ai-dev/mods/claude/<mod-name>"
+  }
+}
+```
+
+> [!NOTE]
+> The repository has no plugin marketplace yet, so `/plugin install` does not work for these mods.
+> Loading the folder also means a `git pull` updates the mod.

mkdocs.yml

@@ -115,6 +115,10 @@ nav:
           - Codex Configuration Manager: skills/client-config-codex.md
           - Copilot Configuration Manager: skills/client-config-copilotcli.md
           - OpenCode Configuration Manager: skills/client-config-opencode.md
+  - Mods:
+      - mods/index.md
+      - Claude Code:
+          - Git-Aware File Explorer: mods/git-aware-file-explorer.md
   - Harness:
       - harness/index.md
       - OpenCode:

mods/claude/git-aware-file-explorer/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "git-aware-file-explorer",
+  "version": "0.1.0",
+  "description": "A git-aware Files pane: browse the workspace, see changed files highlighted, and view a file's diff in a panel beside the tree.",
+  "author": {
+    "name": "Cowboy Logic",
+    "email": "my.cowboy.logic@gmail.com"
+  },
+  "types": "./types/index.d.ts"
+}

mods/claude/git-aware-file-explorer/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.tsx"] }