DEV Community

Cover image for How To Install Caveman In Codex On macOS And Windows
Gan Mahmud
Gan Mahmud

Posted on

How To Install Caveman In Codex On macOS And Windows

#caveman #codex #ai #programming

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:

  1. a plugin folder: plugins/caveman
  2. a marketplace file: .agents/plugins/marketplace.json
  3. 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Windows

If your project lives at:

C:\Users\your-name\code\my-app
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

If you also want Codex hooks globally, use:

~/.codex/hooks.json
~/.codex/config.toml
Enter fullscreen mode Exit fullscreen mode

Windows 

C:\Users\your-name\plugins\caveman
C:\Users\your-name\.agents\plugins\marketplace.json
Enter fullscreen mode Exit fullscreen mode

If you also want Codex hooks globally, use:

C:\Users\your-name\.codex\hooks.json
C:\Users\your-name\.codex\config.toml
Enter fullscreen mode Exit fullscreen mode

Step 1: Add The Plugin Manifest

Create:

plugins/caveman/.codex-plugin/plugin.json
Enter fullscreen mode Exit fullscreen mode

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": []
  }
}
Enter fullscreen mode Exit fullscreen mode

Step 2: Add The Skill File

Create:

plugins/caveman/skills/caveman/SKILL.md
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

Step 3: Add The Marketplace Entry

Create:

.agents/plugins/marketplace.json
Enter fullscreen mode Exit fullscreen mode

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"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
          }
        ]
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

.codex/config.toml 

[features]
codex_hooks = true
Enter fullscreen mode Exit fullscreen mode

Step 5: Add The Asset Files

The manifest references two SVG files:

plugins/caveman/assets/caveman.svg
plugins/caveman/assets/caveman-small.svg
Enter fullscreen mode Exit fullscreen mode

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:

  1. close any open Codex session in VS Code
  2. reload the VS Code window
  3. reopen Codex
  4. open the plugin list or marketplace view
  5. 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:

Top comments (0)