Caveman Project Structure: Inside the Node-Based CLI Architecture

The Caveman repository follows a four-layer Node.js architecture consisting of a core CLI runtime, hooks for mode management, modular skill implementations, and comprehensive testing assets.

The caveman project structure organizes a Node-based CLI extension designed as a skill for the OpenAI-compatible Instagit platform. This architecture separates concerns into distinct layers that handle everything from command parsing and configuration resolution to LLM-powered code compression and review.

Overview of the Caveman Architecture

The repository divides functionality into four logical layers that work together to provide a seamless developer experience. Each layer has specific responsibilities and well-defined entry points, making the codebase modular and testable.

Layer	Purpose	Key Paths
Core CLI & Runtime	Entry points, command definitions, and binary bootstrapping	bin/install.js, commands/*.md, commands/*.toml
Hooks & Runtime Logic	Node scripts managing Caveman mode, configuration, and statistics	src/hooks/caveman-config.js, src/hooks/caveman-activate.js
Skill Implementations	Feature implementations exposed by the CLI (init, compress, commit, etc.)	src/plugins/opencode/commands/, src/mcp-servers/caveman-shrink/
Supporting Assets	Documentation, tests, evaluation scripts, and CI/CD metadata	docs/, tests/, evals/, benchmarks/

Core CLI and Runtime Layer

The foundation of the caveman project structure handles installation, command discovery, and the initial boot sequence that wires the skill into the host environment.

Installation and Entry Points

Installation scripts (install.sh or install.ps1) copy the Node entry point into the user's $PATH, making the caveman command globally available. The primary bootstrap file coordinates with the Instagit platform to register available commands.

# Install the CLI from the repository root

sh ./install.sh  # or ./install.ps1 on Windows

# Verify installation

caveman --help

The file bin/install.js serves as the main entry point that initializes the CLI runtime and loads the skill definitions.

Command Definition System

Commands in Caveman use a dual-file approach: Markdown documentation paired with TOML manifests. The CLI reads commands/*.toml files to discover available commands and displays the corresponding commands/*.md content when users run caveman help <cmd>.

Key files in this layer include:

• commands/caveman.md — Top-level help documentation
• commands/caveman.toml — Manifest defining the root command
• commands/caveman-stats.md — Documentation for the statistics sub-command

Hooks and Runtime Logic Layer

The hooks directory contains small, pure-Node.js scripts that execute before any LLM request is processed. These hooks manage the Caveman mode state, configuration resolution, and usage tracking.

Configuration Resolution (caveman-config.js)

The src/hooks/caveman-config.js file implements a hierarchical configuration resolver that determines the active Caveman mode. It checks sources in the following priority order:

1. CAVEMAN_DEFAULT_MODE environment variable
2. Repository-local config (.caveman/config.json or .caveman.json)
3. User-level config ($XDG_CONFIG_HOME/caveman/config.json)
4. Fallback default of "full"

const { getDefaultMode } = require('./src/hooks/caveman-config');
console.log('Default mode →', getDefaultMode());

Mode Activation and Tracking

When a mode other than off is active, src/hooks/caveman-activate.js creates a hidden flag file (.caveman-active) in the repository root and prints the "CAVEMAN MODE ACTIVE" banner. The companion hook src/hooks/caveman-mode-tracker.js parses LLM prompts for "/caveman <mode>" directives and updates the flag file dynamically.

Additional hooks include:

• src/hooks/caveman-stats.js — Collects usage metrics (invocations, token counts) and persists them to JSON for analysis

Skill Implementations Layer

This layer contains the actual feature implementations exposed through the CLI, organized under src/plugins/opencode/commands/ and supporting modules.

Project Initialization (caveman-init.js)

The src/tools/caveman-init.js module implements the caveman init command, which scaffolds new projects by writing a .caveman/config.json file with the selected default mode and optionally updating .gitignore.

# Initialize a new project with full mode

caveman init --mode full

Compression Engine (caveman-shrink)

The compression functionality lives in src/mcp-servers/caveman-shrink/. The core algorithm in compress.js walks the project tree, removes large embedded blobs, rewrites markdown files, and generates diffs.

# Preview compression changes without applying

caveman compress --dry-run

# Apply the shrinkage

caveman compress

Additional Commands (commit, review, stats)

Each major feature has its own implementation module:

• caveman-commit — Delegates to LLM modules for generating commit messages
• caveman-review — Handles code review workflows
• caveman-stats — Surfaces usage analytics collected by the hooks

Documentation for these commands resides in src/plugins/opencode/commands/ as Markdown files (e.g., caveman-compress.md, caveman-commit.md).

Supporting Assets and Testing Infrastructure

The final layer of the caveman project structure includes documentation, validation scripts, and performance benchmarks that ensure code quality and distribution integrity.

Documentation and Evaluation Harness

The docs/ directory contains rendered HTML documentation including an index.html landing page and platform-specific guides like docs/install-windows.md. The evals/ directory houses the LLM evaluation harness with scripts such as measure.py and llm_run.py for systematic benchmarking against language model backends.

Test Suite Structure

Testing spans multiple languages and concerns:

• JavaScript tests (test_symlink_flag.js, test_repo_local_config.js) verify hook behavior and configuration resolution
• Python validation (test_validate_inline.py, verify_repo.py) performs end-to-end distribution checks
• benchmarks/ contains Python performance drivers (run.py) with accompanying requirements.txt

Summary

• The caveman project structure organizes code into four distinct layers: CLI runtime, hooks, skills, and supporting assets.
• Configuration resolution follows a strict hierarchy from environment variables to repository-local files, implemented in src/hooks/caveman-config.js.
• Commands use a dual-file system combining TOML manifests with Markdown documentation stored in commands/ and src/plugins/opencode/commands/.
• The compression engine resides in src/mcp-servers/caveman-shrink/compress.js, handling file tree analysis and content optimization.
• Hooks manage state through pure-Node.js scripts that create flag files and track mode changes before LLM processing begins.

Frequently Asked Questions

What is the purpose of the hooks directory in the caveman project?

The src/hooks/ directory contains lightweight Node.js scripts that execute before LLM requests are processed. These hooks handle configuration resolution (caveman-config.js), mode activation banners (caveman-activate.js), prompt parsing for mode directives (caveman-mode-tracker.js), and usage statistics collection (caveman-stats.js). They provide a deterministic, testable layer for managing Caveman mode state independently of the skill implementations.

How does caveman resolve the default mode configuration?

According to the source code in src/hooks/caveman-config.js, the resolver checks four sources in strict priority order: the CAVEMAN_DEFAULT_MODE environment variable, repository-local configuration files (.caveman/config.json or .caveman.json), user-level configuration at $XDG_CONFIG_HOME/caveman/config.json, and finally falls back to the string "full" if no other source defines a mode.

Where is the compression logic implemented in the caveman repository?

The compression algorithm lives in src/mcp-servers/caveman-shrink/compress.js. This module implements the "shrink" engine that walks the project tree, identifies large embedded blobs, rewrites markdown content, and generates diffs. The CLI command caveman compress invokes this engine, with the --dry-run flag allowing users to preview changes before application.

How are commands defined in the caveman CLI?

Commands follow a dual-file definition system using TOML manifests and Markdown documentation. The CLI discovers commands by reading commands/*.toml files for metadata (command names, parameters) and displays help content from corresponding commands/*.md files. Skill-specific documentation resides in src/plugins/opencode/commands/, where each feature like caveman-compress or caveman-commit has both a .md description and implementation code.

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