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

The Caveman installer modifies specific JSON, JavaScript, Markdown, and shell script files across Claude Code, OpenCode, and Hermes configuration directories, including settings.json, 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 at lines 882‑892.

• package.json
• caveman-config.js
• caveman-activate.js
• caveman-mode-tracker.js
• caveman-stats.js
• caveman-statusline.sh
• caveman-statusline.ps1
• 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.

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
• 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
• caveman-commit.md
• caveman-review.md
• caveman-compress.md
• caveman-stats.md
• 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
• cavecrew-builder.md
• 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 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, 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 (with .bak backup), and patches 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, the installer creates .bak backups for settings.json in Claude Code, and for AGENTS.md and 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 and 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}