Where to Find Caveman Agent Profile Definitions: Location and Usage Guide

Caveman agent profile definitions are stored as declarative JSON files in the agents/profiles/ directory, with each file describing a single AI agent's installation, configuration injection, supported skills, and verification metadata.

The JuliusBrussee/caveman repository uses these profiles as the single source of truth for all built-in agents. The CLI reads them to power commands like caveman install and caveman wrap, making it straightforward to add, customize, or inspect agent configurations without modifying source code.

What Are Caveman Agent Profiles?

An agent profile is a JSON file that declaratively specifies everything Caveman needs to integrate with a coding agent. Rather than hard-coding agent logic, Caveman externalizes this into version-controlled, schema-validated files.

Each profile in agents/profiles/<id>.json contains:

• install — How to obtain the agent binary
• injection — Environment variables and configuration to inject at runtime
• binary_names — Executable names to probe for and wrap
• Skills, command hooks, memory hooks, and attribution headers
• Verification metadata (last_verified_at, verified_by)

Example Profile Files

Profile	File Path	Description
Claude Code	agents/profiles/claude.json	Anthropic's Claude Code agent
Opencode	agents/profiles/opencode.json	Opencode AI SDK agent
Qwen Code	agents/profiles/qwen.json	Alibaba's Qwen Code agent

The JSON schema governing all profiles lives at agents/profiles/schema.json.

How the CLI Uses Agent Profiles

The bin/install.js script reads the entire agents/profiles/ directory to construct an internal PROVIDERS matrix. This matrix drives the interactive installer shown when you run caveman install.

When you execute caveman wrap --agent <id>, the CLI:

1. Loads the corresponding JSON profile
2. Injects the defined environment variables and configuration
3. Launches the binary specified in binary_names

This architecture keeps the core CLI generic while allowing rapid agent additions through configuration alone.

Working with Agent Profiles

View an Existing Profile

# Display the raw JSON for the Claude profile

caveman profile view claude

This command loads agents/profiles/claude.json and prints it to stdout, useful for inspecting the exact configuration a wrapped agent will receive.

Add a Custom Agent Profile

Create a new file following the schema in agents/profiles/schema.json:

# Copy the schema as a template

cp agents/profiles/schema.json agents/profiles/mybot.json

# Edit mybot.json with your agent's specifics:

# - Unique "id" field (used as the profile slug)

# - Installation instructions

# - Binary names to probe for

# - Injection rules

Then register and verify your new profile:

# Register in the internal catalog

caveman profile add mybot

# Confirm it's recognized

caveman profile list | grep mybot

Use a Custom Profile in a Wrapper

# Wrap using your custom profile slug (the "id" field)

caveman wrap --agent mybot

The wrapper reads agents/profiles/mybot.json, applies the injection rules, and launches the specified binary with Caveman's transparent context management.

Key Files in the Agent Profile System

File	Purpose
agents/profiles/schema.json	JSON Schema (draft-07) validating all profile files
agents/profiles/claude.json	Production profile for Claude Code
agents/profiles/opencode.json	Production profile for Opencode
agents/profiles/qwen.json	Production profile for Qwen Code
bin/install.js	Installer that constructs the PROVIDERS matrix from profile files
agents/probe-installed.mjs	Binary probing utility that verifies profile-compatibility with installed agents

Extending Caveman with New Agent Profiles

The profile system is designed for contribution. To add support for a new coding agent:

1. Create agents/profiles/<your-agent>.json following the schema
2. Fill all required fields: id, name, binary_names, install, injection
3. Run caveman profile add <your-agent> to register it
4. Test with caveman wrap --agent <your-agent>

The caveman compile step (run during build or development) automatically picks up new files in agents/profiles/, no code changes required.

Summary

• Caveman agent profile definitions live in agents/profiles/ as individual JSON files
• Each file is validated against agents/profiles/schema.json
• The bin/install.js script generates the PROVIDERS matrix from these files
• Use caveman profile view, add, and list commands to inspect and manage profiles
• Custom agents require only a new JSON file—no CLI modifications needed

Frequently Asked Questions

What format are Caveman agent profiles written in?

Agent profiles are JSON files following a strict schema defined in agents/profiles/schema.json. The schema uses JSON Schema draft-07 and specifies required fields like id, name, binary_names, install, and injection.

How do I add a new agent to Caveman without modifying source code?

Drop a new <id>.json file into agents/profiles/ following the schema, then run caveman profile add <id>. The CLI will recognize it immediately. The system is designed so that caveman compile automatically ingests new profile files without requiring changes to bin/install.js or other core code.

Where does Caveman store verification metadata for agents?

Verification metadata including last_verified_at and verified_by fields are stored inside each profile JSON file under agents/profiles/. This keeps provenance data version-controlled alongside the agent definition itself, allowing the CLI to warn when profiles may be outdated relative to upstream agent releases.

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