How To Install Caveman In Codex On macOS And Windows

If you use Codex inside VS Code and want shorter, more compressed responses, caveman is a simple local plugin that adds that behavior.

This guide shows the full setup for both macOS and Windows. It uses a local plugin plus a local marketplace entry, so you do not need to publish anything remotely.

What Caveman Does

caveman adds a skill that tells Codex to answer in a much tighter style:

fewer filler words
shorter phrasing
preserved technical meaning
optional stronger compression levels

It can also auto-activate on session start if you add the optional .codex hook files.

Files You Need

The plugin is made of three parts:

a plugin folder: plugins/caveman
a marketplace file: .agents/plugins/marketplace.json
optional Codex hook files: .codex/hooks.json and .codex/config.toml

Folder Layout

Your workspace should end up looking like this:

your-project/
├─ .agents/
│  └─ plugins/
│     └─ marketplace.json
├─ .codex/
│  ├─ config.toml
│  └─ hooks.json
└─ plugins/
   └─ caveman/
      ├─ .codex-plugin/
      │  └─ plugin.json
      ├─ assets/
      │  ├─ caveman-small.svg
      │  └─ caveman.svg
      └─ skills/
         └─ caveman/
            └─ SKILL.md

Option 1: Install In One Project Only

Use this if you want caveman available only in one repo or one VS Code workspace.

macOS

If your project lives at:

/Users/your-name/code/my-app

create these folders inside that project:

/Users/your-name/code/my-app/plugins/caveman
/Users/your-name/code/my-app/.agents/plugins
/Users/your-name/code/my-app/.codex

Windows

If your project lives at:

C:\Users\your-name\code\my-app

create these folders inside that project:

C:\Users\your-name\code\my-app\plugins\caveman
C:\Users\your-name\code\my-app\.agents\plugins
C:\Users\your-name\code\my-app\.codex

Option 2: Install As A Home-Local Plugin

Use this if you want caveman available across multiple projects.

macOS

~/plugins/caveman
~/.agents/plugins/marketplace.json

If you also want Codex hooks globally, use:

~/.codex/hooks.json
~/.codex/config.toml

Windows

C:\Users\your-name\plugins\caveman
C:\Users\your-name\.agents\plugins\marketplace.json

If you also want Codex hooks globally, use:

C:\Users\your-name\.codex\hooks.json
C:\Users\your-name\.codex\config.toml

Step 1: Add The Plugin Manifest

Create:

plugins/caveman/.codex-plugin/plugin.json

Use this content:

{
  "name": "caveman",
  "version": "0.1.0",
  "description": "Ultra-compressed communication mode. Cut filler. Keep technical accuracy.",
  "author": {
    "name": "Julius Brussee",
    "url": "https://github.com/JuliusBrussee"
  },
  "homepage": "https://github.com/JuliusBrussee/caveman",
  "repository": "https://github.com/JuliusBrussee/caveman",
  "license": "MIT",
  "keywords": [
    "productivity",
    "communication",
    "brevity",
    "writing"
  ],
  "skills": "./skills/",
  "interface": {
    "displayName": "Caveman",
    "shortDescription": "Talk like caveman. Cut filler. Keep technical accuracy.",
    "longDescription": "Ultra-compressed communication mode for Codex. Use fewer words. Keep exact technical substance.",
    "developerName": "Julius Brussee",
    "category": "Productivity",
    "capabilities": [
      "Write"
    ],
    "websiteURL": "https://github.com/JuliusBrussee/caveman",
    "privacyPolicyURL": "https://github.com/JuliusBrussee/caveman/blob/main/README.md",
    "termsOfServiceURL": "https://github.com/JuliusBrussee/caveman/blob/main/LICENSE",
    "defaultPrompt": [
      "Use caveman mode. Cut filler. Keep technical accuracy."
    ],
    "brandColor": "#6B7280",
    "composerIcon": "./assets/caveman-small.svg",
    "logo": "./assets/caveman.svg",
    "screenshots": []
  }
}

Step 2: Add The Skill File

Create:

plugins/caveman/skills/caveman/SKILL.md

Use this content:

---
name: caveman
description: ">"
  Ultra-compressed communication mode. Cuts token usage by speaking like caveman
  while keeping technical accuracy. Supports lite, full, ultra, wenyan-lite,
  wenyan-full, and wenyan-ultra. Use when the user asks for caveman mode,
  fewer tokens, terse output, or invokes `$caveman`.
---

Respond terse like smart caveman. Technical substance stay. Fluff die.

## Persistence

Active every response until user says `stop caveman` or `normal mode`.
Default level: `full`.
Switch with `$caveman lite|full|ultra|wenyan-lite|wenyan|wenyan-ultra`.

## Rules

- Drop articles, filler, pleasantries, and hedging.
- Fragments OK.
- Prefer short synonyms.
- Keep technical terms and quoted errors exact.
- Leave code blocks unchanged.
- Use pattern: `[thing] [action] [reason]. [next step].`

## Levels

- `lite`: tight full sentences, no filler.
- `full`: no articles, fragments OK.
- `ultra`: abbreviate hard, use arrows for causality.
- `wenyan-lite`: semi-classical compression.
- `wenyan`: full classical Chinese terseness.
- `wenyan-ultra`: maximum compression with classical tone.

## Auto-Clarity

Use normal language for destructive actions, security warnings, or any case where
extra clarity reduces risk. Resume caveman after the clear part is done.

## Boundaries

Code, commits, and PR text stay normal unless the user asks otherwise.

Step 3: Add The Marketplace Entry

Create:

.agents/plugins/marketplace.json

If the file does not exist yet, use:

{
  "name": "Local Plugins",
  "interface": {
    "displayName": "Local Plugins"
  },
  "plugins": [
    {
      "name": "caveman",
      "source": {
        "source": "local",
        "path": "./plugins/caveman"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

If you already have a marketplace file, just append the caveman entry inside the plugins array.

Step 4: Add The Optional Auto-Start Hook

If you want Caveman mode to load automatically when Codex starts or resumes, create:

.codex/hooks.json
.codex/config.toml

Use:

`.codex/hooks.json`

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'CAVEMAN MODE ACTIVE. Rules: Drop articles, filler, pleasantries, hedging. Fragments OK. Short synonyms. Pattern: [thing] [action] [reason]. [next step]. Code, commits, security warnings: write normal. User says stop caveman or normal mode to deactivate.'",
            "timeout": 5,
            "statusMessage": "Loading caveman mode"
          }
        ]
      }
    ]
  }
}

`.codex/config.toml`

[features]
codex_hooks = true

Step 5: Add The Asset Files

The manifest references two SVG files:

plugins/caveman/assets/caveman.svg
plugins/caveman/assets/caveman-small.svg

You can copy them from the upstream repo or create your own icons with the same file names.

If you skip them, the plugin may still work, but the UI icons can be missing or broken.

Step 6: Restart VS Code And Reopen Codex

After the files are in place:

close any open Codex session in VS Code
reload the VS Code window
reopen Codex
open the plugin list or marketplace view
install Caveman

If you used the optional .codex hook files, you should also see the startup message when a session starts or resumes.

Step 7: Test It

Try prompts like:

Use caveman mode
$caveman full
$caveman ultra
stop caveman

If the plugin is installed correctly, Codex responses should become much more compressed.

Common Problems

The Plugin Does Not Show Up

Check these first:

marketplace.json is valid JSON
the plugin path is exactly ./plugins/caveman
plugin.json is inside plugins/caveman/.codex-plugin/
you reloaded VS Code after adding the files

The Skill Does Not Trigger

Check:

skills in plugin.json is set to ./skills/
the skill file path is exactly plugins/caveman/skills/caveman/SKILL.md
the frontmatter at the top of SKILL.md is valid

Hooks Do Not Run

Check:

.codex/config.toml contains codex_hooks = true
.codex/hooks.json is valid JSON
you restarted or resumed the Codex session

Final Notes

For a single repo, the repo-local setup is simplest.

For multiple repos, the home-local setup is cleaner because you install the plugin once and reuse it everywhere.

Upstream project:

Caveman on GitHub

How To Install Caveman In Codex On macOS And Windows

What Caveman Does

Files You Need

Folder Layout

Option 1: Install In One Project Only

macOS

Windows

Option 2: Install As A Home-Local Plugin

macOS

Windows

Step 1: Add The Plugin Manifest

Step 2: Add The Skill File

Step 3: Add The Marketplace Entry

Step 4: Add The Optional Auto-Start Hook

`.codex/hooks.json`

`.codex/config.toml`

Step 5: Add The Asset Files

Step 6: Restart VS Code And Reopen Codex

Step 7: Test It

Common Problems

The Plugin Does Not Show Up

The Skill Does Not Trigger

Hooks Do Not Run

Final Notes

Tags

Author

Stats

Published

You Might Also Like

Getting started with caveman, a lightweight and flexible PHP framework, can be a great way to build robust web applications. Caveman is desi