# Caveman Project Structure: Inside the Node-Based CLI Architecture

> Explore the Caveman project structure, a four-layer Node.js architecture featuring a core CLI runtime, modular skills, and hooks for efficient mode management. Understand its design.

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

---

**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`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js), `commands/*.md`, `commands/*.toml` |
| **Hooks & Runtime Logic** | Node scripts managing Caveman mode, configuration, and statistics | [`src/hooks/caveman-config.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-config.js), [`src/hooks/caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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.

```bash

# Install the CLI from the repository root

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

# Verify installation

caveman --help

```

The file [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/commands/caveman.md) — Top-level help documentation
- [`commands/caveman.toml`](https://github.com/JuliusBrussee/caveman/blob/main/commands/caveman.toml) — Manifest defining the root command
- [`commands/caveman-stats.md`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/.caveman/config.json) or [`.caveman.json`](https://github.com/JuliusBrussee/caveman/blob/main/.caveman.json))
3. User-level config (`$XDG_CONFIG_HOME/caveman/config.json`)
4. Fallback default of `"full"`

```javascript
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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/src/tools/caveman-init.js) module implements the `caveman init` command, which scaffolds new projects by writing a [`.caveman/config.json`](https://github.com/JuliusBrussee/caveman/blob/main/.caveman/config.json) file with the selected default mode and optionally updating `.gitignore`.

```bash

# 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`](https://github.com/JuliusBrussee/caveman/blob/main/compress.js) walks the project tree, removes large embedded blobs, rewrites markdown files, and generates diffs.

```bash

# 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`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-compress.md), [`caveman-commit.md`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/index.html) landing page and platform-specific guides like [`docs/install-windows.md`](https://github.com/JuliusBrussee/caveman/blob/main/docs/install-windows.md). The `evals/` directory houses the LLM evaluation harness with scripts such as [`measure.py`](https://github.com/JuliusBrussee/caveman/blob/main/measure.py) and [`llm_run.py`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/test_symlink_flag.js), [`test_repo_local_config.js`](https://github.com/JuliusBrussee/caveman/blob/main/test_repo_local_config.js)) verify hook behavior and configuration resolution
- Python validation ([`test_validate_inline.py`](https://github.com/JuliusBrussee/caveman/blob/main/test_validate_inline.py), [`verify_repo.py`](https://github.com/JuliusBrussee/caveman/blob/main/verify_repo.py)) performs end-to-end distribution checks
- `benchmarks/` contains Python performance drivers ([`run.py`](https://github.com/JuliusBrussee/caveman/blob/main/run.py)) with accompanying [`requirements.txt`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-config.js)), mode activation banners ([`caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-activate.js)), prompt parsing for mode directives ([`caveman-mode-tracker.js`](https://github.com/JuliusBrussee/caveman/blob/main/caveman-mode-tracker.js)), and usage statistics collection ([`caveman-stats.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/.caveman/config.json) or [`.caveman.json`](https://github.com/JuliusBrussee/caveman/blob/main/.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`](https://github.com/JuliusBrussee/caveman/blob/main/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.