Adversarial review against a live Hermes Agent install (v0.11.0) found the
forward install was correct (skills land in the real ~/.hermes/skills/
productivity/<skill>/ layout, all 7 load as 'enabled' via 'hermes skills
list' — verified empirically, no version: field required), but uninstall had
NO Hermes handling: --uninstall silently orphaned all 7 skill folders forever.
- add Hermes block to uninstall() honoring HERMES_HOME (mirrors opencode/openclaw)
- tests/installer/hermes.test.mjs: install lands 7 skills, uninstall removes
them (regression guard for the asymmetry), dry-run uninstall is a no-op
- INSTALL.md: add Hermes Agent row to the per-agent install table (CLAUDE.md
mandates the install table stay complete)
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- restore 2-space PROVIDERS indent and 4-space dispatch-loop indent (PR
re-indented existing gemini/opencode/openclaw lines as churn)
- correct mech label: 'native hermes skills copy' (it does a native dir
copy via installHermes, not 'npx skills add')
- drop dead profile: 'hermes' — shadowed by the installHermes special-case
and not a valid upstream vercel-labs/skills slug
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
PR #527 added cavecrew-model-overrides.js with a wrong sha256 (eae3... vs
actual 9f26...) and modified caveman-activate.js without regenerating its
entry. bin/install.js verifies downloaded hooks against this manifest and
aborts on mismatch, so both were latent install-breakers on the remote path.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
First tag shipping src/hooks/checksums.sha256 — with PINNED_REF now
pointing at it, curl|bash / detached installs fetch hook files from the
immutable v1.9.0 ref and SHA-256 enforcement activates fully (#261,
#262). Manifest verified current against src/hooks/ before the bump.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Smoke-tested against real opencode 1.4.0 (the missing verification
flagged in 22f75e3) — the plugin never loaded: opencode runs plugins
inside a compiled Bun binary where require() of on-disk files is
rejected ('require() async module is unsupported') and await import()
of a CJS file returns an empty namespace. caveman-config.cjs is now
evaluated as CommonJS by hand (readFileSync + Function wrapper with a
createRequire shim — built-ins still resolve fine).
Three more real-runtime gaps found and fixed in the same pass:
- session-init flag write now also happens at plugin factory time; in
one-shot 'opencode run' the first session.created publishes before
plugin event dispatch is wired, so the event handler alone missed it
- the TUI expands '/caveman <level>' into the command template before
chat.message fires; the parser now recovers the level from the
expanded 'Activate caveman mode: <level>' text
- the non-interactive run path wraps messages in literal quotes
('"/caveman ultra"'); the parser unwraps symmetric quotes
Verified end-to-end against opencode 1.4.0: plugin loads clean,
session-init writes the flag, /caveman ultra flips it, 'stop caveman'
deletes it, and the reinforcement line shows up in the outgoing LLM
system prompt.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Counts were stale after the opencode + openclaw targets landed (5 -> 6
repo files, 7 with the openclaw line). Tests also ran the openclaw
installer against the developer's real ~/.openclaw/workspace; runInit()
now pins OPENCLAW_WORKSPACE inside the fixture tmp dir so nothing
escapes the sandbox. verify_repo.py drops the removed
.agents/plugins/marketplace.json from its manifest list.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
.junie/, .kiro/, .roo/, .agents/ held pre-cleanup cavecrew/SKILL.md
mirrors (plus an unused .agents/plugins/marketplace.json). Nothing in
the current install path reads them — bin/install.js handles Codex via
npx skills add, and Claude Code marketplace discovery uses
.claude-plugin/marketplace.json. CLAUDE.md marks these remove-on-sight.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a Sponsors section to README promoting Atlas Cloud with a centered logo, link, and a call to sponsor the project. Include two new SVG assets (atlas-cloud.svg and atlas-cloud-dark.svg) under docs/assets for light/dark mode logo display.
Verbatim copies of edited sources into the CI-managed plugins/caveman mirror and rebuilt dist/caveman.skill, so local main is self-consistent without a push. CI's sync-skill.yml regenerates these on push; this just keeps verify_repo green locally.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Folds in #419 (replace the non-existent session.created/tui.prompt.append hooks with real opencode hooks: event dispatcher for session.created, chat.message for mode parsing, experimental.chat.system.transform for reinforcement; fixes #418/#421), #398 (ship the missing caveman-compress.md command + un-ignore it; fixes #426/#451/#464), and #376 plugin-side (drop %APPDATA% branch). Smoke test rewritten for the new hook shapes. NOTE: not smoke-tested against a real opencode runtime here — verify before release.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Installer fixes: #414 (rename PS1 $Args->$InstallerArgs), #437 (detect Copilot via extension dirs, fixes#336), #395 (--skill '*' instead of --all so -a <agent> is honored, fixes#389), #472 (prune orphaned managed hooks from settings.json, fixes#471), #393 (don't double-wire hooks when the plugin manifest already does, fixes#392), #380 (MCP-shrink off by default, requires an upstream, fixes#474), #376 install-side (opencode uses ~/.config/opencode, drop %APPDATA%), #443 (strip tools: from cavecrew agent copies for opencode, #386), #434 (existsSync guard on command copy), #396 (doc: discover profile slugs via --list).
Security hardening: #261 (pin remote fetch to release tag PINNED_REF=v1.8.2, not moving main) and #262 (SHA-256-verify downloaded hook files against src/hooks/checksums.sha256 before they execute; abort on mismatch). #260 (inspect-before-run note). NOTE: enforcement activates fully once a release tag shipping checksums.sha256 is published and PINNED_REF is bumped; v1.8.2 predates the manifest so downloads there warn-and-proceed.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Folds in #429 (repo-local <repo>/.caveman/config.json resolution layer between env and user config; symlink-safe, bounded walk) and #248 intent (recognize 'less tokens'/'be brief'/'be terse' as natural-language caveman activation).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Folds in #387 — extract spawn options to spawn-options.js; shell:true only on win32 (PATHEXT resolution), POSIX unchanged. Args still come from installer-controlled config (trust boundary unchanged).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Folds in #438 — the docs demo terminal interpolated user input via innerHTML (real reflected/DOM XSS); build nodes with textContent instead. (PR title 'CLI input handler' was a misnomer.)
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Folds in #466 (correct Opus 4.5-4.8 output price to $25/M, keep legacy 4.0/4.1 carve-outs at $75/M; fixes#465) and #459 (UTF-8 console + Get-Content so the pickaxe renders on Windows; +spacing).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Folds in #388 (pin claude subprocess to utf-8, fixes#152 Windows cp1252 crash), #435 (resolve claude via shutil.which for .cmd shims), #424 (preserve YAML frontmatter across compression), #420 (write .original.md backups outside the source tree; cross-platform base dir incl. Windows %LOCALAPPDATA%).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replace the top-of-README alert banner with a centered callout card
placed right after the savings proof, where the reader is most sold.
Cross-sells caveman-code (the full terminal coding agent) on the
momentum of the compression demo.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add a prominent caveman-code callout to the README hero and a
caveman-code row to the ecosystem table. Swap the rock emoji for
the dancing-rock SVG logo across the README, the compress skill
README, and the docs-site cursor.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
curl|bash one-liner stdin is not a TTY, so the upstream skills CLI
renders its interactive skill-picker TUI with nothing selected, exits
0, and installs zero skills — while our installer reports "done".
Pass --yes --all to skip the picker and confirmation prompts in both
the per-provider call and the auto-detect fallback.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- PR #372 (Dave): strip YAML fences from commands/caveman-init.toml — Gemini CLI's FileCommandLoader rejected the file with 'Failed to parse TOML' on extension install. Verified main was broken.
- PR #350 intent (David): rename codex_hooks → hooks in .codex/config.toml. Codex source confirms canonical key is now 'hooks'; codex_hooks is a legacy alias that emits a deprecation log.
Closes#372#326 (duplicate) #350 locally — push deferred.
Two bugs at the curl|bash entry point made the headline install command
fail immediately:
1. install.sh used `${BASH_SOURCE[0]}` under `set -u`. That variable is
unset when bash is invoked from stdin (curl | bash), tripping the
nounset trap before we ever reached the npx fallback.
2. install.sh + install.ps1 passed `--` between npx and the package args.
On modern npm, npx forwards the literal `--` to bin/install.js, which
parseArgs rejected as an unknown flag.
Fix:
- install.sh: default BASH_SOURCE[0] to empty so the curl-pipe path falls
through cleanly under set -u.
- install.sh + install.ps1: drop the `--` separator. npm 7+ npx already
forwards trailing args correctly.
- bin/install.js parseArgs: accept a bare `--` as a no-op (POSIX
end-of-options marker) so future shim drift can't re-break this.
- New regression test asserts `--` is accepted.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Refactor and harden the unified Node installer and related docs. Major changes:
- bin/install.js: validate --only ids, expand ~ for --config-dir, make Claude/install flows async (await hooks/init), add many CLI flags (--no-mcp-shrink, --with-hooks/--no-hooks, --skip-skills, --config-dir docs), preserve original backups once, avoid overwriting plugin/command files unless --force, and add opencode AGENTS.md fenced begin/end markers so installs/uninstalls can append/strip cleanly. Also add opencode idempotency probes for claude/gemini uninstall paths and better handling of opencode plugin payload.
- bin/lib/settings.js: safer removeCavemanHooks that validates shapes before mutating hooks.
- runInit/installHooks/downloadTo calls made async and awaited; runInit returns promise now.
- Docs and README/INSTALL/CONTRIBUTING/CLAUDE.md/src/hooks/README.md: update user-facing text to match new flags/behaviour, standardize use of $CLAUDE_CONFIG_DIR, clarify --with-init semantics, and note opencode/openclaw handling. Change command name usages from `/caveman:compress` to `/caveman-compress`.
- opencode: write fenced caveman block to AGENTS.md and handle legacy unfenced blocks; tests updated to expect fence markers.
These changes improve idempotency, safer upgrades/uninstalls, clearer UX around per-repo vs per-user init, and make the opencode rule block removable without destroying user content.
OpenClaw is a self-hosted gateway that orchestrates multiple agents and
loads workspace skills on-demand. To make caveman always-on through it we
write a spec-correct skill folder plus a marker-fenced bootstrap block in
SOUL.md (which OpenClaw auto-injects every turn). Both writes are
idempotent and reachable from `bin/install.js --only openclaw` and
`caveman-init.js --only openclaw`. Side-effect: `--only <id>` now bypasses
the detect-match guard so explicit opt-in works for any provider whose
preconditions can't be probed (e.g. custom OPENCLAW_WORKSPACE paths).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replaces opencode's Tier-4 npx-skills entry with a native in-repo plugin
that mirrors the Claude Code hook architecture (session.created +
tui.prompt.append) using opencode's lifecycle hook system. Reaches Tier-1
parity minus the statusline (opencode TUI exposes no plugin-writable
badge). Skill files drop in unchanged — opencode reads SKILL.md natively.
Plugin reuses src/hooks/caveman-config.js for the symlink-safe flag-write
helpers via createRequire (renamed .cjs post-install to coexist with the
plugin dir's "type":"module"). AGENTS.md provides a Tier-3 always-on
fallback if the plugin runtime breaks.
5 new tests cover fresh install, idempotency, JSONC tolerance of
pre-existing opencode.json, uninstall, and a plugin smoke test that fires
synthetic tui.prompt.append events. All 38 installer tests pass.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Brings the long-stashed Node installer onto main. install.sh and install.ps1
shrink to thin shims (~50 lines each) that delegate to bin/install.js, fixing
the cross-platform drift that caused #249-class quoting bugs.
- bin/install.js (850 lines) — unified PROVIDERS-driven installer
- bin/lib/settings.js (221 lines) — JSONC parser + hook validator
(validateHookFields prevents single bad hook from poisoning settings.json)
- tests/installer/{unit.argv,unit.settings,e2e.dryrun}.test.mjs — npm test
now actually runs four real tests (was silently passing 0)
- .agents/skills/cavecrew, .junie/, .kiro/, .roo/ — per-agent skill mirrors
- skills-lock.json — vercel-labs/skills slug pinning
- install.{sh,ps1}.legacy escape hatch dropped (git history is the fallback)
- Minor cavecrew agent description refinements
Closes the gap between docs (already merged) describing bin/install.js and
the actual implementation.
Reflect the post-cleanup repo layout: consolidated caveman-compress
under skills/, removed agent-dotdir mirrors, build artifacts in dist/,
per-skill READMEs alongside SKILL.md, bin/install.js as the only
installer entry point, and INSTALL.md for the per-agent reference.
Adds a top-level "What lives where" tree, trims the auto-synced table
to what CI actually mirrors, and updates the key rules accordingly.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Real install harness — writes hooks, merges settings.json, asserts on-disk
state. Catches regressions a dry-run can't see (missing hooks, malformed
settings, broken statusline). Five cases:
- Fresh install populates hooks dir + wires SessionStart/UserPromptSubmit
- Idempotent install does not duplicate hook entries
- Uninstall strips caveman hooks, preserves user-authored ones
- Install tolerates JSONC settings.json (#249 regression guard)
- Lib-level addCommandHook idempotency (always runs, no claude CLI)
Tests requiring `claude` on PATH skip cleanly with a clear reason. Uninstall
test strips claude/gemini from PATH so the user's real plugin/extension
state is never touched.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Trim README from 16.4 KB to 10.2 KB (~38% shorter, 331 -> 220 lines)
so non-technical readers can scan it in 60 seconds. Front door now
keeps the Before/After pitch, one-line install, top-6 manual install
table, condensed feature matrix, real benchmark numbers, and a short
"how it work" section in caveman voice.
Moves to other docs:
- Full 30+ agent install matrix and detailed flag reference -> INSTALL.md
- Hook architecture deep-dive -> CLAUDE.md (already there)
- Eval methodology paragraphs -> evals/ link
Caveman voice phrases preserved ("Brain still big", "Cost go down
forever", "One rock. Two rock. Three rock. That it.", "caveman speak").
Benchmark numbers untouched (verbatim from benchmarks/results/). All
top-of-funnel install commands still work.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Drop CI-generated mirrors that self-applied caveman to this repo when
opened in Cursor/Windsurf/Cline/Copilot. The installer never read them
(bin/install.js consumes only hooks/, rules/, tools/, agents/, skills/,
mcp-servers/, plugins/caveman/), so removing them just declutters the
root. Devs who want self-application can opt in via npx caveman --only
<agent>.
Removed:
- .cursor/skills/, .cursor/rules/caveman.mdc
- .windsurf/skills/, .windsurf/rules/caveman.md
- .clinerules/caveman.md
- .github/copilot-instructions.md
- caveman/SKILL.md (and empty caveman/ parent)
Updated .github/workflows/sync-skill.yml: drop the cp + mkdir lines and
git add paths for those mirrors, drop the entire "Sync auto-activation
rules" step, and drop rules/caveman-activate.md from the paths: trigger
since the workflow no longer consumes it. plugins/caveman/, cavecrew,
compress, and caveman.skill ZIP sync steps are preserved.
Updated CONTRIBUTING.md note to reflect the smaller auto-synced set.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Move caveman-compress/ source (SKILL.md, scripts/, README.md, SECURITY.md) to skills/caveman-compress/.
- Delete skills/compress/ — the CI-generated rename mirror that caused dual-source confusion.
- Move plugins/caveman/skills/compress/ to plugins/caveman/skills/caveman-compress/. Plugin keeps the consolidated name; CI no longer rewrites the frontmatter.
- Replace the two sed-heavy CI sync steps with one verbatim cp -r from source to plugin.
- Update verify_repo.py, test_compress_safety.py, test_validate_inline.py, GEMINI.md, AGENTS.md, CONTRIBUTING.md, README.md, and the workflow paths to reference the new location.
- Use Path.resolve().parents[N] for the benchmark.py repo-root walk now that the directory depth changed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Expand the 25-line stub to a scannable 190-line guide reflecting the
post-cleanup repo layout. Adds:
- Sources-of-truth table covering all editable skill, agent, hook, and
installer files (skills/caveman-compress/, bin/install.js PROVIDERS,
tools/caveman-init.js, mcp-servers/caveman-shrink/).
- CI-mirrors table calling out plugins/caveman/* and dist/caveman.skill
as auto-rebuilt, edits-will-be-reverted.
- Step-by-step recipes for adding a new agent (PROVIDERS row +
--list verification) and a new skill (frontmatter + sync workflow).
- Test commands (npm test, compress safety, init, symlink), benchmark
and eval invocations, PR guidelines, and the load-bearing code-style
invariants (silent-fail hooks, JSONC-tolerant settings.js,
safeWriteFlag, CLAUDE_CONFIG_DIR).
Preserves caveman voice in the framing and Ideas section.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Splits install guidance out of README into a dedicated INSTALL.md so
users can find the install path in one glance. Covers the one-liner,
per-agent table for all 33 providers, manual install, verify, uninstall,
troubleshooting, and a privacy note. README and installer source are
unchanged.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The caveman.skill ZIP is regenerated by CI on every push and lived at
the repo root, where users mistook it for an editable source. Moving it
to dist/ makes its build-product nature obvious while keeping it
tracked so GitHub release links and npm packaging keep working.
Updates:
- git mv caveman.skill -> dist/caveman.skill
- .github/workflows/sync-skill.yml rebuild step now writes to dist/
- .gitignore ignores dist/* but allows dist/caveman.skill
- package.json files array includes dist/caveman.skill for npm pack
- CONTRIBUTING.md and tests/verify_repo.py path references updated
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add a human-facing README.md to each skill directory so users browsing
skills/ can quickly see what each skill does, how to invoke it, and an
example output. Mirrors the per-skill README pattern used by upstream
skill libraries (vercel-labs/skills, claude-code-sdk).
SKILL.md remains the LLM-facing system prompt; README.md is the human
front door.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
CLAUDE.original.md was a backup snapshot from the initial caveman-compress
of the project's own CLAUDE.md. It is not referenced by any tooling — the
mentions in caveman-compress/README.md and tests/test_caveman_stats.js
describe the compress skill's output naming convention, not this file.
The other deletion targets from the cleanup brief (install.sh.legacy,
install.ps1.legacy, .junie/, .kiro/, .roo/, .agents/) either don't exist
in this branch or — in the case of .agents/plugins/marketplace.json — are
real manifests verified by tests/verify_repo.py.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
caveman-shrink@0.1.0 is now live on npm (pre-1.0). Restore the original
default-on behavior for --with-mcp-shrink / -WithMcpShrink. Keep the
`npm view caveman-shrink` probe — a transient registry outage now degrades
to a clean manual-config skip instead of registering a `npx -y caveman-shrink`
entry that would have spawned-failed.
Also: sync `model: haiku` onto cavecrew investigator/reviewer canonicals
so the top-level agents/ matches the synced plugins/caveman/agents/.
README + CLAUDE.md flipped back to "On by default."
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
install.sh:
- detect_match: replace `awk -v RS='||'` (rejected by macOS BSD awk:
"illegal primary in regular expression") with bash parameter expansion.
Compound detection specs were silently failing, so cursor / windsurf /
continue / and 28 other compound-spec providers were never detected.
- --with-mcp-shrink: flip default OFF + probe `npm view caveman-shrink`
before registering. Was registering a config that 404s on first spawn.
install.ps1: mirror the MCP-shrink default flip + npm probe.
tests: update statusline tests for default-on suffix behavior. Add a
regression for fresh installs where the suffix file is absent.
Add npm-pkg-fix formatting to package.json.
cavecrew: promote agents/cavecrew-*.md to top-level canonical, refine
subagent contracts (sharper output formats, terminal refusal
lines, model: haiku for read-only roles). CI workflow syncs
agents/ + skills/cavecrew/ into plugins/caveman/.
docs: README & CLAUDE.md align with new opt-in MCP-shrink policy.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- caveman-stats: dollar math via per-million model pricing, --share
tweetable line, lifetime log via symlink-safe appendFlag, --all and
--since N[d|h] aggregation, opt-in statusline savings suffix, and
detection of *.original.md compress backups for input-side savings.
- install.sh / install.ps1 at repo root: smart multi-agent installer
that detects Claude Code, Gemini, Codex, Cursor, Windsurf, Cline,
Copilot and runs each one's native install. Idempotent, --dry-run,
--only, --force.
- cavecrew: skills/cavecrew + three Claude Code subagents
(investigator / builder / reviewer) for caveman-style machine-to-
machine handoffs.
- cavepack: tools/caveman-init.js drops the always-on caveman rule
into Cursor / Windsurf / Cline / Copilot / AGENTS.md in one shot,
idempotent, with a sentinel check so re-runs never duplicate.
- caveman-shrink: MCP middleware proxy + pure-Node prose compressor
that strips articles/filler/hedging from tools/list descriptions
while preserving code, URLs, paths, and identifiers byte-for-byte.
59 tests passing (27 stats, 8 init, 12 mcp-shrink, 12 symlink-flag).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
New slash command that reads the active Claude Code session JSONL
(.claude/projects/**/*.jsonl), sums output_tokens and
cache_read_input_tokens from assistant turns, and shows an estimated
savings figure when the active mode is 'full'.
Real numbers, not the model's guess:
Caveman Stats
──────────────────────────────────
Session: ...projects/my-app/abc123.jsonl
Turns: 47
──────────────────────────────────
Output tokens: 3,210
Cache-read tokens: 128,400
──────────────────────────────────
Est. without caveman: 9,171
Est. tokens saved: 5,961 (~65%)
Savings est. from benchmarks/ (mean per-task). Actual varies by task.
Implementation:
* hooks/caveman-stats.js — script. Run directly with
`node hooks/caveman-stats.js`, or via `--session-file <path>`.
Falls back to most-recent JSONL under .claude/projects/ when no
session file is passed.
* hooks/caveman-mode-tracker.js — `/caveman-stats` triggers an
execFileSync call to caveman-stats.js with the hook's transcript_path,
and the output is returned via `decision: "block"` so the user sees
the stats inline without a model round-trip.
* install.sh / install.ps1 / uninstall.{sh,ps1} include
caveman-stats.js in HOOK_FILES.
* skills/caveman-stats/SKILL.md (+ plugin mirror) for skill listing.
* README install matrix and Caveman Skills section updated.
Compression ratio (0.65) is the mean per-task figure from
benchmarks/results/*.json (avg_savings: 65 across 10 tasks). Only 'full'
mode has measured data — lite/ultra/wenyan show no estimate.
Tests: 6 passing in tests/test_caveman_stats.js covering direct
invocation, full-mode estimate math, non-full skip, no-session error,
mode-tracker block behavior, and flag preservation.
Closes#305 (re-implementation; takes the design from
@DeeptimaanB but rewritten against current main).
Co-Authored-By: Deeptimaan Banerjee <DeeptimaanB@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Codex install line now says "Open Codex in repo" before /plugins,
removing first-time-user ambiguity (#226 by @cirops).
* Windows manual fallback section: PowerShell block to copy SKILL.md
into the plugin path and patch marketplace.json by hand when
automated install fails (#258 by @Abbasam8910). Plugin-skill only;
doesn't install standalone hooks/statusline.
Skipped from this batch:
* #290 (75% → 50% headline numbers) — leaving the headline figure as is.
* #295 (Pages link) — not advertising the Pages site in the README.
Co-Authored-By: Ciro Plá <cirops@users.noreply.github.com>
Co-Authored-By: ABBAS A M <Abbasam8910@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three small SKILL.md edits batched:
* Ultra mode: spell out that abbreviation applies to prose only, never to
code symbols, function names, API names, or error strings (#238 by
@AnthoHansen). Stops models from rendering literal `fn` in code where
the user wrote `function`.
* Auto-clarity (#239 by @AnthoHansen): bullet list replaces run-on
sentence; adds explicit trigger for compression-induced ambiguity in
technical sequences (e.g. "migrate table drop column backup first").
* Typst + LaTeX (#243 by @wildwestrom): add .typ, .typst, .tex to
COMPRESSIBLE_EXTENSIONS in caveman-compress/scripts/detect.py and to
the boundaries lists in SKILL.md / README.md.
Synced SKILL.md to caveman/, plugins/caveman/skills/caveman/,
.cursor/skills/caveman/, .windsurf/skills/caveman/, and rebuilt
caveman.skill ZIP.
Co-Authored-By: Anthony Domínguez <AnthoHansen@users.noreply.github.com>
Co-Authored-By: West <wildwestrom@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two converging hook fixes:
* /caveman arg parser uses VALID_MODES whitelist (#314 by @jgttech).
Drops the silent fallback to getDefaultMode() on unknown args. Three
bugs collapsed: /caveman full was impossible if defaultMode was set
to anything else, /caveman off had no effect, and typos like
/caveman fulll silently clobbered state. Now: bare /caveman activates
default; /caveman off|stop|disable removes flag; unknown args leave
flag untouched (no silent overwrite); independent modes (commit,
review, compress) cannot be selected as args.
* safeWriteFlag through symlinked ~/.claude (#224 by @voidborne-d,
closes#207). Earlier hardening (5ad8f6d) refused every symlinked
parent including legitimate ~/.claude → /opt/shared-claude or
/mnt/d/claude-config patterns. Now resolves the parent via
realpathSync, verifies ownership on Unix (uid match) or under-home
on Windows, and uses the resolved path for the atomic write. Flag
file itself still must not be a symlink — that's the actual clobber
vector. CAVEMAN_DEBUG=1 emits stderr diagnostics on refusal.
12 regression tests in tests/test_symlink_flag.js — all pass.
Verified:
/caveman / lite / full / ultra / wenyan{,-lite,-full,-ultra} → mode set
/caveman off / stop / disable → flag deleted
/caveman commit → no flag (rejected)
/caveman fulll (typo) → no flag (rejected)
symlink ~/.claude → owned dir → write succeeds in real dir
symlink ~/.claude → other-user dir → refused
Co-Authored-By: Jonathon Tech <jgttech@users.noreply.github.com>
Co-Authored-By: voidborne-d <voidborne-d@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
PowerShell 5.1 mangles the multiline $nodeScript when passed to
node -e — the embedded `"` after `node ` terminates the argument
early, causing SyntaxError mid-install. Hook files copy but
settings.json never updates, leaving caveman non-functional.
Write the script to %TEMP%\caveman-install-<pid>.js, run it, clean
up in a finally block. Verified clean install on Windows 11 /
PowerShell 5.1 / Node 24.
Closes#249.
Co-Authored-By: Scott Converse <scottconverse@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Five user-contributed fixes consolidated:
* UTF-8 stdout (#289 by @ousamabenyounes) — reconfigure stdout/stderr at the
top of cli.py so Windows cp1252 consoles don't crash on the ❌ glyph in
error/validation branches and mask the real error.
* Empty / unchanged compression guards (#292 by @ousamabenyounes, closes#237)
— refuse empty input, refuse empty/whitespace/identical Claude output,
read back the backup before touching the input. Five regression tests in
tests/test_compress_safety.py.
* Inline backtick validation (#309 by @hireblackout) — validate_inline_codes
closes the silent-overwrite gap where `npm install` → `yarn install`
passed validation. Wired into validate(); 11 unit tests in
tests/test_validate_inline.py.
* Frontmatter angle-bracket fix (#268 by @Bortlesboat, closes#266) —
caveman-compress/SKILL.md description now uses FILEPATH instead of
<filepath>, plus verify_repo gains a new
verify_skill_frontmatter_upload_compatibility check, UTF-8 hardening for
Windows, and the activation-banner regex no longer requires a trailing
period.
* Two test fixtures (claude-md-project.md, mixed-with-code.md) updated so
the new inline-backtick validator passes — they were silently dropping
`server/src/`, `type(scope): description`, and `status` references in
compression. The fixture is documentation of "good" compression, so the
fix is to preserve those references.
Co-Authored-By: Ben Younes <ousama.benyounes@oratelecom.net>
Co-Authored-By: hireblackout <hireblackout@users.noreply.github.com>
Co-Authored-By: Andrew Barnes <Bortlesboat@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Writes were hardened via safeWriteFlag (PRs #70/#71) but readers still
trusted whatever the flag contained. A local attacker with write access
to ~/.claude/ could symlink the flag at a secret file and have the
per-turn reinforcement inject its bytes into model context, or the
statuslines echo ANSI escapes to the terminal on every keystroke.
- caveman-config.js: new readFlag() — lstat symlink refuse, 64-byte cap,
O_NOFOLLOW, VALID_MODES whitelist. Returns null on any anomaly.
- caveman-mode-tracker.js: per-turn reinforcement routes through
readFlag() instead of fs.readFileSync.
- caveman-statusline.sh / .ps1: symlink + size refuse, strip to
[a-z0-9-], whitelist-validate before rendering.
- compress.py (3 synced copies): is_sensitive_path() denylist refuses
.env*, .netrc, keys/certs, ~/.ssh|.aws|.gnupg|.kube|.docker, and any
basename containing secret/credential/password/apikey/token/privatekey
(separator-insensitive). Fails loudly before read — no silent exfil
of credentials to the Anthropic API.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Parent-chain walk produced false positives: macOS /tmp -> /private/tmp
and symlinked home dirs broke all flag writes. Check only the immediate
parent directory and the target itself — that covers the threat model
(attacker replacing the flag with a symlink) without breaking legit
paths.
Extend safeWriteFlag() in caveman-config.js with:
- hasSymlinkInPath() walks every ancestor component and refuses
if any is a symlink (protects against parent-dir redirect)
- Atomic write via temp file + rename
- O_EXCL on temp open to prevent race
Removes duplicate local helper from mode-tracker.
Co-Authored-By: tuanaiseo <221258316+tuanaiseo@users.noreply.github.com>
Consolidate write protection into safeWriteFlag() helper in
caveman-config.js. Applied to all flag write sites:
- caveman-activate.js (SessionStart)
- caveman-mode-tracker.js slash command
- caveman-mode-tracker.js natural-language activation
Refuses symlink targets via lstat, opens with O_NOFOLLOW where
supported, writes with 0600.
Co-Authored-By: tuanaiseo <221258316+tuanaiseo@users.noreply.github.com>
Replace hardcoded intensity table and examples with runtime loading of skills/caveman/SKILL.md (single source of truth). Strip YAML frontmatter and filter the intensity table and examples to include only the active mode; fall back to a minimal built-in ruleset when SKILL.md is missing (standalone installs). Add INDEPENDENT_MODES (commit, review, compress) to short-circuit and emit a brief activation line for modes that use their own skill files. Normalize the wenyan alias to wenyan-full. Overall simplifies maintenance and prevents duplicated, stale rule text in the hook.
Replace the terse one-line caveman activation message with a full, structured ruleset and examples. Introduces INTENSITY and EXAMPLES maps (lite/full/ultra + wenyan variants), selects the active level from mode with a fallback, and builds a detailed output covering persistence, rules, examples, auto-clarity and boundaries. Rationale: anchor terse response behavior more reliably to prevent drift and provide selectable verbosity/compression profiles while preserving exact code/commit formatting.
Mode tracker wrote getDefaultMode() result to flag file even when it
returned "off". Now guards against it — same pattern as caveman-activate.
Added test coverage for off mode in both activate and tracker paths.
Also: fix swapped step comments in uninstall.sh, update stale CLAUDE.md
description for /caveman default.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Set CAVEMAN_DEFAULT_MODE=off or {"defaultMode":"off"} in config to
skip session-start activation. No flag file written, no rules injected.
User can still manually activate with /caveman.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
/caveman-help displays all modes, skills, triggers, config options,
and deactivation — one-shot display, no mode change.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Symlinks in plugins/caveman/skills/compress/ were checked out as plain
text path stubs on Windows (core.symlinks=false), causing Codex to reject
SKILL.md as missing YAML frontmatter. Replace with verbatim copies of
source files and add CI sync step to keep them in sync.
Closes#92
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Make the installer require a configured statusLine before treating hooks as already installed and ensure PowerShell 5.1 compatibility. hooks/install.ps1: stop using -AsHashtable, adjust hooks access, track presence of settings.statusLine and only skip installation when SessionStart, UserPromptSubmit and statusLine are present. hooks/install.sh: add HAS_STATUSLINE check and update the Node-based settings validation to require settings.statusLine. tests/test_hooks.py: add test_install_reconfigures_missing_statusline to verify installer adds a missing statusLine. tests/verify_repo.py: add a manifest path to the verification list and assert that -AsHashtable is not used in install.ps1 to preserve compatibility with Windows PowerShell 5.1.
Add a PowerShell statusline script (hooks/caveman-statusline.ps1) and update activation/installer logic to support Windows and avoid clobbering custom statuslines. install.sh and install.ps1 now check for a full set of hook files and wired hook entries before short-circuiting, wire a managed statusline path, and prefer not to overwrite user statusLine settings. Uninstall scripts now remove the managed statusline only when it was installed. caveman-activate.js updated to detect existing statusLine entries and emit a platform-appropriate snippet. Add tests (tests/test_hooks.py) and a local verification runner (tests/verify_repo.py) to validate install/uninstall/activation flows and caveman-compress fixtures. Also update README and caveman-compress docs and stats (token savings ~45%→~46%) and clarify auto-activation and statusline behavior.
Make several robustness and clarity fixes across scripts and docs:
- README: Clarify agent-specific behavior (Codex, Cursor/Windsurf) and note Codex uses $caveman and lacks some bundled plugins.
- caveman-compress: Avoid division-by-zero when computing token savings; skip unclosed markdown fences when extracting code blocks to prevent false positives.
- hooks (install/uninstall, PowerShell and shell): Pass settings and hooks paths via environment variables to avoid injection issues with special characters, quote generated command paths, use safer here-strings in PowerShell, and ensure settings.json is written via the resolved path. Also remove installer backup files during uninstall and add explanatory comments.
These changes improve security, correctness, and developer-facing documentation.
Add a new caveman-styled README (CLAUDE.md) documenting project overview, file ownership, CI sync workflow, hook system, skill system, agent distribution, evals, and benchmarks. Also add CLAUDE.original.md as the original, more formal copy for reference/backup.
Add .windsurf/skills/caveman SKILL.md and update the sync workflow to copy and commit the new file. Expand README install docs with agent-specific install instructions and standalone hook usage; update AGENTS.md and GEMINI.md to use the new caveman-compress path. Add Windows PowerShell installers (hooks/install.ps1 and hooks/uninstall.ps1) and enhance shell installers (hooks/install.sh, hooks/uninstall.sh) to support --force, plugin detection, clearer statusline wiring messages, and idempotent JSON merging/removal of hook entries. Provides uninstall guidance for other agents and improves overall install/uninstall robustness.
Add statusline support and installer/uninstaller hooks, improve compression tooling and docs. Key changes:
- Add caveman statusline badge script (hooks/caveman-statusline.sh) and wire it into install/uninstall (hooks/install.sh, hooks/uninstall.sh); installer now requires node, backs up settings.json, and makes the statusline executable.
- Enhance SessionStart hook (hooks/caveman-activate.js) to detect missing statusline config and emit a setup nudge; update hooks README with statusline usage and setup instructions.
- Add gemini-extension.json, AGENTS.md, and GEMINI.md to register skills and support Gemini CLI installation.
- Update README to mention statusline badge, Gemini CLI install, and agent list.
- Improve caveman-compress: rename skill (caveman-compress), clarify CLI path/usage in SKILL.md, return on validation failure without overwriting, bump benchmark encoding, and make compressor robust to LLM outer fences by stripping wrapping fences and expanding max_tokens; add explicit rule to avoid wrapping entire output in fences.
- Strengthen code-block extraction in validate.py to handle variable-length fences (```/~~~), nested fences, and CommonMark rules.
- Minor SKILL.md tweak: resume caveman mode when user asks to clarify or repeats question.
These changes integrate a visible status badge for Claude Code users, improve install/uninstall reliability, extend Gemini support, and make the compressor/validator more robust when interacting with LLM outputs.
Register SessionStart and UserPromptSubmit hooks in .claude-plugin/plugin.json to auto-load caveman rules and track active mode (writes to ~/.claude/.caveman-active). Update README and hooks/README.md to reflect automatic activation when installed as a plugin, remove the one-line install snippet, clarify the optional statusline badge, and adjust uninstall instructions (replace PostToolUse with UserPromptSubmit and note disabling the plugin deactivates hooks).
Switch caveman mode tracking from PostToolUse to UserPromptSubmit: update README to document the new hook, adjust caveman-mode-tracker.js to read the incoming `prompt` field (removing `user_prompt`), and modify install.sh to register the UserPromptSubmit hook with timeouts and status messages (and add a timeout/status for the activate hook). This ensures mode detection runs on every user prompt and prevents hook stalls by setting command timeouts and status text. Files changed: hooks/README.md, hooks/caveman-mode-tracker.js, hooks/install.sh.
Add a new caveman-mode-tracker.js hook to track active /caveman modes and write them to ~/.claude/.caveman-active (supports full/lite/ultra/wenyan/commit/review/compress and detects deactivation). Update caveman-activate.js to write 'full' to the flag file on SessionStart. Enhance hooks/install.sh to install both hooks and idempotently wire SessionStart and UserPromptSubmit hooks into ~/.claude/settings.json. Revise hooks/README.md and top-level README.md to document the two hooks, improved statusline badge snippet (shows [CAVEMAN] or [CAVEMAN:MODE]), and how the flag file bridges hooks and the statusline. Minor SKILL.md whitespace/newline cleanups.
Replace the long README hook section with a concise "Auto-Load Hook (Claude Code only)" install hint and link to new docs. Add hooks/README.md documenting the optional SessionStart hook, statusline badge, and quick install. Add hooks/install.sh: a one-command installer that copies or downloads caveman-activate.js into ~/.claude/hooks, idempotently wires a SessionStart entry into ~/.claude/settings.json (using node), and prints usage/uninstall notes. Restart Claude Code to activate the hook.
Rework README layout and copy: reorder navbar links, rename sections (Levels, 文言文), simplify intensity triggers, and tighten many examples/phrasing. Add caveman-compress docs and compression benchmarks (file-savings table), move/reinsert API benchmark table, and replace long "Why/How" prose with concise benefits and visuals. Misc fixes: Wenyan wording, CLAUDE.md compress examples, and various formatting cleanup for clarity and token-efficiency.
Expand README with new features and docs: add TOC links for Skills and Evals, update intro to mention Wenyan mode/terse commits/reviews and compression tool, and consolidate Windows Codex install/symlink notes into a short note. Add a new Wenyan (文言文) section with levels and example, introduce Caveman Skills (caveman-commit and caveman-review) with usage examples and severity prefixes, and add an Evals section describing the eval harness and commands. Minor wording/ordering tweaks to installation text.
Separate language translations are unnecessary — Claude already responds
in the user's language. These added maintenance surface without real value.
Wenyan mode is kept as it's a genuinely different compression technique
built into the core skill.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
