git clone https://github.com/JuliusBrussee/caveman.git
cd caveman
.\install.ps1

const PROVIDERS = [
  // ...
  { id: 'codex', label: 'Codex CLI', mech: 'npx skills add (codex)',
    detect: 'command:codex', profile: 'codex' },
  // ...
];

Installed 7 skills
  ✓ caveman
  ✓ cavecrew
  ✓ caveman-commit
  ✓ caveman-compress
  ✓ caveman-help
  ✓ caveman-review
  ✓ caveman-stats

# caveman 仓库根目录下执行
Copy-Item -Path ".\.agents\skills\caveman" `
          -Destination "$env:USERPROFILE\.codex\skills\caveman" -Recurse -Force
Copy-Item -Path ".\.agents\skills\cavecrew" `
          -Destination "$env:USERPROFILE\.codex\skills\cavecrew" -Recurse -Force
Copy-Item -Path ".\.agents\skills\caveman-commit" `
          -Destination "$env:USERPROFILE\.codex\skills\caveman-commit" -Recurse -Force
Copy-Item -Path ".\.agents\skills\caveman-compress" `
          -Destination "$env:USERPROFILE\.codex\skills\caveman-compress" -Recurse -Force
Copy-Item -Path ".\.agents\skills\caveman-help" `
          -Destination "$env:USERPROFILE\.codex\skills\caveman-help" -Recurse -Force
Copy-Item -Path ".\.agents\skills\caveman-review" `
          -Destination "$env:USERPROFILE\.codex\skills\caveman-review" -Recurse -Force
Copy-Item -Path ".\.agents\skills\caveman-stats" `
          -Destination "$env:USERPROFILE\.codex\skills\caveman-stats" -Recurse -Force

/caveman          # full（默认）
/caveman lite     # 轻度——去填充词，保留完整句子
/caveman ultra    # 极端——仅保留核心信息

---
name: caveman
description: >
  Ultra-compressed communication mode. Cuts output tokens 65% (measured)
  by speaking like caveman while keeping full technical accuracy.
---

Respond terse like smart caveman. All technical substance stay. Only fluff die.

ACTIVE EVERY RESPONSE. No revert after many turns. No filler drift.
Still active if unsure. Off only: "stop caveman" / "normal mode".

Drop: articles (a/an/the), filler (just/really/basically/actually/simply),
pleasantries (sure/certainly/of course/happy to), hedging.
Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for").

Technical terms exact. Code blocks unchanged. Errors quoted exact.

ALWAYS keep technical terms, code, API names, CLI commands,
commit-type keywords (feat/fix/...), and exact error strings verbatim.

| Level | What change |
|-------|------------|
| lite  | No filler/hedging. Keep articles + full sentences. Professional but tight |
| full  | Drop articles, fragments OK, short synonyms. Classic caveman. |
| ultra | Strip conjunctions when cause-then-effect stay unambiguous. One word when one word enough. |

// caveman-activate.js: 写入模式标记
const mode = getDefaultMode();
safeWriteFlag(flagPath, mode);

function getDefaultMode() {
  // 1. 环境变量（最高优先级）
  const envMode = process.env.CAVEMAN_DEFAULT_MODE;
  if (envMode && VALID_MODES.includes(envMode.toLowerCase())) {
    return envMode.toLowerCase();
  }
  // 2. 仓库级配置（check-in 到代码仓库中）
  const repoConfigPath = findRepoConfigPath(process.cwd());
  if (repoConfigPath) { /* ... */ }
  // 3. 用户级配置（~/.config/caveman/config.json）
  const userMode = readModeFromConfigFile(getConfigPath());
  if (userMode) return userMode;
  // 4. 默认值
  return 'full';
}

// caveman-activate.js: 按当前模式过滤规则表
const body = skillContent.replace(/^---[\s\S]*?---\s*/, '');

const filtered = body.split('\n').reduce((acc, line) => {
  const tableRowMatch = line.match(/^\|\s*\*\*(\S+?)\*\*\s*\|/);
  if (tableRowMatch) {
    // 只保留当前模式的强度行
    if (tableRowMatch[1] === modeLabel) acc.push(line);
    return acc;
  }
  // 只保留当前模式的示例行
  const exampleMatch = line.match(/^- (\S+?):\s/);
  if (exampleMatch) {
    if (exampleMatch[1] === modeLabel) acc.push(line);
    return acc;
  }
  acc.push(line);
  return acc;
}, []);

// caveman-mode-tracker.js: 每轮强制提醒
if (activeMode && !INDEPENDENT_MODES.has(activeMode)) {
  process.stdout.write(JSON.stringify({
    hookSpecificOutput: {
      hookEventName: "UserPromptSubmit",
      additionalContext: "CAVEMAN MODE ACTIVE (" + activeMode + "). " +
        "Drop articles/filler/pleasantries/hedging. Fragments OK. " +
        "Code/commits/security: write normal."
    }
  }));
}

# benchmarks/run.py: 核心对比逻辑
NORMAL_SYSTEM = "You are a helpful assistant."
SKILL_PATH = REPO_DIR / "skills" / "caveman" / "SKILL.md"

# 对每个 Prompt，分别用两种 System Prompt 调用 API
for mode, system in [("normal", NORMAL_SYSTEM), ("caveman", caveman_system)]:
    for t in range(1, trials + 1):
        result = call_api(client, model, system, prompt_text)
        entry[mode].append(result)

# 计算中位数和节省比例
normal_medians = statistics.median([t["output_tokens"] for t in entry["normal"]])
caveman_medians = statistics.median([t["output_tokens"] for t in entry["caveman"]])
savings = 1 - (caveman_medians / normal_medians) if normal_medians > 0 else 0

{
  "prompts": [
    { "id": "react-rerender", "category": "debugging",
      "prompt": "Why is my React component re-rendering..." },
    { "id": "auth-middleware-fix", "category": "bugfix",
      "prompt": "My Express auth middleware is letting expired JWT tokens through..." },
    { "id": "postgres-pool", "category": "setup",
      "prompt": "How do I set up a PostgreSQL connection pool in Node.js..." },
    { "id": "git-rebase-merge", "category": "explanation",
      "prompt": "Explain the difference between git rebase and git merge..." },
    { "id": "async-refactor", "category": "refactor",
      "prompt": "Refactor this callback-based Node.js function to use async/await..." },
    { "id": "microservices-monolith", "category": "architecture",
      "prompt": "We have a monolithic Django app that's getting slow..." },
    { "id": "pr-security-review", "category": "code-review",
      "prompt": "Review this Express route handler for security issues..." },
    { "id": "docker-multi-stage", "category": "devops",
      "prompt": "Write a multi-stage Dockerfile for a Node.js TypeScript application..." },
    { "id": "race-condition-debug", "category": "debugging",
      "prompt": "My Node.js API endpoint that increments a counter..." },
    { "id": "error-boundary", "category": "implementation",
      "prompt": "Implement a React error boundary component..." }
  ]
}

## When caveman wins

- Long chatty outputs — anywhere the model would write 1k+ output tokens
  per reply. This is where the 50-87% cuts happen.
- Long sessions with verbose agents. The per-reply savings compound;
  the fixed ~1-1.5k/turn rule cost stays flat.

## When caveman loses (net-negative)

- Terse coding Q&A. If your normal replies are ~150 output tokens, caveman
  saves maybe 70-100 of them and costs ~1k+ of input overhead per turn.
  Net loss.
- Session-level totals are always smaller than the output-reduction headline,
  because input tokens (your prompts, your context, your files, the injected
  rules) dwarf output tokens in agentic coding. Independent session-level
  measurements land around 14-21% total savings on output-heavy workloads —
  and below zero on terse ones.
- Agents that bill by request or credit, not tokens. GitHub Copilot charges
  premium requests. A shorter answer is the same request.

## Rule of thumb

> Normal reply longer than ~1.5-2k output tokens → caveman probably saves you money.
> Normal reply shorter than that, or you pay per request → caveman probably costs you money.
> Either way, caveman replies faster to read. That part is free.

# compress.py: 压缩前置处理——分离 YAML 头
def split_frontmatter(text: str):
    m = FRONTMATTER_REGEX.match(text)
    if m:
        return m.group(1), m.group(2)
    return "", text

# compress.py: 压缩流程
frontmatter, body = split_frontmatter(original_text)
compressed_body = call_claude(build_compress_prompt(body))
compressed = frontmatter + compressed_body

// caveman-shrink/index.js: 中间件主循环
function transformResponse(msg) {
  const r = msg.result;
  for (const arrayName of ['tools', 'prompts', 'resources', 'resourceTemplates']) {
    if (Array.isArray(r[arrayName])) {
      for (const item of r[arrayName]) {
        for (const field of fields) {
          if (typeof item[field] === 'string') {
            const { compressed } = compress(item[field]);
            if (compressed !== item[field]) {
              item[field] = compressed;
            }
          }
        }
      }
    }
  }
  return msg;
}

// caveman-shrink/compress.js: 受保护的模式——压缩前先替换为占位符
const PROTECTED_PATTERNS = [
  /```[\s\S]*?```/g,                    // fenced code
  /`[^`\n]+`/g,                         // inline code
  /\bhttps?:\/\/\S+/gi,                 // URLs
  /[\w.-]*[\/\\][\w.\/\\\-]+/g,         // paths with / or \
  /[A-Z][A-Za-z0-9]*(?:_[A-Z][A-Za-z0-9]*)+\b/g, // CONST_CASE
  /\b\w+\.\w+(?:\.\w+)*\(\)?/g,         // dotted.method or pkg.fn()
  /[A-Za-z_][A-Za-z0-9_]*\s*\([^)]*\)/g, // function calls
];

// caveman-shrink/compress.js: 文本压缩规则
function compressProse(text) {
  let s = text;
  s = s.replace(LEADERS, '');      // 去除句首引导词
  s = s.replace(PLEASANTRIES, '');  // 去除礼貌语
  s = s.replace(HEDGES, '');        // 去除模糊词
  s = s.replace(FILLERS, '');       // 去除填充词
  s = s.replace(ARTICLES, '');      // 去除冠词
  s = s.replace(/[ \t]{2,}/g, ' '); // 合并多余空白
  return s.trim();
}

SessionStart Hook
  │
  ├── caveman-config.js: getDefaultMode() 决定当前模式
  ├── caveman-activate.js: 读取 SKILL.md → 按模式过滤 → 注入规则
  └── 写入 .caveman-active 标记文件
        │
        ▼
UserPromptSubmit Hook（每次用户输入触发）
  │
  ├── caveman-mode-tracker.js: 检测 /caveman / stop 等命令
  ├── 更新标记文件（模式切换或关闭）
  └── 注入 "CAVEMAN MODE ACTIVE" 每轮提醒
        │
        ▼
模型生成回复
  │
  ├── 遵守 SKILL.md 规则条生成输出
  ├── 代码块/c ommands/URLs 不变
  └── 输出 Token 减少平均 65%
        │
        ▼
/caveman-stats 读取会话日志
  └── 按模式归属计算实际节省量