# What Files Are Modified by the Caveman Installer in Agent Configuration Directories?

> Discover which files the Caveman installer modifies in agent configuration directories. Learn about updated JSON, JS, MD, and shell script files for Claude Code, OpenCode, and Hermes.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: how-to-guide
- Published: 2026-07-07

---

**The Caveman installer modifies specific JSON, JavaScript, Markdown, and shell script files across Claude Code, OpenCode, and Hermes configuration directories, including [`settings.json`](https://github.com/JuliusBrussee/caveman/blob/main/settings.json), [`AGENTS.md`](https://github.com/JuliusBrussee/caveman/blob/main/AGENTS.md), and runtime-specific plugin directories.**

The JuliusBrussee/caveman repository provides a unified installer that provisions multi-agent workflows across three distinct AI coding runtimes. When you execute the installation script, it targets user-side agent configuration directories to inject hooks, plugins, and skill definitions. Understanding exactly what files are modified by the Caveman installer in agent configuration directories helps you audit changes, manage backups, and troubleshoot integration conflicts.

## Claude Code Configuration Files

The installer provisions **Claude Code** by writing hook scripts and updating the runtime's settings manifest.

### Hook Scripts in `<configDir>/hooks`

The installer copies eight specific files into the hooks subdirectory (default `$CLAUDE_CONFIG_DIR/hooks`). These files are written during the hook copy loop in **[`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js)** at lines 882‑892.

- [`package.json`](https://github.com/JuliusBrussee/caveman/blob/main/package.json)
- [`caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-config.js)
- [`caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js)
- [`caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-mode-tracker.js)
- [`caveman-stats.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-stats.js)
- [`caveman-statusline.sh`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-statusline.sh)
- `caveman-statusline.ps1`
- [`cavecrew-model-overrides.js`](https://github.com/JuliusBrussee/caveman/blob/main/cavecrew-model-overrides.js)

### Settings.json Modifications

The installer merges **SessionStart** and **UserPromptSubmit** hook entries into `<configDir>/settings.json`. It also injects a `statusLine` entry if one is absent. To protect existing configurations, the installer creates a backup named `settings.json.bak` on first install. This logic resides in the **`installHooks`** function at lines 964‑976 of [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js).

## OpenCode Configuration Files

**OpenCode** receives the most extensive modifications, including a complete plugin hierarchy, command definitions, agent personas, and global ruleset updates.

### Plugin Files and Structure

The installer creates a dedicated plugin directory under `~/.config/opencode` (or `$XDG_CONFIG_HOME/opencode`). The **`installOpencode`** function (lines 702‑709) copies:

- [`plugins/caveman/plugin.js`](https://github.com/JuliusBrussee/caveman/blob/main/plugins/caveman/plugin.js)
- [`plugins/caveman/package.json`](https://github.com/JuliusBrussee/caveman/blob/main/plugins/caveman/package.json)
- `plugins/caveman/caveman-config.cjs`

### Commands Directory

Within `~/.config/opencode/commands`, the installer copies any existing Markdown command files from the repository. The command copy loop at lines 744‑753 handles:

- [`caveman.md`](https://github.com/JuliusBrussee/caveman/blob/main/caveman.md)
- [`caveman-commit.md`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-commit.md)
- [`caveman-review.md`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-review.md)
- [`caveman-compress.md`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-compress.md)
- [`caveman-stats.md`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-stats.md)
- [`caveman-help.md`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-help.md)

### Agents Directory

The installer places agent personas in `~/.config/opencode/agents` while stripping the `tools:` line from each file. The agent copy loop (lines 760‑768) processes:

- [`cavecrew-investigator.md`](https://github.com/JuliusBrussee/caveman/blob/main/cavecrew-investigator.md)
- [`cavecrew-builder.md`](https://github.com/JuliusBrussee/caveman/blob/main/cavecrew-builder.md)
- [`cavecrew-reviewer.md`](https://github.com/JuliusBrussee/caveman/blob/main/cavecrew-reviewer.md)

### Skills Directory

Entire skill directories are copied into `~/.config/opencode/skills` via the skill copy loop at lines 774‑781:

- `caveman/`
- `caveman-commit/`
- `caveman-review/`
- `caveman-help/`
- `caveman-stats/`
- `caveman-compress/`
- `cavecrew/`

### AGENTS.md Ruleset Injection

The installer appends a **Caveman ruleset** block to `~/.config/opencode/AGENTS.md`, wrapping the content in `<!-- caveman-begin -->` and `<!-- caveman-end -->` comments. If migrating a legacy block, the original file is backed up as `AGENTS.md.bak`. This occurs at lines 883‑904.

### opencode.json Plugin Registration

The installer patches `~/.config/opencode/opencode.json` to register the plugin entry [`./plugins/caveman/plugin.js`](https://github.com/JuliusBrussee/caveman/blob/main/./plugins/caveman/plugin.js) and optionally a *caveman‑shrink* MCP entry. The original configuration is preserved as `opencode.json.bak`. This patch logic is implemented at lines 838‑872.

## Hermes Configuration Files

For **Hermes**, the installer operates exclusively within `~/.hermes/skills/productivity`. Unlike OpenCode, Hermes does not receive individual file edits; instead, the **`installHermes`** function (lines 618‑633) copies entire skill directories:

- `caveman/`
- `caveman-commit/`
- `caveman-review/`
- `caveman-help/`
- `caveman-stats/`
- `caveman-compress/`
- `cavecrew/`

No existing user files are modified during Hermes installation.

## Summary

- **Claude Code**: The installer writes eight hook scripts to `<configDir>/hooks` and merges hook entries into [`settings.json`](https://github.com/JuliusBrussee/caveman/blob/main/settings.json), backing up the original as `settings.json.bak`.
- **OpenCode**: Creates a plugin hierarchy under `~/.config/opencode`, populates commands and agents, copies skill directories, injects rules into [`AGENTS.md`](https://github.com/JuliusBrussee/caveman/blob/main/AGENTS.md) (with `.bak` backup), and patches [`opencode.json`](https://github.com/JuliusBrussee/caveman/blob/main/opencode.json) (with `.bak` backup).
- **Hermes**: Copies complete skill directories into `~/.hermes/skills/productivity` without editing existing configuration files.

## Frequently Asked Questions

### Does Caveman backup existing configuration files before modifying them?

Yes. According to the source code in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js), the installer creates `.bak` backups for [`settings.json`](https://github.com/JuliusBrussee/caveman/blob/main/settings.json) in Claude Code, and for [`AGENTS.md`](https://github.com/JuliusBrussee/caveman/blob/main/AGENTS.md) and [`opencode.json`](https://github.com/JuliusBrussee/caveman/blob/main/opencode.json) in OpenCode when it first modifies them or migrates legacy blocks.

### What is the difference between how Caveman handles OpenCode versus Hermes?

OpenCode receives granular file modifications including plugin registration, command injection, and JSON patching, while Hermes only receives wholesale directory copies into its skills folder. The Hermes installer at lines 618‑633 does not edit existing user files, whereas OpenCode extensively modifies [`AGENTS.md`](https://github.com/JuliusBrussee/caveman/blob/main/AGENTS.md) and [`opencode.json`](https://github.com/JuliusBrussee/caveman/blob/main/opencode.json).

### Can I manually inspect the hook files before they are installed?

Yes. The hook files exist in the Caveman repository and are copied verbatim to `<configDir>/hooks` during the installation process at lines 882‑892. You can review [`caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-config.js), [`caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js), and the other scripts in the repository before running the installer.

### Why does Caveman strip the `tools:` line from OpenCode agent files?

The installer removes the `tools:` line when copying agent files (lines 760‑768) to ensure compatibility with OpenCode's agent parsing logic, preventing configuration conflicts while preserving the agent's core instructions and persona definitions.