Add headroom as an optional installer group (#7)

headroom (headroomlabs-ai/headroom) is a standalone Python CLI, not a
Claude Code plugin, so it can't go through marketplaceSetup. Adds a
toolSetup field for external CLI tools: when uv is on PATH the installer
offers to run `uv tool install --python 3.13 "headroom-ai[all]"`
(defaults to No since it installs machine-wide), and prints the command
otherwise. `headroom wrap claude` is shown as the next step only after a
successful install.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: arnabdeypolimi

CLAUDE.md

@@ -101,6 +101,13 @@ claude plugin install academic-research-skills@academic-research-skills
 claude plugin install ponytail@ponytail
 ```
 
+Optional external CLI — [headroom](https://github.com/headroomlabs-ai/headroom) context compression (not a plugin; installs machine-wide):
+
+```bash
+uv tool install --python 3.13 "headroom-ai[all]"
+headroom wrap claude
+```
+
 Marketing skills can also be installed via the `npx skills` CLI (installs to `.agents/skills/` and symlinks into `.claude/skills/`):
 
 ```bash

README.md

@@ -175,6 +175,9 @@ Source: [pbakaus/impeccable](https://github.com/pbakaus/impeccable). Useful when
 | Caveman Mode | — | **caveman** |
 | Agent Skills | — | **agent-skills** |
 | Ponytail (Lazy Dev) | — | **ponytail** |
+| Headroom (Context Compression) | — | — (optional CLI install) |
+
+Headroom ([headroomlabs-ai/headroom](https://github.com/headroomlabs-ai/headroom)) is a standalone CLI, not a plugin. If `uv` is on your PATH, the installer offers to run `uv tool install --python 3.13 "headroom-ai[all]"` for you (defaults to No; installs machine-wide); otherwise it prints the command. Afterwards, run `headroom wrap claude` (undo with `headroom unwrap claude`).
 
 ## Repo layout
 

create-claude-setup/bin/cli.js

@@ -8,6 +8,7 @@ import { GROUPS } from '../src/catalog.js';
 import { install, readManifest } from '../src/installer.js';
 import { update } from '../src/updater.js';
 import { claudeAvailable, installAllPlugins } from '../src/plugin-installer.js';
+import { commandAvailable, formatCommand, runCommand } from '../src/tool-installer.js';
 
 // Node version check
 const [major] = process.versions.node.split('.').map(Number);
@@ -218,6 +219,29 @@ async function main() {
     }
   }
 
+  // ── External tools ────────────────────────────────────────────────────────
+  for (const tool of plan.toolSetup) {
+    const installCmd = formatCommand(tool.install);
+    let installed = false;
+
+    if (commandAvailable(tool.requires)) {
+      const choice = await confirm({
+        message: `Install ${tool.name} now? (${pc.dim(installCmd)} — installs machine-wide)`,
+        initialValue: false,
+      });
+      if (!isCancel(choice) && choice) {
+        installed = runCommand(tool.install);
+        if (!installed) console.log(pc.red(`  ${tool.name} install failed.`));
+      }
+    } else {
+      console.log(pc.dim(`  \`${tool.requires}\` not found — install ${tool.name} manually:`));
+    }
+
+    if (installed) console.log(pc.dim(`  Then run: `) + pc.yellow(tool.next));
+    else console.log(pc.yellow(`  ${installCmd}`));
+    console.log('');
+  }
+
   // Skill summary
   console.log(pc.dim(`  Installed ${plan.skills.length} skill(s) across ${finalGroups.length} group(s)`));
   if (plan.copyAgents) console.log(pc.dim('  Copied agents and workflows'));

create-claude-setup/src/catalog.js

@@ -237,6 +237,27 @@ export const GROUPS = [
     copyAgents: false,
     copyTemplates: false,
   },
+  {
+    id: 'headroom',
+    label: 'Headroom (Context Compression)',
+    hint: 'CLI proxy that compresses tool outputs before they reach the LLM',
+    required: false,
+    skills: [],
+    plugins: [],
+    marketplaceSetup: [],
+    // External CLI tools. The installer offers to run `install` (machine-wide) if `requires`
+    // is on PATH; `next` is printed after a successful install for the user to run themselves.
+    toolSetup: [
+      {
+        name: 'headroom',
+        requires: 'uv',
+        install: ['uv', 'tool', 'install', '--python', '3.13', 'headroom-ai[all]'],
+        next: 'headroom wrap claude',
+      },
+    ],
+    copyAgents: false,
+    copyTemplates: false,
+  },
 ];
 
 export function getGroupById(id) {
@@ -247,6 +268,7 @@ export function resolveInstallPlan(selectedGroupIds) {
   const skills = new Set();
   const plugins = new Set();
   const marketplaceSetup = [];
+  const toolSetup = [];
   let copyAgents = false;
   let copyTemplates = false;
 
@@ -262,6 +284,7 @@ export function resolveInstallPlan(selectedGroupIds) {
         plugins.add(`${m.pluginName}@${m.marketplaceFlag}`);
       }
     });
+    toolSetup.push(...(group.toolSetup ?? []));
     if (group.copyAgents) copyAgents = true;
     if (group.copyTemplates) copyTemplates = true;
   }
@@ -270,6 +293,7 @@ export function resolveInstallPlan(selectedGroupIds) {
     skills: [...skills],
     plugins: [...plugins],
     marketplaceSetup,
+    toolSetup,
     copyAgents,
     copyTemplates,
   };

create-claude-setup/src/tool-installer.js

@@ -0,0 +1,32 @@
+import { execFileSync } from 'node:child_process';
+
+/**
+ * Check whether an executable is available in PATH.
+ */
+export function commandAvailable(name) {
+  try {
+    execFileSync(name, ['--version'], { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Render an argv array as a copy-pasteable shell command.
+ */
+export function formatCommand(argv) {
+  return argv.map(a => (/[^\w@%+=:,./-]/.test(a) ? `"${a}"` : a)).join(' ');
+}
+
+/**
+ * Run an argv array with output streamed to the terminal. Returns true on success.
+ */
+export function runCommand([cmd, ...args]) {
+  try {
+    execFileSync(cmd, args, { stdio: 'inherit' });
+    return true;
+  } catch {
+    return false;
+  }
+}