@towles/tool 0.0.107 → 0.0.109

package/README.md

@@ -12,13 +12,19 @@ claude plugin install tt@towles-tool
 claude plugin update tt@towles-tool
 ```
 
+### Global Install
+
+```bash
+bun install -g towles-tool
+```
+
 ### From Source
 
 ```bash
 git clone https://github.com/ChrisTowles/towles-tool.git
 cd towles-tool
 bun install
-bun start
+bun link
 ```
 
 ## CLI Commands

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@towles/tool",
-  "version": "0.0.107",
+  "version": "0.0.109",
   "description": "One off quality of life scripts that I use on a daily basis.",
   "homepage": "https://github.com/ChrisTowles/towles-tool#readme",
   "bugs": {
@@ -22,6 +22,7 @@
   "files": [
     "bin",
     "patches",
+    "plugins",
     "src"
   ],
   "type": "module",

package/plugins/tt-agentboard/README.md

@@ -0,0 +1,160 @@
+# AgentBoard
+
+Tmux sidebar TUI for monitoring sessions and AI agents. Based on [opensessions](https://github.com/nicholasgasior/opensessions).
+
+## Why
+
+AgentBoard v1 was a Nuxt web UI with embedded terminal rendering in the browser, built around a Kanban board workflow — create tickets, watch them move across columns as agents work. In practice, most tasks only need one or two touches before they're done, so constantly tracking which state a card is in added friction instead of removing it. The real unit of work is just a tmux session — when it's ready, merge it.
+
+On top of that, fighting the gap between a web page and the real terminal meant losing Claude Code's native TUI goodness — keybindings, scrollback, copy/paste, all the little things that just work in a real terminal. Less is more. A tmux sidebar that lives right next to your sessions keeps everything terminal-native, no translation layer needed.
+
+## Quick Start
+
+```bash
+# Install into tmux (one-time)
+tt agentboard setup
+
+# Reload tmux, then toggle the sidebar:
+# prefix a t
+```
+
+## Keybindings
+
+### Tmux (prefix defaults to `C-a`)
+
+| Key            | Action                   |
+| -------------- | ------------------------ |
+| `prefix a t`   | Toggle sidebar           |
+| `prefix a s`   | Focus sidebar            |
+| `prefix a 1-9` | Jump to session by index |
+
+### In Sidebar
+
+| Key                       | Action                      |
+| ------------------------- | --------------------------- |
+| `Tab` / `Shift+Tab`       | Cycle sessions              |
+| `j` / `k` / `Up` / `Down` | Move focus                  |
+| `Enter`                   | Switch to session           |
+| `1-9`                     | Jump to session             |
+| `d`                       | Hide session                |
+| `x`                       | Kill session (with confirm) |
+| `r`                       | Refresh                     |
+| `u`                       | Show all sessions           |
+| `n` / `c`                 | New session (fzf picker)    |
+| `?`                       | Help overlay                |
+| `q`                       | Quit                        |
+
+### Agent Detail Panel
+
+| Key                     | Action                 |
+| ----------------------- | ---------------------- |
+| `Right` / `l`           | Switch to agents panel |
+| `Left` / `h` / `Escape` | Back to sessions       |
+| `Enter`                 | Focus agent pane       |
+| `d`                     | Dismiss agent          |
+| `x`                     | Kill agent pane        |
+| `Alt+Up/Down`           | Reorder sessions       |
+
+## Architecture
+
+```
+plugins/tt-agentboard/
+  apps/
+    server/        WebSocket server (port 4201)
+    tui/           OpenTUI + Solid.js terminal UI
+  packages/
+    runtime/       Shared types, themes, agent watchers
+    mux-tmux/      Tmux provider (session/pane management)
+  scripts/         Tmux keybinding scripts
+  (tmux init via `tt agentboard init`)
+```
+
+### Server
+
+WebSocket server on `127.0.0.1:4201`. Auto-started by the TUI or tmux scripts.
+
+- Scans tmux sessions, git info, listening ports
+- Tracks agent status (Claude Code, Amp, Codex, OpenCode)
+- Broadcasts state to connected TUI clients
+- HTTP endpoints for tmux hooks (`/focus`, `/toggle`, `/ensure-sidebar`, etc.)
+
+### TUI
+
+Solid.js app rendered via OpenTUI. Connects to server over WebSocket.
+
+- Session cards with accent bars, status icons, branch info
+- Resizable detail panel with agent list + metadata
+- Mouse support (click, drag to resize)
+- Help overlay (`?`)
+
+#### TUI Components
+
+**`SessionCard`** (`components/SessionCard.tsx`) — session list item
+
+- Row 1: session name (truncated to 18 chars) + status icon (braille spinner when running, `●` for unseen terminal states)
+- Row 2: git branch + listening port hint (`⌁4201`, or `⌁4201+2` for multiple)
+- Row 3: metadata summary (status text + progress like `3/5` or `42%`)
+- Left accent bar colored by state: green (current), yellow (running), red (error), peach (interrupted), lavender (focused), teal (unseen done)
+
+**`DetailPanel`** (`components/DetailPanel.tsx`) — expanded view for focused session
+
+- Drag-resizable separator (height persisted per session in config)
+- Truncated working directory
+- Agent list via `AgentListItem` sub-component (see below)
+- Metadata section: status line with tone icon + progress, last 8 log entries
+
+**`AgentListItem`** (inside `DetailPanel.tsx`) — single agent instance row
+
+- Status icon: braille spinner (running), `◉` (waiting), `✓` (done), `✗` (error), `⚠` (interrupted)
+- Agent name, thread name, status text
+- Dismiss `✕` button (hover turns red), click row to focus the agent's tmux pane
+- Flash animation on click
+
+**`HelpOverlay`** (inline in `index.tsx`) — modal overlay
+
+- Shows all keybindings in a bordered dialog
+- Dismissed by pressing any key
+
+#### TUI Utilities
+
+- `constants.ts` — shared icons (`SPINNERS`, `UNSEEN_ICON`, `TONE_ICONS`), spark blocks for sparkline charts, theme list, tone-to-color mapping
+- `mux-context.ts` — tmux detection, pane refocus after startup, client TTY and session name resolution
+- `detail-panel-height.ts` — per-session detail panel height persistence (min 4 rows, default 10)
+
+## Configuration
+
+Config file: `~/.config/towles-tool/agentboard/config.json`
+
+```json
+{
+  "theme": "catppuccin-mocha",
+  "sidebarWidth": 26,
+  "sidebarPosition": "left"
+}
+```
+
+## CLI Commands
+
+```bash
+tt agentboard setup      # Install tmux plugin
+tt agentboard uninstall  # Remove from tmux
+tt agentboard server     # Start server manually
+tt agentboard tui        # Start TUI manually
+tt agentboard keys       # Show keybindings
+tt agentboard restart    # Kill stash sessions, ensure server, toggle sidebar on
+```
+
+## Agent Watchers
+
+Detects and tracks AI coding agents running in tmux sessions:
+
+- **Claude Code** - reads `~/.claude/projects/` JSONL journals
+- **Amp** - detects from pane titles
+- **Codex** - reads `~/.codex/logs_1.sqlite`
+- **OpenCode** - reads log files via `lsof`
+
+## Themes
+
+Theme is set via config file. Available themes:
+
+catppuccin-mocha, catppuccin-latte, catppuccin-frappe, catppuccin-macchiato, tokyo-night, gruvbox-dark, nord, dracula, github-dark, one-dark, kanagawa, everforest, material, cobalt2, flexoki, ayu, aura, matrix, transparent

package/plugins/tt-agentboard/apps/server/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@tt-agentboard/server",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/main.ts",
+  "types": "src/main.ts",
+  "scripts": {
+    "start": "bun run src/main.ts",
+    "dev": "bun --watch run src/main.ts"
+  },
+  "dependencies": {
+    "@tt-agentboard/mux-tmux": "workspace:*",
+    "@tt-agentboard/runtime": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  }
+}

package/plugins/tt-agentboard/apps/server/src/main.ts

@@ -0,0 +1,60 @@
+import {
+  AmpAgentWatcher,
+  ClaudeCodeAgentWatcher,
+  CodexAgentWatcher,
+  OpenCodeAgentWatcher,
+  PluginLoader,
+  loadConfig,
+  startServer,
+} from "@tt-agentboard/runtime";
+import { TmuxProvider } from "@tt-agentboard/mux-tmux";
+import { join } from "node:path";
+
+const config = loadConfig();
+const loader = new PluginLoader();
+
+// Register tmux provider (tmux only)
+try {
+  const provider = new TmuxProvider();
+  loader.registerMux(provider);
+} catch (err) {
+  console.error("Failed to initialize tmux provider:", err);
+}
+
+const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+const pluginDir = join(home, ".config", "towles-tool", "agentboard", "plugins");
+const localPlugins = loader.loadDir(pluginDir);
+if (localPlugins.length > 0) {
+  console.log(`Loaded local plugins: ${localPlugins.join(", ")}`);
+}
+
+if (config.plugins.length > 0) {
+  const npmPlugins = loader.loadPackages(config.plugins);
+  if (npmPlugins.length > 0) {
+    console.log(`Loaded npm plugins: ${npmPlugins.join(", ")}`);
+  }
+}
+
+const mux = loader.resolve(config.mux);
+if (!mux) {
+  console.error(
+    "No terminal multiplexer detected.\n" +
+      `Registered providers: ${loader.registry.list().join(", ") || "(none)"}\n` +
+      "$TMUX environment variable is not set — are you running inside a tmux session?\n" +
+      "Set 'mux' in ~/.config/towles-tool/agentboard/config.json to override.",
+  );
+  process.exit(1);
+}
+
+loader.registerWatcher(new AmpAgentWatcher());
+loader.registerWatcher(new ClaudeCodeAgentWatcher());
+loader.registerWatcher(new CodexAgentWatcher());
+loader.registerWatcher(new OpenCodeAgentWatcher());
+
+const watchers = loader.getWatchers();
+if (watchers.length > 0) {
+  console.log(`Agent watchers: ${watchers.map((watcher) => watcher.name).join(", ")}`);
+}
+
+console.log(`Primary mux provider: ${mux.name}`);
+startServer(mux, [], watchers);

package/plugins/tt-agentboard/apps/tui/build.ts

@@ -0,0 +1,11 @@
+import solidPlugin from "@opentui/solid/bun-plugin";
+
+await Bun.build({
+  entrypoints: ["./src/index.tsx"],
+  outdir: "./dist",
+  target: "bun",
+  minify: true,
+  plugins: [solidPlugin],
+});
+
+console.log("Build complete!");

package/plugins/tt-agentboard/apps/tui/bunfig.toml

@@ -0,0 +1 @@
+preload = ["@opentui/solid/preload"]

package/plugins/tt-agentboard/apps/tui/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@tt-agentboard/tui",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/index.tsx",
+  "scripts": {
+    "start": "bun run src/index.tsx",
+    "dev": "bun --watch run src/index.tsx",
+    "build": "bun run build.ts"
+  },
+  "dependencies": {
+    "@opentui/core": "^0.1.88",
+    "@opentui/solid": "^0.1.88",
+    "@tt-agentboard/mux-tmux": "workspace:*",
+    "@tt-agentboard/runtime": "workspace:*",
+    "solid-js": "^1.9.11"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  }
+}

package/plugins/tt-agentboard/apps/tui/scripts/sessionizer.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# agentboard sessionizer — fuzzy directory picker for new tmux sessions
+# Requires: fzf, find
+
+SEARCH_DIR="${SESSIONIZER_DIR:-$HOME/code}"
+
+if ! command -v fzf &>/dev/null; then
+  echo "fzf is required for the sessionizer. Install it: https://github.com/junegunn/fzf"
+  exit 1
+fi
+
+if [ ! -d "$SEARCH_DIR" ]; then
+  echo "Directory not found: $SEARCH_DIR"
+  exit 1
+fi
+
+selected=$(find "$SEARCH_DIR" -mindepth 1 -maxdepth 3 -type d 2>/dev/null | fzf \
+  --reverse \
+  --header="Pick a directory for new session" \
+  --preview=':' \
+  --preview-window=hidden \
+  --bind='ctrl-c:abort')
+
+[ -z "$selected" ] && exit 0
+
+# Derive session name from directory basename, replacing dots with underscores
+session_name=$(basename "$selected" | tr '.' '_')
+
+# If session already exists, just switch to it
+if tmux has-session -t "=$session_name" 2>/dev/null; then
+  tmux switch-client -t "$session_name"
+  exit 0
+fi
+
+tmux new-session -d -s "$session_name" -c "$selected"
+tmux switch-client -t "$session_name"