cavewoman — AI response optimizer CLI

Install

Prerequisite: Node.js for npm.

Option 1 — global (recommended)

zsh

$ npm install -g cavewoman

$ cavewoman

Follow on-screen prompts to configure.

Option 2 — run without installation

zsh

$ npx cavewoman

No global install required.

Common commands

Switch mode

Updates the mode for the last agent you configured. Modes: balanced, structured, ultra. Pass the mode in the command, or run cavewoman switch with no argument for an interactive picker.

cavewoman

$ cavewoman switch ultra

Configure another agent (change target)

Run cavewoman or npx cavewoman and use prompts to pick a different agent.

Supported coding agents:

Cursor (cursor)
Claude Code (claude-code)
ChatGPT (chatgpt)
Gemini CLI (gemini)
Codex CLI (codex)
Windsurf (windsurf)
Other (generic) — fallback when your tool is not listed

Check status

cavewoman

$ cavewoman status

Shows configured agent, target, scope, mode, and whether expected files exist.

Uninstall

cavewoman

$ cavewoman uninstall
$ cavewoman uninstall -t cursor
$ cavewoman uninstall -t chatgpt -s global

Without -t, uninstall uses the last installed target. Non-Cursor: -s is global or project. Cursor: removes global and project skill dirs when present.

How to use in each agent

Target	Outputs (typical)	Invoke
`cursor`	`SKILL.md` → `~/.agents/skills/cavewoman` or `./.agents/skills/cavewoman`	`/cavewoman` per chat
`claude-code`	`.claude-plugin/plugin.json`, `skills/cavewoman/SKILL.md` under `~/.cavewoman/claude-code-plugin` or `./.cavewoman/claude-code-plugin`	`claude --plugin-dir <plugin-root>` (or marketplace install of same tree)
`chatgpt`	`~/.cavewoman/chatgpt-sticky-prompt.txt` (+ clipboard on `install`)	Paste → Custom instructions / project rules / system prompt (persistent until replaced)
`gemini`	`~/.gemini/extensions/cavewoman/` (`gemini-extension.json`, `GEMINI.md`) or `./.gemini/extensions/cavewoman/`	Restart CLI; enable extension; `/extensions` or `gemini extensions list`
`codex`	`~/.cavewoman/codex-prefix.txt`, `~/.cavewoman/bin/cavewoman-codex`	`export PATH="$HOME/.cavewoman/bin:$PATH"`; `cavewoman-codex "<prompt>"` → prefixes, calls `codex -p`; or prepend file if calling `codex` yourself
`windsurf`	`~/.cavewoman/windsurf-prefix.txt`	Paste into Cascade persistent instructions
`generic`	`~/.cavewoman/generic-prefix.txt`	Manual prepend to prompts

Configuration

~/.cavewomanrc (JSON):

defaultTarget — default agent id
defaultMode — balanced | structured | ultra
lastInstalledTarget — switch refresh + default uninstall
lastScope — global (this machine) | project (this repo)
preferences.cursorSkillsDir — optional absolute Cursor skill root override

Environment: CAVEWOMAN_CURSOR_SKILLS_DIR overrides Cursor skills base directory.

Modes

balanced — concise, natural response with minimal fluff; good for readable answers
structured — organized sections; good for debugging
ultra — maximum compression; good for heavy daily use; saves tokens

Before vs after

Before

Sure! I’d be happy to help you with that. The issue you’re experiencing is likely caused by a subtle mismatch between…

After (cavewoman-guided)

Root cause: stale build artifact in dist/. Fix: delete dist, rerun npm run build, restart dev server. Verify: curl localhost:3000/health returns 200.

Extending agents

Add an injector under src/injectors/, export it from src/injectors/index.ts, and document the target in the README.

Development

zsh

$ npm install
$ npm run build
$ npx cavewoman