cc-sidebar 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tyler Nishida
+
+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

@@ -0,0 +1,128 @@
+# cc-sidebar
+
+A visual sidebar for managing tasks alongside [Claude Code](https://claude.ai/code). Run it in a split pane next to your Claude Code session to queue tasks, track progress, and stay organized.
+
+```
++-------------------------------+------------------+
+|                               |   cc-sidebar     |
+|        Claude Code            |------------------|
+|                               | Claude           |
+|                               |   Fixing bug...  |
+|                               |                  |
+|                               | Queue            |
+|                               |   Add tests      |
+|                               |   Update docs    |
++-------------------------------+------------------+
+```
+
+## Features
+
+- **Task Queue**: Add tasks for Claude to work through
+- **Auto-completion detection**: Sidebar detects when Claude finishes a task
+- **Keyboard-driven**: Full keyboard navigation
+- **iTerm2 + tmux support**: Works with both (iTerm2 preferred)
+- **Persistent**: Data survives restarts
+
+## Installation
+
+Requires [Bun](https://bun.sh) runtime.
+
+```bash
+bun add -g cc-sidebar
+```
+
+## Quick Start
+
+### Option 1: iTerm2 (Recommended)
+
+1. Open iTerm2
+2. Start Claude Code: `claude`
+3. Run: `cc-sidebar spawn`
+
+A split pane opens on the right with the sidebar.
+
+### Option 2: tmux
+
+1. Start tmux: `tmux`
+2. Start Claude Code: `claude`
+3. Run: `cc-sidebar spawn --tmux`
+
+## Usage
+
+### Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `a` | Add new task |
+| `Enter` | Send task to Claude |
+| `e` | Edit selected task |
+| `d` | Delete selected task |
+| `j/k` or arrows | Navigate list |
+| `Tab` | Switch sections |
+| `q` or `Esc` | Quit sidebar |
+
+### How It Works
+
+1. **Add tasks** to the Queue using `a`
+2. **Send a task** to Claude by pressing `Enter`
+3. **Task moves to Active** while Claude works
+4. **Auto-completes** when Claude returns to prompt
+
+### Data Storage
+
+Data is stored in `~/.claude-sidebar/`:
+
+| File | Purpose |
+|------|---------|
+| `tasks.json` | Task queue |
+| `active.json` | Current active task |
+| `history.log` | Completed tasks |
+
+## Claude Integration
+
+For automatic task completion tracking, add this to your `~/.claude/CLAUDE.md`:
+
+```markdown
+## Sidebar Integration
+
+When completing work, check if this project uses the sidebar task queue.
+
+**Detection:**
+- Compute project hash: `sha256(cwd).slice(0, 12)`
+- Check if `~/.claude-sidebar/projects/<hash>/tasks.json` exists
+- If not, skip this section
+
+**On task completion:**
+1. Read the tasks.json file for this project
+2. Find any task that semantically matches what you just completed
+3. Move the matching task to done.json (Review section) for user confirmation:
+   - Remove from tasks.json array
+   - Add to done.json array with `completedAt` timestamp
+4. Write both files back
+
+Keep it simple - if no clear match, don't move anything. User can manually mark tasks done.
+
+**done.json format:**
+```json
+[{"id": "...", "content": "task content", "completedAt": "ISO timestamp"}]
+```
+```
+
+## Commands
+
+```bash
+cc-sidebar show       # Render in current terminal
+cc-sidebar spawn      # Launch in split pane (auto-detects iTerm2 vs tmux)
+cc-sidebar spawn --tmux  # Force tmux mode
+cc-sidebar env        # Show environment info
+```
+
+## Requirements
+
+- [Bun](https://bun.sh) >= 1.0.0
+- iTerm2 or tmux
+- macOS (iTerm2 support) or Linux (tmux)
+
+## License
+
+MIT

package/commands/sidebar.md

@@ -0,0 +1,62 @@
+---
+name: sidebar
+description: Open the Claude Code sidebar panel for task queue management
+---
+
+# Sidebar Command
+
+Spawn the Claude Sidebar in a tmux split pane.
+
+## Requirements
+
+**You must be running Claude Code inside a tmux session.** Check the TMUX environment variable - if it's empty, tell the user to:
+1. Start or attach to tmux: `tmux` or `tmux attach`
+2. Run Claude Code from inside tmux
+
+## Spawning the Sidebar
+
+Run this command to spawn the sidebar:
+
+```bash
+cd ${CLAUDE_PLUGIN_ROOT} && bun run src/cli.ts spawn
+```
+
+The sidebar will appear on the right side (50 chars wide) showing:
+- **Active**: Current task sent to Claude (auto-completes when Claude finishes)
+- **Queue**: User's task backlog
+
+## Keyboard Shortcuts (in sidebar)
+
+| Key | Action |
+|-----|--------|
+| Tab | Switch between Active and Queue sections |
+| ↑↓ or j/k | Navigate queue list |
+| 1-9 | Quick select queue item by number |
+| a | Add new task to queue |
+| e | Edit selected queue item |
+| d | Delete selected item (or clear active task) |
+| Enter | Send selected task to Claude |
+| Esc | Close sidebar |
+
+## How It Works
+
+1. Sidebar spawns in a tmux split pane (50 chars fixed width)
+2. User adds tasks to Queue via `a` key
+3. User presses Enter to send a task to Claude
+4. Task moves to Active section, text is injected into Claude's input
+5. Sidebar polls Claude's pane for completion (detects when Claude returns to prompt)
+6. When complete, task is logged to history and Active section clears
+
+## Checking Sidebar Status
+
+```bash
+cd ${CLAUDE_PLUGIN_ROOT} && bun run src/cli.ts env
+```
+
+## Closing the Sidebar
+
+User can press `Esc` in the sidebar, or close the tmux pane:
+
+```bash
+tmux kill-pane -t $(cat /tmp/claude-sidebar-pane-id)
+```

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "cc-sidebar",
+  "version": "0.1.0",
+  "description": "Visual sidebar for managing todos, tasks, and context alongside Claude Code",
+  "author": "Tyler Nishida",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tylernishida/cc-sidebar"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "sidebar",
+    "task-management",
+    "terminal",
+    "cli"
+  ],
+  "module": "src/cli.ts",
+  "type": "module",
+  "bin": {
+    "cc-sidebar": "src/cli.ts"
+  },
+  "files": [
+    "src",
+    "skills",
+    "commands"
+  ],
+  "scripts": {
+    "start": "bun run src/cli.ts",
+    "show": "bun run src/cli.ts show",
+    "spawn": "bun run src/cli.ts spawn"
+  },
+  "dependencies": {
+    "commander": "^14.0.2"
+  },
+  "peerDependencies": {
+    "bun": ">=1.0.0"
+  }
+}

package/skills/sidebar-awareness/SKILL.md

@@ -0,0 +1,69 @@
+# Claude Code Sidebar Integration
+
+You have access to a sidebar that the user uses to manage tasks for you. The sidebar runs in a tmux split pane alongside this conversation.
+
+## How It Works
+
+1. **User adds tasks** to the Queue in the sidebar
+2. **User sends a task** to you by pressing Enter on a queue item
+3. **Task moves to Active** section while you work on it
+4. **When you finish**, the sidebar auto-detects completion and clears the active task
+
+## Active Task
+
+When the user sends you a task, it appears as text input in your conversation AND is stored in:
+
+```bash
+cat ~/.claude-sidebar/active.json
+```
+
+Format:
+```json
+{
+  "id": "uuid",
+  "content": "Fix the authentication bug in login.ts",
+  "sentAt": "2024-01-15T10:35:00Z"
+}
+```
+
+**When you receive input that matches an active task, work on it.**
+
+## Task Queue
+
+The user's queue of upcoming tasks:
+
+```bash
+cat ~/.claude-sidebar/tasks.json
+```
+
+Format:
+```json
+[
+  {
+    "id": "uuid",
+    "content": "Add unit tests for user service",
+    "createdAt": "2024-01-15T10:30:00Z"
+  }
+]
+```
+
+## Completion Detection
+
+The sidebar monitors your output. When you return to the input prompt and stay idle for a few seconds, it automatically:
+1. Marks the active task as complete
+2. Logs it to `~/.claude-sidebar/history.log`
+3. Clears the Active section
+
+## Data Files Summary
+
+| File | What it is | Who writes |
+|------|-----------|------------|
+| `~/.claude-sidebar/tasks.json` | User's task queue | User (via sidebar) |
+| `~/.claude-sidebar/active.json` | Current task you're working on | Sidebar (when user sends) |
+| `~/.claude-sidebar/history.log` | Completed tasks log | Sidebar (on completion) |
+
+## Best Practices
+
+1. **Focus on the task** - when you receive input matching an active task, work on it
+2. **Complete thoroughly** - the sidebar waits for you to finish before clearing
+3. **Don't check queue** - the user controls when to send you the next task

package/src/cli.ts

@@ -0,0 +1,166 @@
+#!/usr/bin/env bun
+/**
+ * Claude Sidebar CLI
+ *
+ * Commands:
+ *   show   - Render sidebar in current terminal
+ *   spawn  - Launch sidebar in tmux split pane
+ *   update - Send data to running sidebar via IPC
+ *   env    - Show environment info (tmux status, etc.)
+ */
+
+import { program } from "commander";
+import { isInTmux, getEnvInfo, spawnSidebarPane } from "./terminal/tmux";
+import { isInITerm, spawnITermSidebarPane, getITermEnvInfo } from "./terminal/iterm";
+import { createIPCServer } from "./ipc/server";
+import { sendMessage } from "./ipc/client";
+import { getSocketPath, ensureDir } from "./persistence/store";
+import { dirname } from "path";
+import { RawSidebar } from "./components/RawSidebar";
+
+// Terminal title disabled - could cause flicker
+// process.stdout.write("\x1b]0;claude-sidebar\x07");
+
+program
+  .name("cc-sidebar")
+  .description("Visual sidebar for Claude Code")
+  .version("0.1.0");
+
+// Show command - render sidebar in current terminal
+program
+  .command("show")
+  .description("Render sidebar in current terminal")
+  .option("-s, --socket <path>", "Unix socket path for IPC")
+  .action(async (options) => {
+    ensureDir();
+    const socketPath = options.socket || getSocketPath();
+
+    // Start IPC server for receiving updates
+    const server = createIPCServer({
+      socketPath,
+      onMessage: (_message) => {
+        // IPC messages can be handled here if needed
+      },
+      onError: (error) => {
+        console.error("IPC error:", error.message);
+      },
+    });
+
+    // Use raw terminal rendering (bypasses Ink completely for flicker-free input)
+    const sidebar = new RawSidebar(() => {
+      server.close();
+    });
+
+    sidebar.start();
+
+    // Handle Ctrl+C and termination signals for clean exit
+    const cleanup = () => {
+      sidebar.stop();
+      server.close();
+      process.exit(0);
+    };
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+
+    // Keep process running
+    await new Promise(() => {});
+  });
+
+// Spawn command - launch sidebar in split pane (iTerm2 or tmux)
+program
+  .command("spawn")
+  .description("Launch sidebar in split pane (iTerm2 preferred, tmux fallback)")
+  .option("--tmux", "Force tmux mode even in iTerm2")
+  .action(async (options) => {
+    // Get the path to this script and current working directory
+    const scriptPath = process.argv[1];
+    const cwd = process.cwd();
+    // Include cd to ensure sidebar runs in the same directory (for per-project tasks)
+    const command = `cd "${cwd}" && bun ${scriptPath} show`;
+
+    // Prefer iTerm2 if available (avoids scrollback corruption)
+    if (isInITerm() && !options.tmux) {
+      console.log("Using iTerm2 split (preserves scrollback)...");
+      const sessionId = await spawnITermSidebarPane(command);
+      if (sessionId) {
+        console.log(`Sidebar spawned in iTerm2 session: ${sessionId}`);
+      } else {
+        console.error("Failed to spawn iTerm2 sidebar");
+        process.exit(1);
+      }
+      return;
+    }
+
+    // Fall back to tmux
+    if (!isInTmux()) {
+      console.error("Error: Not running in tmux or iTerm2.");
+      console.error("Options:");
+      console.error("  - Run inside iTerm2 (recommended)");
+      console.error("  - Start a tmux session: tmux");
+      process.exit(1);
+    }
+
+    console.log("Using tmux split (may affect scrollback)...");
+    const paneId = await spawnSidebarPane(command);
+    if (paneId) {
+      console.log(`Sidebar spawned in tmux pane: ${paneId}`);
+    }
+  });
+
+// Update command - send data to running sidebar
+program
+  .command("update")
+  .description("Send data to running sidebar via IPC")
+  .option("-s, --socket <path>", "Unix socket path")
+  .option("-t, --type <type>", "Message type", "update")
+  .option("-d, --data <json>", "Message data (JSON)")
+  .action(async (options) => {
+    const socketPath = options.socket || getSocketPath();
+
+    let data: unknown;
+    if (options.data) {
+      try {
+        data = JSON.parse(options.data);
+      } catch {
+        console.error("Invalid JSON data");
+        process.exit(1);
+      }
+    }
+
+    try {
+      await sendMessage(socketPath, {
+        type: options.type,
+        data,
+      });
+      console.log("Message sent");
+    } catch (err) {
+      console.error("Failed to send message:", err instanceof Error ? err.message : err);
+      process.exit(1);
+    }
+  });
+
+// Env command - show environment info
+program
+  .command("env")
+  .description("Show environment info")
+  .action(() => {
+    const tmuxInfo = getEnvInfo();
+    const itermInfo = getITermEnvInfo();
+    console.log("Environment:");
+    console.log(`  In iTerm2: ${itermInfo.inITerm ? "Yes" : "No"}`);
+    console.log(`  In tmux: ${tmuxInfo.inTmux ? "Yes" : "No"}`);
+    console.log(`  TERM_PROGRAM: ${itermInfo.termProgram}`);
+    console.log(`  TERM: ${tmuxInfo.term}`);
+    console.log(`  SHELL: ${tmuxInfo.shell}`);
+    console.log(`  Socket: ${getSocketPath()}`);
+    if (tmuxInfo.inTmux) {
+      console.log(`  Stored tmux pane: ${tmuxInfo.storedPaneId || "none"}`);
+    }
+  });
+
+// Default to show if no command given
+if (process.argv.length === 2) {
+  process.argv.push("show");
+}
+
+program.parse();