uncompact 0.44.0

package/README.md

@@ -0,0 +1,284 @@
+# Uncompact
+
+[![context bomb](https://raw.githubusercontent.com/supermodeltools/Uncompact/main/assets/badge.svg)](https://github.com/supermodeltools/Uncompact)
+
+> Stop Claude Code compaction from making your AI stupid.
+
+Uncompact hooks into Claude Code's lifecycle to reinject a high-density "context bomb" after compaction. It's powered by the [Supermodel Public API](https://supermodeltools.com) and stores versioned project graphs locally in SQLite.
+
+---
+
+## ⭐ Star the Supermodel Ecosystem
+
+If this is useful, please star our tools — it helps us grow:
+
+[![mcp](https://img.shields.io/github/stars/supermodeltools/mcp?style=social)](https://github.com/supermodeltools/mcp)  [![mcpbr](https://img.shields.io/github/stars/supermodeltools/mcpbr?style=social)](https://github.com/supermodeltools/mcpbr)  [![typescript-sdk](https://img.shields.io/github/stars/supermodeltools/typescript-sdk?style=social)](https://github.com/supermodeltools/typescript-sdk)  [![arch-docs](https://img.shields.io/github/stars/supermodeltools/arch-docs?style=social)](https://github.com/supermodeltools/arch-docs)  [![dead-code-hunter](https://img.shields.io/github/stars/supermodeltools/dead-code-hunter?style=social)](https://github.com/supermodeltools/dead-code-hunter)  [![Uncompact](https://img.shields.io/github/stars/supermodeltools/Uncompact?style=social)](https://github.com/supermodeltools/Uncompact)  [![narsil-mcp](https://img.shields.io/github/stars/supermodeltools/narsil-mcp?style=social)](https://github.com/supermodeltools/narsil-mcp)
+
+---
+
+## How It Works
+
+```text
+Claude Code compaction occurs
+         ↓
+Stop hook fires → uncompact run
+         ↓
+Check local SQLite cache (TTL: 15 min)
+         ↓ (cache miss or stale)
+Zip repo → POST /v1/graphs/supermodel
+         ↓
+Poll for result (async job)
+         ↓
+Render token-budgeted Markdown context bomb
+         ↓
+Claude Code receives context via stdout
+```
+
+## Claude Code Plugin
+
+The fastest way to integrate Uncompact is via the Claude Code plugin system — no manual hook installation required.
+
+### Install the plugin
+
+```bash
+/plugin marketplace add supermodeltools/Uncompact
+/plugin install uncompact@supermodeltools-Uncompact
+```
+
+This installs both hooks automatically:
+
+- **`SessionStart`** — runs `scripts/setup.sh` which auto-installs the `uncompact` binary via `go install` if not already present.
+- **`Stop`** — runs `scripts/uncompact-hook.sh` which reinjects context after every compaction event.
+
+> **Note:** After plugin installation, authenticate once with `uncompact auth login` to connect your Supermodel API key. That's it — no manual binary install or hook setup required.
+
+### CI / GitHub Actions
+
+In remote environments (`CLAUDE_CODE_REMOTE=true`), the hook automatically enables `--fallback` mode. Pass your API key via the `SUPERMODEL_API_KEY` environment variable:
+
+```yaml
+env:
+  SUPERMODEL_API_KEY: ${{ secrets.SUPERMODEL_API_KEY }}
+```
+
+---
+
+## Quick Start
+
+### 1. Install
+
+**Via npm (recommended):**
+
+```bash
+npm install -g uncompact
+```
+
+Or run without installing:
+
+```bash
+npx uncompact --help
+```
+
+**Via Go:**
+
+```bash
+go install github.com/supermodeltools/uncompact@latest
+```
+
+**Or download a binary** from [Releases](https://github.com/supermodeltools/Uncompact/releases).
+
+### 2. Authenticate
+
+```bash
+uncompact auth login
+```
+
+This opens [dashboard.supermodeltools.com](https://dashboard.supermodeltools.com) where you can subscribe and generate an API key.
+
+### 3. Install Claude Code Hooks
+
+```bash
+uncompact install
+```
+
+This auto-detects your Claude Code `settings.json`, shows a diff, and merges the hooks non-destructively.
+
+### 4. Verify
+
+```bash
+uncompact verify-install
+uncompact run --debug
+```
+
+## CLI Reference
+
+```text
+uncompact auth login             # Authenticate via dashboard.supermodeltools.com
+uncompact auth status            # Show auth status and API key validity
+uncompact auth logout            # Remove stored API key
+
+uncompact install                # Merge hooks into Claude Code settings.json (with diff preview)
+uncompact install --dry-run      # Preview changes without writing
+uncompact verify-install         # Check if hooks are correctly installed
+
+uncompact run                    # Emit context bomb to stdout (used by the hook)
+uncompact run --debug            # Show debug output on stderr
+uncompact run --force-refresh    # Bypass cache and fetch fresh from API
+uncompact run --max-tokens 1500  # Cap context bomb at 1500 tokens
+uncompact run --fallback         # Emit minimal static context on failure
+
+uncompact dry-run                # Preview context bomb without emitting it
+uncompact status                 # Show last injection, cache state, auth status
+uncompact logs                   # Show recent injection activity
+uncompact logs --tail 50         # Show last 50 entries
+uncompact stats                  # Token usage, cache hit rate, API call count
+
+uncompact cache clear            # Clear all cached graph data
+uncompact cache clear --project  # Clear only the current project's cache
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SUPERMODEL_API_KEY` | Supermodel API key (overrides config file) |
+
+### Config File
+
+Located at `~/.config/uncompact/config.json` (Linux/macOS) or `%APPDATA%\uncompact\config.json` (Windows).
+
+```json
+{
+  "api_key": "your-api-key-here",
+  "base_url": "https://api.supermodeltools.com",
+  "max_tokens": 2000
+}
+```
+
+### CLI Flags (Global)
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--api-key` | | Override API key |
+| `--max-tokens` | `2000` | Max tokens in context bomb |
+| `--force-refresh` | `false` | Bypass cache |
+| `--fallback` | `false` | Emit minimal static context on failure |
+| `--debug` | `false` | Debug output to stderr |
+
+## Manual Hook Installation
+
+If `uncompact install` doesn't work for your setup, add this to your Claude Code `settings.json`:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "uncompact run"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+See the [Claude Code hooks guide](https://code.claude.com/docs/en/hooks-guide#re-inject-context-after-compaction) for more details.
+
+## Architecture
+
+```text
+uncompact/
+├── main.go
+├── cmd/
+│   ├── root.go        # Root command, global flags
+│   ├── run.go         # Core hook command
+│   ├── auth.go        # auth login/status/logout
+│   ├── install.go     # install, verify-install
+│   └── status.go      # status, logs, stats, dry-run, cache
+└── internal/
+    ├── api/
+    │   └── client.go  # Supermodel API client (async 200/202 polling)
+    ├── cache/
+    │   └── store.go   # SQLite cache (TTL, staleness, injection log)
+    ├── config/
+    │   └── config.go  # Config loading (flag > env > file)
+    ├── hooks/
+    │   └── hooks.go   # settings.json installer (non-destructive)
+    ├── project/
+    │   └── project.go # Git-aware project detection
+    ├── template/
+    │   └── render.go  # Token-budgeted Markdown renderer
+    └── zip/
+        └── zip.go     # Repo zipper (excludes .git, node_modules, etc.)
+```
+
+### Caching Strategy
+
+| Concern | Policy |
+|---------|--------|
+| Default TTL | 15 minutes |
+| Stale cache | Served with `⚠️ STALE` warning; fresh fetch attempted |
+| API unavailable | Serve most recent cache entry silently |
+| No cache + API down | Silent exit 0 (never blocks Claude Code) |
+| Storage growth | Auto-prune entries older than 30 days |
+| Force refresh | `--force-refresh` flag |
+
+### Context Bomb Design
+
+The context bomb is capped at `--max-tokens` (default: 2,000) to avoid triggering the very compaction it's trying to prevent. Sections are rendered in priority order:
+
+1. **Required** (always included): Project overview, language, stats
+2. **Optional** (filled to token budget): Domain map, key files, dependencies
+
+### Fallback Chain
+
+```text
+1. Fresh cache hit → serve immediately
+2. Cache miss / stale → fetch from API → cache result
+3. API fails + stale cache exists → serve stale with warning
+4. API fails + no cache → silent exit 0 (or minimal static if --fallback)
+```
+
+## KPIs
+
+| Metric | Target |
+|--------|--------|
+| Clarifying questions per session (proxy for context loss) | ↓ after Uncompact |
+| Post-compaction task completion rate | ↑ after Uncompact |
+| Token efficiency (useful tokens / injected tokens) | > 80% |
+| 7-day retention | % of users who keep hooks enabled |
+
+## Building from Source
+
+```bash
+git clone https://github.com/supermodeltools/Uncompact
+cd Uncompact
+go mod tidy
+go build -o uncompact .
+```
+
+Requires Go 1.22+.
+
+## Add to your project
+
+Show that your project uses Uncompact by adding this badge to your README:
+
+```markdown
+[![context bomb](https://raw.githubusercontent.com/supermodeltools/Uncompact/main/assets/badge.svg)](https://github.com/supermodeltools/Uncompact)
+```
+
+Or with Shields.io:
+
+```markdown
+[![context bomb](https://img.shields.io/badge/context--bomb-Uncompact-5b21b6)](https://github.com/supermodeltools/Uncompact)
+```
+
+## License
+
+MIT

package/hooks/hooks.json

@@ -0,0 +1,80 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/setup.sh",
+            "timeout": 60
+          },
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/pregen-hook.sh",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/setup.sh",
+            "timeout": 60
+          },
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/pregen-hook.sh",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/uncompact-hook.sh",
+            "timeout": 120
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/pregen-hook.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/pregen-hook.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/show-hook.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/npm/install.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+
+const https = require("https");
+const fs = require("fs");
+const path = require("path");
+const { execSync, execFileSync } = require("child_process");
+const os = require("os");
+
+const REPO_OWNER = "supermodeltools";
+const REPO_NAME = "Uncompact";
+const BINARY_NAME = "uncompact";
+
+function getPackageVersion() {
+  const pkgPath = path.join(__dirname, "..", "package.json");
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  return pkg.version;
+}
+
+function getPlatform() {
+  const platform = os.platform();
+  if (platform === "darwin") return "darwin";
+  if (platform === "linux") return "linux";
+  if (platform === "win32") return "windows";
+  throw new Error(`Unsupported platform: ${platform}`);
+}
+
+function getArch() {
+  const arch = os.arch();
+  if (arch === "x64") return "amd64";
+  if (arch === "arm64") return "arm64";
+  throw new Error(`Unsupported architecture: ${arch}`);
+}
+
+function getBinaryName(platform) {
+  return platform === "windows" ? `${BINARY_NAME}.exe` : BINARY_NAME;
+}
+
+function getAssetName(platform, arch) {
+  const ext = platform === "windows" ? ".zip" : ".tar.gz";
+  return `${BINARY_NAME}_${platform}_${arch}${ext}`;
+}
+
+function httpsGet(url) {
+  return new Promise((resolve, reject) => {
+    const request = https.get(url, { headers: { "User-Agent": "uncompact-npm" } }, (response) => {
+      if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+        httpsGet(response.headers.location).then(resolve).catch(reject);
+        return;
+      }
+      if (response.statusCode !== 200) {
+        reject(new Error(`HTTP ${response.statusCode}: ${url}`));
+        return;
+      }
+      const chunks = [];
+      response.on("data", (chunk) => chunks.push(chunk));
+      response.on("end", () => resolve(Buffer.concat(chunks)));
+      response.on("error", reject);
+    });
+    request.setTimeout(20000, () => {
+      request.destroy();
+      reject(new Error(`Request timed out: ${url}`));
+    });
+    request.on("error", reject);
+  });
+}
+
+function httpsGetJson(url) {
+  return httpsGet(url).then((buffer) => JSON.parse(buffer.toString()));
+}
+
+async function getRelease(version) {
+  if (version && version !== "0.0.0") {
+    const tag = version.startsWith("v") ? version : `v${version}`;
+    const url = `https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/releases/tags/${tag}`;
+    return await httpsGetJson(url);
+  }
+  const url = `https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/releases/latest`;
+  return httpsGetJson(url);
+}
+
+function extractTarGz(buffer, destDir, binaryName) {
+  const tarPath = path.join(destDir, "archive.tar.gz");
+  fs.writeFileSync(tarPath, buffer);
+  execFileSync("tar", ["-xzf", tarPath, "-C", destDir], { stdio: "pipe" });
+  fs.unlinkSync(tarPath);
+  
+  const extracted = path.join(destDir, binaryName);
+  if (!fs.existsSync(extracted)) {
+    throw new Error(`Binary not found after extraction: ${extracted}`);
+  }
+  return extracted;
+}
+
+function extractZip(buffer, destDir, binaryName) {
+  const zipPath = path.join(destDir, "archive.zip");
+  fs.writeFileSync(zipPath, buffer);
+  
+  if (process.platform === "win32") {
+    execFileSync("powershell", ["-Command", `Expand-Archive -Path '${zipPath}' -DestinationPath '${destDir}' -Force`], { stdio: "pipe" });
+  } else {
+    execFileSync("unzip", ["-o", zipPath, "-d", destDir], { stdio: "pipe" });
+  }
+  fs.unlinkSync(zipPath);
+  
+  const extracted = path.join(destDir, binaryName);
+  if (!fs.existsSync(extracted)) {
+    throw new Error(`Binary not found after extraction: ${extracted}`);
+  }
+  return extracted;
+}
+
+async function main() {
+  const platform = getPlatform();
+  const arch = getArch();
+  const assetName = getAssetName(platform, arch);
+  const binaryName = getBinaryName(platform);
+  const binDir = path.join(__dirname, "bin");
+
+  console.log(`[uncompact] Installing ${BINARY_NAME} for ${platform}/${arch}...`);
+
+  if (!fs.existsSync(binDir)) {
+    fs.mkdirSync(binDir, { recursive: true });
+  }
+
+  const destPath = path.join(binDir, binaryName);
+
+  if (fs.existsSync(destPath)) {
+    console.log(`[uncompact] Binary already exists at ${destPath}`);
+    return;
+  }
+
+  const version = getPackageVersion();
+  let release;
+  try {
+    release = await getRelease(version);
+  } catch (err) {
+    console.error(`[uncompact] Failed to fetch release: ${err.message}`);
+    console.error(`[uncompact] You can install manually: go install github.com/${REPO_OWNER}/${REPO_NAME.toLowerCase()}@latest`);
+    process.exit(0);
+  }
+
+  const asset = release.assets.find((a) => a.name === assetName);
+  if (!asset) {
+    console.error(`[uncompact] No binary found for ${platform}/${arch} in release ${release.tag_name}`);
+    console.error(`[uncompact] Available assets: ${release.assets.map((a) => a.name).join(", ")}`);
+    console.error(`[uncompact] You can install manually: go install github.com/${REPO_OWNER}/${REPO_NAME.toLowerCase()}@latest`);
+    process.exit(0);
+  }
+
+  console.log(`[uncompact] Downloading ${asset.name}...`);
+
+  let buffer;
+  try {
+    buffer = await httpsGet(asset.browser_download_url);
+  } catch (err) {
+    console.error(`[uncompact] Failed to download: ${err.message}`);
+    process.exit(0);
+  }
+
+  console.log(`[uncompact] Extracting...`);
+
+  try {
+    if (platform === "windows") {
+      extractZip(buffer, binDir, binaryName);
+    } else {
+      extractTarGz(buffer, binDir, binaryName);
+    }
+  } catch (err) {
+    console.error(`[uncompact] Failed to extract: ${err.message}`);
+    process.exit(0);
+  }
+
+  if (platform !== "windows") {
+    fs.chmodSync(destPath, 0o755);
+  }
+
+  console.log(`[uncompact] Installed to ${destPath}`);
+}
+
+main().catch((err) => {
+  console.error(`[uncompact] Installation failed: ${err.message}`);
+  process.exit(0);
+});

package/npm/run.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+const { spawn } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+
+const BINARY_NAME = os.platform() === "win32" ? "uncompact.exe" : "uncompact";
+
+function findBinary() {
+  const localBin = path.join(__dirname, "bin", BINARY_NAME);
+  if (fs.existsSync(localBin)) {
+    return localBin;
+  }
+
+  const globalPaths = [
+    path.join(os.homedir(), "go", "bin", BINARY_NAME),
+    path.join(os.homedir(), ".local", "bin", BINARY_NAME),
+    "/usr/local/bin/" + BINARY_NAME,
+    "/opt/homebrew/bin/" + BINARY_NAME,
+  ];
+
+  for (const p of globalPaths) {
+    if (fs.existsSync(p)) {
+      return p;
+    }
+  }
+
+  return null;
+}
+
+function main() {
+  const binary = findBinary();
+
+  if (!binary) {
+    console.error("[uncompact] Binary not found. Try reinstalling:");
+    console.error("  npm install -g uncompact");
+    console.error("Or install via Go:");
+    console.error("  go install github.com/supermodeltools/uncompact@latest");
+    process.exit(1);
+  }
+
+  const args = process.argv.slice(2);
+  const child = spawn(binary, args, {
+    stdio: "inherit",
+    env: process.env,
+  });
+
+  child.on("error", (err) => {
+    console.error(`[uncompact] Failed to run binary: ${err.message}`);
+    process.exit(1);
+  });
+
+  child.on("close", (code, signal) => {
+    if (code === null && signal) {
+      process.kill(process.pid, signal);
+    } else {
+      process.exit(code ?? 0);
+    }
+  });
+}
+
+main();

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "uncompact",
+  "version": "0.44.0",
+  "description": "Stop Claude Code compaction from making your AI stupid. Re-inject project context after compaction via the Supermodel API.",
+  "author": "Supermodel <abe@supermodel.software>",
+  "license": "MIT",
+  "homepage": "https://github.com/supermodeltools/Uncompact",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/supermodeltools/Uncompact.git"
+  },
+  "bugs": {
+    "url": "https://github.com/supermodeltools/Uncompact/issues"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "cli",
+    "ai",
+    "context",
+    "compaction",
+    "supermodel"
+  ],
+  "bin": {
+    "uncompact": "npm/run.js"
+  },
+  "scripts": {
+    "postinstall": "node npm/install.js"
+  },
+  "files": [
+    "npm/",
+    "hooks/"
+  ],
+  "engines": {
+    "node": ">=16"
+  }
+}