seestack 0.0.0-stage → 1.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,22 @@
+{
+  "name": "seestack-mods",
+  "owner": {
+    "name": "See Stack",
+    "url": "https://github.com/see-stack"
+  },
+  "metadata": {
+    "description": "Official Claude Code mods by See Stack: interactive context bar, voice player, and developer tools."
+  },
+  "plugins": [
+    {
+      "name": "context-bar",
+      "source": "./mods/context-bar",
+      "description": "Interactive context window audit bar with expandable category drilldowns, token meters, and compaction headroom."
+    },
+    {
+      "name": "read-aloud",
+      "source": "./mods/read-aloud",
+      "description": "Speaks Claude Code replies aloud in a personal voice (Ember) with a live media player deck, progress scrubber, and speech queue."
+    }
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 See Stack (https://github.com/seestack-dev)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,165 @@
-# Temporary Holding Version
+# See Stack Mods for Claude Code ⚡
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-v2.1.287%2B-blueviolet?style=flat-square)](https://code.claude.com)
+[![License: MIT](https://img.shields.io/badge/License-MIT-emerald.svg?style=flat-square)](LICENSE)
+[![YouTube: See Stack](https://img.shields.io/badge/YouTube-See%20Stack-red?style=flat-square&logo=youtube)](https://youtube.com/@SeeStack)
+[![Website: seestack.dev](https://img.shields.io/badge/Web-seestack.dev-cyan?style=flat-square)](https://seestack.dev/mods)
+
+> 🔴 **Step 1: [Subscribe to @SeeStack on YouTube](https://youtube.com/@seestack?sub_confirmation=1) for new weekly Claude Code mods and AI agent tools!**
+
+Curated developer mods for [Claude Code](https://code.claude.com) by [See Stack](https://youtube.com/@SeeStack).
+
+Upgrade your terminal with live context window telemetry, compaction headroom alerts, and personal voice narration with media transport controls.
+
+---
+
+## ⚡ Quick Install (One Command)
+
+Add the **See Stack Marketplace** to your Claude Code installation:
+
+```bash
+claude plugin marketplace add see-stack/claude-code-mods
+```
+
+Then install any of the mods:
+
+```bash
+# 1. Interactive Context Bar with Headroom Tracking
+claude plugin install context-bar@seestack-mods
+
+# 2. Text-to-Speech Voice Player with Transport Scrubber & Queue
+claude plugin install read-aloud@seestack-mods
+```
+
+To update mods anytime:
+```bash
+claude plugin update context-bar@seestack-mods
+claude plugin update read-aloud@seestack-mods
+```
+
+---
+
+## 📋 Prerequisites & What You Need to Enable
+
+Before installing, make sure your environment meets these requirements:
+
+### 1. Claude Code Version (`v2.1.287` or higher)
+Native plugin and mod support was introduced in Claude Code `v2.1.287`. Check your version:
+```bash
+claude --version
+```
+If you are on an older build, upgrade to the latest version:
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+### 2. Verify Plugins Are Enabled
+Once installed, verify that Claude Code recognizes the mods:
+```bash
+claude plugin list
+```
+If a mod shows as disabled, enable it with:
+```bash
+claude plugin enable context-bar@seestack-mods
+claude plugin enable read-aloud@seestack-mods
+```
+
+### 3. Voice Synthesis (`read-aloud` mod only)
+* **macOS**: Works out of the box with macOS speech synthesis (`say` / `AVSpeechSynthesizer`). 
+* Supports personal voices (e.g. **Ember**, **Samantha**, **Daniel**). Configure your preferred voice in `System Settings > Accessibility > Spoken Content`.
+
+---
+
+## 🛠 Featured Mods
+
+### 1. `context-bar`
+A live stacked context window audit HUD placed directly above your prompt with an interactive collapsible accordion dropdown so you never burn 40,000 tokens on stale logs or get surprised by auto-compaction.
+
+![Context Bar Accordion Details View](assets/context-bar-dropdown.png)
+
+#### Key Features:
+* **Interactive Accordion Dropdown**: Click anywhere on the header to reveal the full itemized audit (`detail`), or hit `[ Minimize ]` to collapse back to a single compact line.
+* **Inline Drilldowns**: Click `▶` directly on `memory files` or `skills` to expand their itemized breakdown without repeating headers.
+* **Auto-Compaction Headroom**: Real-time tracking of safety headroom before auto-compaction triggers (e.g. `compacts at 167k [38%]`).
+* **Visual Token Meter**: Color-coded segments for system prompt, system tools, memory files, skills, messages, and free space.
+* **Slash Command**: Type `/context-bar` inside any Claude Code session to toggle visibility.
+
+```text
+┌──────────────────────────────────────────────────────────────┐
+│ ◆ context            75k of 200k · compacts at 167k  38% ▾   │
+│ █■■■███████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │
+│ detail                                                       │
+│ ▶ ■ system prompt    █·························   2k    1%   │
+│ ▶ ■ system tools     ██████████················  19k  9.5%   │
+│ ▶ ■ memory files     █························· 3.1k  1.5%   │
+│ ▶ ■ skills           █························· 2.6k  1.3%   │
+│ ▶ ■ messages         ██████████████████········  49k   24%   │
+│   ─ free space       ──────────────────────────  92k   46%   │
+│   ░ autocompact buf… ░░░░░░░░··················  33k   17%   │
+│                                                              │
+│ slash commands  42 of 42 · 1.4k                              │
+│ window  claude-sonnet-5-5 · compacts at 167k                 │
+│                                                              │
+│ [ Minimize ]                                                 │
+└──────────────────────────────────────────────────────────────┘
+```
+
+---
+
+### 2. `read-aloud`
+Brings a high-quality audio deck and Text-to-Speech into Claude Code with full media transport controls.
+
+![Read Aloud Demo](assets/read-aloud-demo.gif)
+
+#### Key Features:
+* **Media Deck**: Play/Pause, sentence scrubbing, reply queuing, and speed multiplier.
+* **Terracotta Progress Bar**: Visual scrub bar matching your context meter.
+* **Speech Queue**: Seamlessly queues replies without cutting off sentences mid-speech.
+* **Clean Formatting**: Automatically strips markdown headers, raw code blocks, and table noise before speaking so the voice remains natural and conversational.
+* **Slash Command**: Type `/read-aloud` or click the `read` button above your prompt.
+
+#### Keyboard Transport Controls:
+| Key | Action | Description |
+|:---:|:---|:---|
+| `p` | **Pause / Resume** | Instantly toggles speech playback |
+| `s` | **Stop** | Halts audio and clears speech buffer |
+| `◀` / `▶` | **Sentence Step** | Steps one sentence backward or forward |
+| `⏮` / `⏭` | **Reply Step** | Jumps across queued assistant replies |
+| `r` | **Speed Multiplier** | Cycles playback speed: `1×` ➔ `1.25×` ➔ `1.5×` ➔ `2×` |
+
+---
+
+## 🔧 Useful Commands Inside Claude Code
+
+| Slash Command / Key | What it does |
+|:---|:---|
+| `/context-bar` | Toggles the Context Bar HUD above prompt |
+| `/read-aloud` | Speaks the latest response out loud |
+| `/plugins` | Opens the interactive Claude Code plugin manager |
+| `/reload-plugins` | Hot-reloads all mods without restarting your terminal session |
+
+---
+
+## 💻 Local Development & Customization
+
+To inspect, tweak, or test these mods locally:
+
+```bash
+git clone https://github.com/see-stack/claude-code-mods.git
+cd claude-code-mods
+
+# Load mods in development mode:
+claude --plugin-dir ./mods/context-bar
+claude --plugin-dir ./mods/read-aloud
+```
+
+Reload changes instantly in your active session with `/reload-plugins`.
+
+---
+
+## 🌐 Ecosystem & Community
+
+* 📺 **YouTube**: [See Stack (@SeeStack)](https://youtube.com/@SeeStack) — In-depth AI agent architecture breakdowns and tutorials.
+* 🌐 **Documentation & Vaults**: [seestack.dev](https://seestack.dev)
+* 💬 Built for developers building real AI agent workflows.
+* 📄 Licensed under the [MIT License](LICENSE).

package/bin/cli.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+
+/**
+ * See Stack CLI for Claude Code Mods
+ * https://seestack.dev
+ */
+
+const { execSync, spawnSync } = require('child_process');
+const readline = require('readline');
+
+// ANSI formatting
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  magenta: '\x1b[35m',
+  red: '\x1b[31m',
+  gray: '\x1b[90m',
+};
+
+const BANNER = `
+${c.cyan}${c.bold}  ███████╗███████╗███████╗███████╗████████╗ █████╗  ██████╗██╗  ██╗
+  ██╔════╝██╔════╝██╔════╝██╔════╝╚══██╔══╝██╔══██╗██╔════╝██║ ██╔╝
+  ███████╗█████╗  █████╗  ███████╗   ██║   ███████║██║     █████╔╝ 
+  ╚════██║██╔══╝  ██╔══╝  ╚════██║   ██║   ██╔══██║██║     ██╔═██╗ 
+  ███████║███████╗███████╗███████║   ██║   ██║  ██║╚██████╗██║  ██╗
+  ╚══════╝╚══════╝╚══════╝╚══════╝   ╚═╝   ╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝${c.reset}
+  ${c.dim}Official Claude Code Mods & Telemetry • https://seestack.dev${c.reset}
+`;
+
+function checkClaudeInstalled() {
+  try {
+    const res = spawnSync('which', ['claude'], { encoding: 'utf8' });
+    if (res.status === 0 && res.stdout.trim()) {
+      return true;
+    }
+  } catch (e) {}
+  return false;
+}
+
+function run(cmd, desc) {
+  if (desc) {
+    process.stdout.write(`  ${c.cyan}▸${c.reset} ${desc}... `);
+  }
+  try {
+    execSync(cmd, { stdio: 'pipe' });
+    if (desc) console.log(`${c.green}✔ done${c.reset}`);
+    return true;
+  } catch (err) {
+    if (desc) console.log(`${c.red}✖ failed${c.reset}`);
+    return false;
+  }
+}
+
+function ensureMarketplace() {
+  console.log(`\n${c.bold}1. Connecting to See Stack Marketplace:${c.reset}`);
+  run('claude plugin marketplace add see-stack/claude-code-mods', 'Adding see-stack/claude-code-mods marketplace');
+}
+
+function installMods(mods = ['context-bar', 'read-aloud']) {
+  ensureMarketplace();
+  console.log(`\n${c.bold}2. Installing Mods:${c.reset}`);
+  for (const mod of mods) {
+    if (mod === 'context-bar') {
+      run('claude plugin install context-bar@seestack-mods', 'Installing context-bar (Live Context Telemetry)');
+    } else if (mod === 'read-aloud') {
+      run('claude plugin install read-aloud@seestack-mods', 'Installing read-aloud (Voice Narration Player)');
+    }
+  }
+  console.log(`\n${c.green}${c.bold}✨ All mods installed successfully!${c.reset}`);
+  console.log(`\n${c.dim}Start Claude Code to see your new mods in action:${c.reset}`);
+  console.log(`  ${c.bold}${c.cyan}claude${c.reset}\n`);
+}
+
+function updateMods() {
+  ensureMarketplace();
+  console.log(`\n${c.bold}Updating See Stack Mods:${c.reset}`);
+  run('claude plugin update context-bar@seestack-mods', 'Updating context-bar');
+  run('claude plugin update read-aloud@seestack-mods', 'Updating read-aloud');
+  console.log(`\n${c.green}${c.bold}✔ Updates complete!${c.reset}\n`);
+}
+
+function listMods() {
+  console.log(`\n${c.bold}Installed Claude Code Plugins:${c.reset}\n`);
+  try {
+    execSync('claude plugin list', { stdio: 'inherit' });
+  } catch (e) {
+    console.log(`${c.red}Could not retrieve plugin list.${c.reset}`);
+  }
+}
+
+function doctor() {
+  console.log(`\n${c.bold}See Stack Environment Doctor:${c.reset}\n`);
+  console.log(`  Node.js:  ${process.version}`);
+  const hasClaude = checkClaudeInstalled();
+  console.log(`  Claude:   ${hasClaude ? c.green + 'Installed' + c.reset : c.red + 'Not found' + c.reset}`);
+  if (hasClaude) {
+    try {
+      const v = execSync('claude --version', { encoding: 'utf8' }).trim();
+      console.log(`  Version:  ${v}`);
+    } catch (e) {}
+  }
+  console.log('');
+}
+
+async function main() {
+  console.log(BANNER);
+
+  if (!checkClaudeInstalled()) {
+    console.log(`${c.red}${c.bold}Error: Claude Code CLI not found.${c.reset}`);
+    console.log(`\nPlease install Claude Code first:`);
+    console.log(`  ${c.cyan}npm install -g @anthropic-ai/claude-code${c.reset}\n`);
+    process.exit(1);
+  }
+
+  const args = process.argv.slice(2);
+  const command = args[0] ? args[0].toLowerCase() : null;
+
+  if (command === 'update') {
+    updateMods();
+  } else if (command === 'list') {
+    listMods();
+  } else if (command === 'doctor') {
+    doctor();
+  } else if (command === 'help' || command === '--help' || command === '-h') {
+    console.log(`Usage:`);
+    console.log(`  npx seestack              ${c.dim}Interactive installation${c.reset}`);
+    console.log(`  npx seestack install      ${c.dim}Install all mods${c.reset}`);
+    console.log(`  npx seestack update       ${c.dim}Update all mods to latest${c.reset}`);
+    console.log(`  npx seestack list         ${c.dim}List installed plugins${c.reset}`);
+    console.log(`  npx seestack doctor       ${c.dim}Check environment status${c.reset}\n`);
+  } else {
+    // Default interactive / fast install
+    installMods(['context-bar', 'read-aloud']);
+  }
+}
+
+main();

package/mods/context-bar/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "context-bar",
+  "version": "0.2.0",
+  "description": "Your context window as a stacked bar above the prompt, a color per category, with token counts and the compaction point. Click the ▾ to open every row's share and what sits under the rows. /context-bar shows or hides it.",
+  "author": {
+    "name": "Hamza Zafar",
+    "url": "https://github.com/hamzafer"
+  },
+  "license": "MIT",
+  "types": "./types/index.d.ts"
+}

package/mods/context-bar/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.tsx"] }