ccdock 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cchub contributors
+
+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,195 @@
+# ccdock
+
+A TUI sidebar to orchestrate VS Code windows and track Claude Code agents.
+
+## Why?
+
+Running multiple Claude Code agents across git worktrees is powerful — but managing the VS Code windows that go with them is a nightmare. You end up Alt-Tabbing through a dozen windows, losing track of which agent is doing what, and manually arranging editors every time you switch context.
+
+Existing "hub" tools either force you into a CLI-only workflow or require a proprietary editor. But you already have VS Code. You just need something to **keep it organized**.
+
+ccdock sits in a narrow terminal sidebar and takes care of the rest: auto-positioning VS Code windows, tracking every Claude Code agent in real time, and letting you switch between sessions with a single click.
+
+## Features
+
+- **VS Code orchestration** — Auto-open, position, and switch VS Code (or Cursor) windows next to the sidebar. Click a session, and the right editor snaps into focus.
+- **Real-time agent monitoring** — See exactly what each Claude Code agent is doing: which tool it's calling, what file it's reading, what command it's running.
+- **Git worktree management** — Create, switch, and delete worktrees via [git-wt](https://github.com/k1LoW/git-wt) integration. Each worktree gets its own session.
+- **Activity log** — Live feed of tool invocations with session numbers (#N) across all active agents.
+- **Mouse + keyboard** — Click to select sessions, scroll wheel to navigate, or use vim-style `j`/`k` keys.
+- **Auto-layout** — VS Code windows automatically resize and reposition when the terminal resizes.
+
+## Requirements
+
+- **macOS** (uses AppleScript for window management)
+- [Bun](https://bun.sh/) runtime (v1.0+)
+- [VS Code](https://code.visualstudio.com/) or [Cursor](https://cursor.sh/)
+- [git-wt](https://github.com/k1LoW/git-wt) for worktree creation (`go install github.com/k1LoW/git-wt@latest`)
+- [Ghostty](https://ghostty.org/) terminal (used for sidebar window detection)
+- A terminal font with [Nerd Font](https://www.nerdfonts.com/) support (for icons)
+
+## Install
+
+```sh
+# ccdock itself
+bun install -g ccdock
+
+# git-wt (required for worktree creation)
+go install github.com/k1LoW/git-wt@latest
+```
+
+## Setup
+
+### 1. Configure workspace directories
+
+Edit `~/.config/ccdock/config.json` (auto-created on first run):
+
+```json
+{
+  "workspace_dirs": ["~/workspace"],
+  "editor": "code"
+}
+```
+
+| Key              | Description                                               |
+| ---------------- | --------------------------------------------------------- |
+| `workspace_dirs` | Directories to scan for git repositories                  |
+| `editor`         | Editor command: `"code"` for VS Code, `"cursor"` for Cursor |
+
+### 2. Set up Claude Code hooks
+
+Add to `~/.claude/settings.json` to enable agent status monitoring:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{ "matcher": "", "hooks": [{ "type": "command", "command": "ccdock hook claude-code PreToolUse" }] }],
+    "PostToolUse": [{ "matcher": "", "hooks": [{ "type": "command", "command": "ccdock hook claude-code PostToolUse" }] }],
+    "PermissionRequest": [{ "matcher": "", "hooks": [{ "type": "command", "command": "ccdock hook claude-code PermissionRequest" }] }],
+    "Stop": [{ "matcher": "", "hooks": [{ "type": "command", "command": "ccdock hook claude-code Stop" }] }],
+    "Notification": [{ "matcher": "", "hooks": [{ "type": "command", "command": "ccdock hook claude-code Notification" }] }],
+    "SessionEnd": [{ "matcher": "", "hooks": [{ "type": "command", "command": "ccdock hook claude-code SessionEnd" }] }]
+  }
+}
+```
+
+## Usage
+
+```sh
+ccdock          # start the sidebar TUI
+ccdock help     # show help
+```
+
+### Keybindings
+
+| Key          | Action                                  |
+| ------------ | --------------------------------------- |
+| `j` / `k`   | Navigate between sessions               |
+| `Enter`      | Focus editor window for selected session |
+| `Tab`        | Focus editor window (same as Enter)     |
+| `n`          | Create new session (interactive wizard) |
+| `d`          | Delete session                          |
+| `r`          | Realign all VS Code windows             |
+| `c`          | Toggle compact mode                     |
+| `l`          | Toggle activity log                     |
+| `q` / Ctrl+C | Quit (with option to close editors)    |
+| Mouse click  | Select session                          |
+| Scroll wheel | Navigate between sessions               |
+
+### Session card states
+
+| Card appearance | Meaning |
+| --------------- | ------- |
+| White border + green `●` | Editor is focused |
+| Normal border + green `●` | Editor is open but not focused |
+| Spinning `⠋` indicator | Editor is launching |
+| Dim border, no dot | Editor is closed |
+
+### Agent status
+
+| Icon | Status | Description |
+| ---- | ------ | ----------- |
+| `●` green | running | Agent is executing tools |
+| `●`/`○` yellow pulse | waiting | Awaiting user permission |
+| `○` teal | idle | Agent is ready |
+
+## How it works
+
+### Architecture
+
+```
+Claude Code hooks --> ccdock hook --> writes agent JSON files
+                                          |
+ccdock sidebar (polls every 2s) <----------+
+       |
+       +--> reads session + agent state files
+       +--> queries VS Code windows via AppleScript
+       +--> renders TUI with merged state
+```
+
+- **State** — `~/.local/state/ccdock/` stores session and agent state as JSON files
+- **Hooks** — `ccdock hook` writes agent state files when Claude Code fires events
+- **Window management** — AppleScript via `osascript` to position VS Code next to the sidebar
+- **Wizard** — `n` key scans workspace dirs, offers create/existing/root worktree options via `git wt`
+
+### File structure
+
+```
+src/
+  main.ts              — CLI entry point
+  sidebar.ts           — Main event loop, input handling
+  types.ts             — Type definitions
+  config/config.ts     — Config (~/.config/ccdock/)
+  workspace/state.ts   — Session/agent state persistence
+  workspace/editor.ts  — VS Code open/focus
+  workspace/window.ts  — AppleScript window management
+  worktree/manager.ts  — Git worktree operations
+  worktree/scanner.ts  — Repository discovery
+  tui/render.ts        — Sidebar rendering
+  tui/wizard.ts        — Session wizard rendering
+  tui/input.ts         — Keyboard input parsing
+  tui/ansi.ts          — ANSI escape codes
+  agent/hook.ts        — Hook handler
+```
+
+## Development
+
+```sh
+# Clone
+git clone https://github.com/shibutani/ccdock.git
+cd ccdock
+bun install
+
+# Run directly
+bun run dev
+
+# Type check
+bun run typecheck
+
+# Format
+bun run format
+
+# Build standalone binary (optional)
+bun run build
+```
+
+### Project structure
+
+The project uses [Bun](https://bun.sh/) as runtime and [Biome](https://biomejs.dev/) for formatting.
+
+- `src/main.ts` — CLI entry point, routes `start` / `hook` / `help` commands
+- `src/sidebar.ts` — Main event loop: keyboard input, timers, state refresh
+- `src/tui/` — Terminal UI rendering (cards, wizard, input parsing, ANSI codes)
+- `src/workspace/` — File-based state, AppleScript window management, editor control
+- `src/worktree/` — Git worktree operations and repository scanning
+- `src/agent/` — Claude Code hook handler
+
+### Publishing
+
+```sh
+npm publish
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "ccdock",
+  "version": "0.1.0",
+  "description": "A TUI sidebar to orchestrate VS Code windows and track Claude Code agents.",
+  "type": "module",
+  "bin": {
+    "ccdock": "src/main.ts"
+  },
+  "scripts": {
+    "dev": "bun run src/main.ts",
+    "build": "bun build --compile src/main.ts --outfile ccdock",
+    "typecheck": "bunx tsc --noEmit",
+    "format": "bunx @biomejs/biome format --write src/"
+  },
+  "keywords": [
+    "claude-code",
+    "worktree",
+    "git",
+    "tui",
+    "sidebar",
+    "vscode",
+    "terminal"
+  ],
+  "author": "shibutani",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shibukazu/ccdock"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "os": [
+    "darwin"
+  ],
+  "files": [
+    "src/**/*.ts",
+    "LICENSE",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@biomejs/biome": "^1.9.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/src/agent/hook.ts

@@ -0,0 +1,134 @@
+import type { AgentState, AgentType } from "../types.ts";
+import {
+	findSessionByPath,
+	readAgentState,
+	removeAgentFile,
+	writeAgentState,
+} from "../workspace/state.ts";
+
+function sanitize(path: string): string {
+	return path.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 100);
+}
+
+function extractToolDetail(toolName: string, toolInput: Record<string, unknown>): string {
+	switch (toolName) {
+		case "Bash":
+			return (toolInput.command as string) ?? "";
+		case "Read":
+		case "Write":
+			return shortenPath((toolInput.file_path as string) ?? "");
+		case "Edit":
+			return shortenPath((toolInput.file_path as string) ?? "");
+		case "Grep":
+			return `/${(toolInput.pattern as string) ?? ""}/`;
+		case "Glob":
+			return (toolInput.pattern as string) ?? "";
+		case "Agent":
+		case "Task":
+			return (toolInput.description as string) ?? (toolInput.prompt as string)?.slice(0, 80) ?? "";
+		case "WebSearch":
+			return (toolInput.query as string) ?? "";
+		case "WebFetch":
+			return (toolInput.url as string) ?? "";
+		default:
+			return "";
+	}
+}
+
+function shortenPath(path: string): string {
+	const home = process.env.HOME ?? "";
+	if (home && path.startsWith(home)) {
+		return `~${path.slice(home.length)}`;
+	}
+	return path;
+}
+
+function buildPrompt(eventName: string, payload: Record<string, unknown>): string {
+	if (eventName === "PreToolUse" || eventName === "PostToolUse") {
+		const toolName = (payload.tool_name as string) ?? "";
+		return `[${eventName}] ${toolName}`;
+	}
+	if (eventName === "Stop") {
+		const reason = (payload.stop_reason as string) ?? "completed";
+		return `[Stop] ${reason}`;
+	}
+	return `[${eventName}]`;
+}
+
+const STATUS_MAP: Record<string, string> = {
+	PreToolUse: "running",
+	PostToolUse: "running",
+	SubagentToolUse: "running",
+	PermissionRequest: "waiting",
+	Stop: "idle",
+	SessionEnd: "remove",
+};
+
+export async function handleHook(agentType: string, eventName: string): Promise<void> {
+	let payload: Record<string, unknown> = {};
+	try {
+		const input = await Bun.stdin.text();
+		if (input.trim()) {
+			payload = JSON.parse(input) as Record<string, unknown>;
+		}
+	} catch {
+		// No stdin or invalid JSON - continue with empty payload
+	}
+
+	const cwd = (payload.cwd as string) ?? process.cwd();
+	const claudeSessionId = payload.session_id as string | undefined;
+
+	if (!claudeSessionId) {
+		return;
+	}
+
+	const filename = `${sanitize(cwd)}-${claudeSessionId}.json`;
+
+	const mappedStatus = STATUS_MAP[eventName];
+
+	if (mappedStatus === "remove") {
+		removeAgentFile(filename);
+		return;
+	}
+
+	// Notification doesn't carry meaningful status info — preserve previous state
+	if (eventName === "Notification") {
+		const prev = readAgentState(filename);
+		if (prev) {
+			prev.updatedAt = Date.now();
+			writeAgentState(prev, filename);
+		}
+		return;
+	}
+
+	const status = mappedStatus ?? "unknown";
+	const sessionId = findSessionByPath(cwd);
+	const rawToolName = (payload.tool_name as string) ?? "";
+	const toolInput = (payload.tool_input as Record<string, unknown>) ?? {};
+	const rawToolDetail = extractToolDetail(rawToolName, toolInput);
+
+	// Preserve previous toolName/toolDetail only for events that don't carry tool info
+	// but clear them on Stop (idle) since the agent is no longer doing anything
+	let toolName = rawToolName;
+	let toolDetail = rawToolDetail;
+	if (!toolName && status !== "idle") {
+		const prev = readAgentState(filename);
+		if (prev) {
+			toolName = prev.toolName ?? "";
+			toolDetail = prev.toolDetail ?? "";
+		}
+	}
+
+	const state: AgentState = {
+		sessionId,
+		agentType: agentType as AgentType,
+		status: status as AgentState["status"],
+		prompt: buildPrompt(eventName, payload),
+		toolName,
+		toolDetail,
+		cwd,
+		updatedAt: Date.now(),
+	};
+
+	writeAgentState(state, filename);
+}

package/src/config/config.ts

@@ -0,0 +1,58 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { HubConfig } from "../types.ts";
+
+const CONFIG_DIR_NAME = "ccdock";
+
+function getConfigDir(): string {
+	const home = process.env.HOME ?? "";
+	const configBase = process.env.XDG_CONFIG_HOME ?? join(home, ".config");
+	return join(configBase, CONFIG_DIR_NAME);
+}
+
+function getConfigPath(): string {
+	return join(getConfigDir(), "config.json");
+}
+
+function expandTilde(p: string): string {
+	const home = process.env.HOME ?? "";
+	if (p.startsWith("~/")) {
+		return join(home, p.slice(2));
+	}
+	return p;
+}
+
+const DEFAULT_CONFIG: HubConfig = {
+	workspace_dirs: ["~/workspace"],
+	editor: "code",
+};
+
+export function loadConfig(): HubConfig {
+	const configDir = getConfigDir();
+	const configPath = getConfigPath();
+
+	// Auto-create config directory and file on first run
+	if (!existsSync(configDir)) {
+		mkdirSync(configDir, { recursive: true });
+	}
+
+	if (!existsSync(configPath)) {
+		writeFileSync(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2));
+		return resolveConfig(DEFAULT_CONFIG);
+	}
+
+	try {
+		const raw = readFileSync(configPath, "utf-8");
+		const parsed = JSON.parse(raw) as HubConfig;
+		return resolveConfig(parsed);
+	} catch {
+		return resolveConfig(DEFAULT_CONFIG);
+	}
+}
+
+function resolveConfig(config: HubConfig): HubConfig {
+	return {
+		workspace_dirs: config.workspace_dirs.map(expandTilde).filter((dir) => existsSync(dir)),
+		editor: config.editor ?? "code",
+	};
+}

package/src/main.ts

@@ -0,0 +1,65 @@
+#!/usr/bin/env bun
+import { handleHook } from "./agent/hook.ts";
+import { runSidebar } from "./sidebar.ts";
+
+function printHelp(): void {
+	const help = `
+ccdock - TUI sidebar for managing git worktree development sessions
+
+USAGE:
+  ccdock [command]
+
+COMMANDS:
+  start       Start the sidebar TUI (default)
+  hook        Handle agent hook events (called by Claude Code hooks)
+  help        Show this help message
+
+HOOK USAGE:
+  ccdock hook <agent-type> <event-name>
+
+  Agent types: claude-code, codex
+  Events: PreToolUse, PostToolUse, Stop, session.end, Notification
+
+KEYBINDINGS (sidebar):
+  j/k         Navigate sessions
+  Enter/Tab   Focus editor window for selected session
+  n           Create new session (wizard)
+  d           Delete session
+  c           Toggle compact mode
+  l           Toggle activity log
+  q/Ctrl+C    Quit sidebar
+
+CONFIG:
+  ~/.config/ccdock/config.json
+
+STATE:
+  ~/.local/state/ccdock/
+`.trim();
+
+	console.log(help);
+}
+
+async function main(): Promise<void> {
+	const [command, ...args] = process.argv.slice(2);
+
+	switch (command) {
+		case "start":
+		case undefined:
+			await runSidebar();
+			break;
+		case "hook":
+			await handleHook(args[0] ?? "claude-code", args[1] ?? "unknown");
+			break;
+		case "help":
+		case "--help":
+		case "-h":
+			printHelp();
+			break;
+		default:
+			console.error(`Unknown command: ${command}`);
+			printHelp();
+			process.exit(1);
+	}
+}
+
+await main();