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

> Discover where to find Caveman agent profile definitions. Locate and understand these JSON files in the agents profiles directory for your AI agent configurations.

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

---

**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](https://github.com/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`](https://github.com/JuliusBrussee/caveman/blob/main/agents/profiles/claude.json) | Anthropic's Claude Code agent |
| Opencode | [`agents/profiles/opencode.json`](https://github.com/JuliusBrussee/caveman/blob/main/agents/profiles/opencode.json) | Opencode AI SDK agent |
| Qwen Code | [`agents/profiles/qwen.json`](https://github.com/JuliusBrussee/caveman/blob/main/agents/profiles/qwen.json) | Alibaba's Qwen Code agent |

The JSON schema governing all profiles lives at **[`agents/profiles/schema.json`](https://github.com/JuliusBrussee/caveman/blob/main/agents/profiles/schema.json)**.

## How the CLI Uses Agent Profiles

The [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/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

```bash

# Display the raw JSON for the Claude profile

caveman profile view claude

```

This command loads [`agents/profiles/claude.json`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/agents/profiles/schema.json):

```bash

# 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:

```bash

# 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

```bash

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

caveman wrap --agent mybot

```

The wrapper reads [`agents/profiles/mybot.json`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/agents/profiles/schema.json) | JSON Schema (draft-07) validating all profile files |
| [`agents/profiles/claude.json`](https://github.com/JuliusBrussee/caveman/blob/main/agents/profiles/claude.json) | Production profile for Claude Code |
| [`agents/profiles/opencode.json`](https://github.com/JuliusBrussee/caveman/blob/main/agents/profiles/opencode.json) | Production profile for Opencode |
| [`agents/profiles/qwen.json`](https://github.com/JuliusBrussee/caveman/blob/main/agents/profiles/qwen.json) | Production profile for Qwen Code |
| [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/agents/profiles/schema.json)
- The [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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.