claude-code-kanban 1.16.0 → 1.18.0

package/README.md

@@ -35,6 +35,24 @@ npm install -g claude-code-kanban
 claude-code-kanban --open
 ```
 
+## Agent Log (subagent tracking)
+
+The Kanban footer can show live subagent activity (start/stop/idle) when hooks are installed. A one-time setup installs a lightweight shell script and adds hook entries to `~/.claude/settings.json`.
+
+```bash
+npx claude-code-kanban --install
+```
+
+This will:
+1. Copy `agent-spy.sh` to `~/.claude/hooks/` (requires `jq`)
+2. Add `SubagentStart`, `SubagentStop`, and `TeammateIdle` hooks to settings.json
+
+All changes are non-destructive — existing settings are preserved. To remove:
+
+```bash
+npx claude-code-kanban --uninstall
+```
+
 ## Configuration
 
 ```bash

package/hooks/agent-spy.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+# Tracks subagent lifecycle: one JSON file per agent, grouped by session
+# Layout: ~/.claude/agent-activity/{sessionId}/{agentId}.json
+
+INPUT=$(cat)
+
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty')
+AGENT_ID=$(echo "$INPUT" | jq -r '.agent_id // empty')
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // empty')
+
+[ -z "$SESSION_ID" ] || [ -z "$AGENT_ID" ] && exit 0
+
+AGENT_TYPE_RAW=$(echo "$INPUT" | jq -r '.agent_type // empty')
+DIR="$HOME/.claude/agent-activity/$SESSION_ID"
+FILE="$DIR/$AGENT_ID.json"
+
+# On Start: skip if no type (internal agents like AskUserQuestion)
+# On Stop/Idle: only skip if no existing file (never tracked)
+if [ -z "$AGENT_TYPE_RAW" ]; then
+  if [ "$EVENT" = "SubagentStart" ]; then
+    exit 0
+  elif [ ! -f "$FILE" ]; then
+    exit 0
+  fi
+fi
+
+mkdir -p "$DIR"
+TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+if [ "$EVENT" = "SubagentStart" ]; then
+  cat > "$FILE" <<EOF
+{"agentId":"$AGENT_ID","type":"$AGENT_TYPE_RAW","status":"active","startedAt":"$TS","updatedAt":"$TS"}
+EOF
+
+elif [ "$EVENT" = "SubagentStop" ]; then
+  # Read type and startedAt from existing file if available
+  AGENT_TYPE="$AGENT_TYPE_RAW"
+  STARTED_AT="$TS"
+  if [ -f "$FILE" ]; then
+    [ -z "$AGENT_TYPE" ] && AGENT_TYPE=$(jq -r '.type // "unknown"' "$FILE")
+    STARTED_AT=$(jq -r '.startedAt // empty' "$FILE")
+    [ -z "$STARTED_AT" ] && STARTED_AT="$TS"
+  fi
+  LAST_MSG=$(echo "$INPUT" | jq -r '.last_assistant_message // ""')
+  LAST_MSG_ESC=$(echo "$LAST_MSG" | jq -Rs '.')
+  cat > "$FILE" <<EOF
+{"agentId":"$AGENT_ID","type":"$AGENT_TYPE","status":"stopped","startedAt":"$STARTED_AT","lastMessage":$LAST_MSG_ESC,"stoppedAt":"$TS","updatedAt":"$TS"}
+EOF
+
+elif [ "$EVENT" = "TeammateIdle" ]; then
+  AGENT_TYPE="$AGENT_TYPE_RAW"
+  STARTED_AT="$TS"
+  if [ -f "$FILE" ]; then
+    [ -z "$AGENT_TYPE" ] && AGENT_TYPE=$(jq -r '.type // "unknown"' "$FILE")
+    STARTED_AT=$(jq -r '.startedAt // empty' "$FILE")
+    [ -z "$STARTED_AT" ] && STARTED_AT="$TS"
+  fi
+  cat > "$FILE" <<EOF
+{"agentId":"$AGENT_ID","type":"$AGENT_TYPE","status":"idle","startedAt":"$STARTED_AT","updatedAt":"$TS"}
+EOF
+fi

package/install.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+const { execSync } = require('child_process');
+
+const CLAUDE_DIR = path.join(os.homedir(), '.claude');
+const HOOKS_DIR = path.join(CLAUDE_DIR, 'hooks');
+const SETTINGS_PATH = path.join(CLAUDE_DIR, 'settings.json');
+const HOOK_SCRIPT_DEST = path.join(HOOKS_DIR, 'agent-spy.sh');
+const HOOK_SCRIPT_SRC = path.join(__dirname, 'hooks', 'agent-spy.sh');
+const AGENT_ACTIVITY_DIR = path.join(CLAUDE_DIR, 'agent-activity');
+
+const HOOK_COMMAND = '~/.claude/hooks/agent-spy.sh';
+const HOOK_EVENTS = ['SubagentStart', 'SubagentStop', 'TeammateIdle'];
+
+// ANSI helpers
+const green = s => `\x1b[32m${s}\x1b[0m`;
+const yellow = s => `\x1b[33m${s}\x1b[0m`;
+const red = s => `\x1b[31m${s}\x1b[0m`;
+const bold = s => `\x1b[1m${s}\x1b[0m`;
+const dim = s => `\x1b[2m${s}\x1b[0m`;
+
+function prompt(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => {
+    rl.question(question, answer => {
+      rl.close();
+      resolve(!answer || answer.trim().toLowerCase() !== 'n');
+    });
+  });
+}
+
+async function runInstall() {
+  console.log(`\n  ${bold('claude-code-kanban')} — Agent Log hook installer\n`);
+
+  // 1. Check jq
+  process.stdout.write('  Checking jq... ');
+  try {
+    const ver = execSync('jq --version', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    console.log(green(`✓ found (${ver})`));
+  } catch {
+    console.log(yellow('⚠ not found — hook script requires jq for JSON parsing'));
+  }
+
+  // 2. Hook script
+  console.log(`\n  Hook script: ${dim(HOOK_SCRIPT_DEST)}`);
+  let hookInstalled = false;
+  if (fs.existsSync(HOOK_SCRIPT_DEST)) {
+    const existing = fs.readFileSync(HOOK_SCRIPT_DEST, 'utf8');
+    const bundled = fs.readFileSync(HOOK_SCRIPT_SRC, 'utf8');
+    if (existing === bundled) {
+      console.log(`    ${green('✓')} Up to date`);
+      hookInstalled = true;
+    } else {
+      if (await prompt(`    Different version found. Update? [Y/n] `)) {
+        fs.mkdirSync(HOOKS_DIR, { recursive: true });
+        fs.copyFileSync(HOOK_SCRIPT_SRC, HOOK_SCRIPT_DEST);
+        try { fs.chmodSync(HOOK_SCRIPT_DEST, 0o755); } catch {}
+        console.log(`    ${green('✓')} Updated`);
+        hookInstalled = true;
+      } else {
+        console.log(`    ${dim('Skipped')}`);
+      }
+    }
+  } else {
+    if (await prompt(`    Not found. Install? [Y/n] `)) {
+      fs.mkdirSync(HOOKS_DIR, { recursive: true });
+      fs.copyFileSync(HOOK_SCRIPT_SRC, HOOK_SCRIPT_DEST);
+      try { fs.chmodSync(HOOK_SCRIPT_DEST, 0o755); } catch {}
+      console.log(`    ${green('✓')} Installed and set executable`);
+      hookInstalled = true;
+    } else {
+      console.log(`    ${dim('Skipped')}`);
+    }
+  }
+
+  // 3. Settings.json
+  console.log(`\n  Settings: ${dim(SETTINGS_PATH)}`);
+  let settings;
+  try {
+    if (fs.existsSync(SETTINGS_PATH)) {
+      settings = JSON.parse(fs.readFileSync(SETTINGS_PATH, 'utf8'));
+    } else {
+      settings = {};
+    }
+  } catch (e) {
+    console.log(`    ${red('✗')} Malformed JSON in settings.json — aborting settings update`);
+    printSummary(hookInstalled, false);
+    return;
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+
+  const needed = [];
+  for (const event of HOOK_EVENTS) {
+    if (!settings.hooks[event]) settings.hooks[event] = [];
+    const exists = settings.hooks[event].some(g =>
+      g.hooks?.some(h => h.command === HOOK_COMMAND)
+    );
+    if (!exists) needed.push(event);
+  }
+
+  let settingsUpdated = false;
+  if (needed.length === 0) {
+    console.log(`    ${green('✓')} Already configured`);
+    settingsUpdated = true;
+  } else {
+    console.log(`    Adding hooks for: ${needed.join(', ')}`);
+    if (await prompt(`    Update settings? [Y/n] `)) {
+      for (const event of needed) {
+        settings.hooks[event].push({
+          matcher: '',
+          hooks: [{ type: 'command', command: HOOK_COMMAND, timeout: 5 }]
+        });
+      }
+      fs.mkdirSync(CLAUDE_DIR, { recursive: true });
+      fs.writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n');
+      console.log(`    ${green('✓')} ${needed.length} hook entries added`);
+      settingsUpdated = true;
+    } else {
+      console.log(`    ${dim('Skipped')}`);
+    }
+  }
+
+  printSummary(hookInstalled, settingsUpdated);
+}
+
+function printSummary(hookOk, settingsOk) {
+  console.log('');
+  if (hookOk && settingsOk) {
+    console.log(`  ${green('Agent Log will appear in the Kanban footer when subagents are active.')}`);
+  } else {
+    console.log(`  ${yellow('Partial install — re-run --install to complete setup.')}`);
+  }
+  console.log('');
+}
+
+async function runUninstall() {
+  console.log(`\n  ${bold('claude-code-kanban')} — Agent Log hook uninstaller\n`);
+
+  // 1. Remove hook entries from settings.json
+  if (fs.existsSync(SETTINGS_PATH)) {
+    try {
+      const settings = JSON.parse(fs.readFileSync(SETTINGS_PATH, 'utf8'));
+      if (settings.hooks) {
+        let removed = 0;
+        for (const event of HOOK_EVENTS) {
+          if (!Array.isArray(settings.hooks[event])) continue;
+          const before = settings.hooks[event].length;
+          settings.hooks[event] = settings.hooks[event].filter(g =>
+            !g.hooks?.some(h => h.command === HOOK_COMMAND)
+          );
+          removed += before - settings.hooks[event].length;
+          if (settings.hooks[event].length === 0) delete settings.hooks[event];
+        }
+        if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+        fs.writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n');
+        console.log(`  Settings: ${green('✓')} Removed ${removed} hook entries`);
+      } else {
+        console.log(`  Settings: ${dim('No hook entries found')}`);
+      }
+    } catch {
+      console.log(`  Settings: ${red('✗')} Could not parse settings.json`);
+    }
+  } else {
+    console.log(`  Settings: ${dim('No settings.json found')}`);
+  }
+
+  // 2. Remove hook script
+  if (fs.existsSync(HOOK_SCRIPT_DEST)) {
+    fs.unlinkSync(HOOK_SCRIPT_DEST);
+    console.log(`  Hook script: ${green('✓')} Removed`);
+  } else {
+    console.log(`  Hook script: ${dim('Not found')}`);
+  }
+
+  // 3. Optionally remove agent-activity data
+  if (fs.existsSync(AGENT_ACTIVITY_DIR)) {
+    if (await prompt(`\n  Remove agent activity data (${AGENT_ACTIVITY_DIR})? [y/N] `)) {
+      fs.rmSync(AGENT_ACTIVITY_DIR, { recursive: true, force: true });
+      console.log(`  ${green('✓')} Agent activity data removed`);
+    } else {
+      console.log(`  ${dim('Kept agent activity data')}`);
+    }
+  }
+
+  console.log(`\n  ${green('Uninstall complete.')}\n`);
+}
+
+module.exports = { runInstall, runUninstall };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-kanban",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "description": "A web-based Kanban board for viewing Claude Code tasks with agent teams support",
   "main": "server.js",
   "bin": {
@@ -40,6 +40,8 @@
   },
   "files": [
     "server.js",
+    "install.js",
+    "hooks/agent-spy.sh",
     "public/**/*"
   ]
 }

package/public/index.html

@@ -1389,6 +1389,72 @@
       padding: 6px 10px;
     }
 
+    /* Agent footer panel */
+    .agent-footer {
+      display: none;
+      flex-direction: column;
+      border-top: 1px solid var(--border);
+      background: var(--bg-surface);
+    }
+    .agent-footer.visible { display: flex; }
+    .agent-footer-header {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      padding: 6px 24px;
+      cursor: pointer;
+      user-select: none;
+      color: var(--text-tertiary);
+      font-size: 12px;
+      letter-spacing: 0.05em;
+      text-transform: uppercase;
+    }
+    .agent-footer-header:hover { background: var(--bg-hover); }
+    .agent-footer-toggle {
+      background: none; border: none; color: var(--text-tertiary);
+      cursor: pointer; font-size: 14px; padding: 2px 4px;
+    }
+    .agent-footer-content {
+      display: flex;
+      gap: 10px;
+      padding: 0 24px 12px;
+      overflow-x: auto;
+      scrollbar-width: thin;
+    }
+    .agent-footer.collapsed .agent-footer-content { display: none; }
+    .agent-card {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      padding: 8px 14px;
+      background: var(--bg-elevated);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      white-space: nowrap;
+      min-width: 0;
+      overflow: hidden;
+      transition: opacity 0.3s;
+      cursor: pointer;
+    }
+    .agent-card:hover { border-color: var(--accent); }
+    .agent-card.fading { opacity: 0.4; }
+    .agent-dot {
+      width: 8px; height: 8px; border-radius: 50%; flex-shrink: 0;
+    }
+    .agent-dot.active { background: var(--success); box-shadow: 0 0 6px var(--success); }
+    .agent-dot.idle { background: var(--warning); box-shadow: 0 0 6px var(--warning); }
+    .agent-dot.stopped { background: var(--text-muted); }
+    .agent-type {
+      font-size: 13px; font-weight: 500; color: var(--text-primary);
+    }
+    .agent-status {
+      font-size: 11px; color: var(--text-tertiary);
+    }
+    .agent-message {
+      font-size: 11px; color: var(--text-muted);
+      max-width: 200px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+    }
+
     /* Light mode */
     body.light {
       --bg-deep: #e8e6e3;
@@ -2004,6 +2070,13 @@
             <div id="completed-tasks" class="column-tasks" role="list"></div>
           </div>
         </div>
+        <div id="agent-footer" class="agent-footer">
+          <div class="agent-footer-header" onclick="toggleAgentFooter()">
+            <span id="agent-footer-label">Agents</span>
+            <button class="agent-footer-toggle" id="agent-footer-toggle" aria-label="Toggle agent panel">&#x25BE;</button>
+          </div>
+          <div class="agent-footer-content" id="agent-footer-content"></div>
+        </div>
       </div>
     </main>
 
@@ -2042,6 +2115,9 @@
     let allTasksCache = []; // Cache all tasks for search
     let bulkDeleteSessionId = null; // Track session for bulk delete
     let ownerFilter = '';
+    let currentAgents = [];
+    let lastAgentsHash = '';
+    let agentDurationInterval = null;
     let selectedTaskId = null;
     let selectedSessionId = null;
     let focusZone = 'board'; // 'board' | 'sidebar'
@@ -2361,7 +2437,7 @@
       try {
         const res = await fetch('/api/tasks/all');
         const allTasks = await res.json();
-        let activeTasks = allTasks.filter(t => t.status === 'in_progress');
+        let activeTasks = allTasks.filter(t => t.status === 'in_progress' && !isInternalTask(t));
         if (filterProject) {
           activeTasks = activeTasks.filter(t => matchesProjectFilter(t.project));
         }
@@ -2423,6 +2499,7 @@
         ownerFilter = '';
         updateUrl();
         renderSession();
+        fetchAgents(sessionId);
       } catch (error) {
         console.error('Failed to fetch tasks:', error);
         currentTasks = [];
@@ -2433,11 +2510,182 @@
       }
     }
 
+    const AGENT_COOLDOWN_MS = 3 * 60 * 1000;
+    const AGENT_STALE_MS = 5 * 60 * 1000;
+    const AGENT_LOG_MAX = 8;
+
+    async function fetchAgents(sessionId) {
+      try {
+        const res = await fetch(`/api/sessions/${sessionId}/agents`);
+        if (!res.ok) { currentAgents = []; renderAgentFooter(); return; }
+        const agents = await res.json();
+        const hash = JSON.stringify(agents);
+        if (hash === lastAgentsHash) return;
+        lastAgentsHash = hash;
+        currentAgents = agents;
+        renderAgentFooter();
+      } catch (e) {
+        console.error('[fetchAgents]', e);
+      }
+    }
+
+    function formatDuration(ms) {
+      const s = Math.floor(ms / 1000);
+      if (s < 60) return `${s}s`;
+      const m = Math.floor(s / 60);
+      if (m < 60) return `${m}m ${s % 60}s`;
+      return `${Math.floor(m / 60)}h ${m % 60}m`;
+    }
+
+    function renderAgentFooter() {
+      const footer = document.getElementById('agent-footer');
+      const content = document.getElementById('agent-footer-content');
+      const label = document.getElementById('agent-footer-label');
+      const now = Date.now();
+
+      // Mark stale "active" agents as stopped (SubagentStop unreliable for shutdown agents)
+      const agents = currentAgents.map(a => {
+        if (a.status === 'active' && a.startedAt && (now - new Date(a.startedAt).getTime()) > AGENT_STALE_MS) {
+          return { ...a, status: 'stopped', stoppedAt: a.updatedAt };
+        }
+        return a;
+      });
+      // Filter shutdown ghosts: for same-type agents, keep if they overlapped (parallel)
+      // or started >30s after previous stopped (legitimate re-spawn). Filter the rest.
+      const byType = {};
+      for (const a of agents) { (byType[a.type] = byType[a.type] || []).push(a); }
+      const filtered = [];
+      for (const group of Object.values(byType)) {
+        group.sort((a, b) => new Date(a.startedAt || 0) - new Date(b.startedAt || 0));
+        filtered.push(group[0]);
+        for (let i = 1; i < group.length; i++) {
+          const prev = group[i - 1];
+          const prevStop = prev.stoppedAt ? new Date(prev.stoppedAt).getTime() : Infinity;
+          const curStart = new Date(group[i].startedAt || 0).getTime();
+          const overlapped = curStart < prevStop;
+          const reSpawn = curStart - prevStop > 30000;
+          if (overlapped || reSpawn) filtered.push(group[i]);
+        }
+      }
+      // Sort by updatedAt desc, keep up to 7 most recent
+      const visible = filtered
+        .sort((a, b) => new Date(b.updatedAt || 0) - new Date(a.updatedAt || 0))
+        .slice(0, AGENT_LOG_MAX);
+
+      if (visible.length === 0) {
+        footer.classList.remove('visible');
+        clearInterval(agentDurationInterval);
+        agentDurationInterval = null;
+        return;
+      }
+
+      footer.classList.add('visible');
+      label.textContent = `Agents Log (${visible.length})`;
+
+      const collapsed = localStorage.getItem('agentFooterCollapsed') === 'true';
+      footer.classList.toggle('collapsed', collapsed);
+      document.getElementById('agent-footer-toggle').innerHTML = collapsed ? '&#x25B4;' : '&#x25BE;';
+
+      content.innerHTML = visible.map(a => {
+        const elapsed = a.status === 'stopped' && a.stoppedAt
+          ? new Date(a.stoppedAt).getTime() - new Date(a.startedAt || a.stoppedAt).getTime()
+          : now - new Date(a.startedAt || a.updatedAt).getTime();
+        const statusText = a.status === 'stopped'
+          ? `stopped · ${formatDuration(elapsed)}`
+          : a.status === 'idle'
+          ? `idle · ${formatDuration(elapsed)}`
+          : `active · ${formatDuration(elapsed)}`;
+        const msgTrimmed = a.lastMessage?.trim() || '';
+        const msgTrunc = msgTrimmed.length > 60 ? msgTrimmed.substring(0, 60) + '…' : msgTrimmed;
+        const msgHtml = msgTrunc
+          ? `<div class="agent-message" title="${escapeHtml(msgTrimmed)}">${escapeHtml(msgTrunc)}</div>` : '';
+        return `<div class="agent-card" onclick="showAgentModal('${a.agentId}')">
+          <span class="agent-dot ${a.status}"></span>
+          <div>
+            <div class="agent-type">${escapeHtml(a.type || 'unknown')}</div>
+            <div class="agent-status">${statusText}</div>
+            ${msgHtml}
+          </div>
+        </div>`;
+      }).join('');
+
+      clearInterval(agentDurationInterval);
+      if (visible.some(a => a.status === 'active' || a.status === 'idle')) {
+        agentDurationInterval = setInterval(() => renderAgentFooter(), 1000);
+      } else {
+        agentDurationInterval = setInterval(() => renderAgentFooter(), 10000);
+      }
+    }
+
+    function toggleAgentFooter() {
+      const footer = document.getElementById('agent-footer');
+      const collapsed = !footer.classList.contains('collapsed');
+      footer.classList.toggle('collapsed', collapsed);
+      localStorage.setItem('agentFooterCollapsed', collapsed);
+      document.getElementById('agent-footer-toggle').innerHTML = collapsed ? '&#x25B4;' : '&#x25BE;';
+    }
+
+    function showAgentModal(agentId) {
+      const agent = currentAgents.find(a => a.agentId === agentId);
+      if (!agent) return;
+      const modal = document.getElementById('agent-modal');
+      const title = document.getElementById('agent-modal-title');
+      const body = document.getElementById('agent-modal-body');
+      const now = Date.now();
+      const started = agent.startedAt ? new Date(agent.startedAt) : null;
+      const stopped = agent.stoppedAt ? new Date(agent.stoppedAt) : null;
+      const elapsed = stopped && started
+        ? stopped.getTime() - started.getTime()
+        : started ? now - started.getTime() : 0;
+
+      const statusDot = `<span class="agent-dot ${agent.status}" style="display:inline-block;vertical-align:middle;margin-right:6px;"></span>`;
+      title.innerHTML = `${statusDot} ${escapeHtml(agent.type || 'unknown')}`;
+
+      const rows = [
+        ['Status', agent.status],
+        ['Agent ID', `<code style="font-size:12px;color:var(--text-tertiary)">${escapeHtml(agent.agentId)}</code>`],
+        ['Duration', formatDuration(elapsed)],
+      ];
+      if (started) rows.push(['Started', started.toLocaleTimeString()]);
+      if (stopped) rows.push(['Stopped', stopped.toLocaleTimeString()]);
+
+      let html = `<table style="width:100%;border-collapse:collapse;">` +
+        rows.map(([k, v]) =>
+          `<tr><td style="padding:6px 12px 6px 0;color:var(--text-tertiary);white-space:nowrap;vertical-align:top;">${k}</td><td style="padding:6px 0;color:var(--text-primary);">${v}</td></tr>`
+        ).join('') + `</table>`;
+
+      if (agent.lastMessage) {
+        const sanitized = typeof DOMPurify !== 'undefined' && typeof marked !== 'undefined'
+          ? DOMPurify.sanitize(marked.parse(agent.lastMessage.trim()))
+          : `<pre style="white-space:pre-wrap;margin:0;">${escapeHtml(agent.lastMessage.trim())}</pre>`;
+        html += `<div style="margin-top:16px;border-top:1px solid var(--border);padding-top:12px;">
+          <div style="font-size:12px;color:var(--text-tertiary);margin-bottom:8px;text-transform:uppercase;letter-spacing:0.05em;">Last Message</div>
+          <div class="detail-desc" style="font-size:13px;">${sanitized}</div>
+        </div>`;
+      }
+
+      body.innerHTML = html;
+      modal.classList.add('visible');
+      const keyHandler = (e) => {
+        if (e.key === 'Escape') {
+          e.preventDefault();
+          closeAgentModal();
+          document.removeEventListener('keydown', keyHandler);
+        }
+      };
+      document.addEventListener('keydown', keyHandler);
+    }
+
+    function closeAgentModal() {
+      document.getElementById('agent-modal').classList.remove('visible');
+    }
+
     async function showAllTasks() {
       try {
         viewMode = 'all';
         currentSessionId = null;
         ownerFilter = '';
+        currentAgents = []; lastAgentsHash = ''; renderAgentFooter();
         const res = await fetch('/api/tasks/all');
         let tasks = await res.json();
         if (filterProject) {
@@ -2457,8 +2705,9 @@
       sessionView.classList.add('visible');
       document.getElementById('owner-filter-bar').classList.remove('visible');
 
-      const totalTasks = currentTasks.length;
-      const completed = currentTasks.filter(t => t.status === 'completed').length;
+      const visibleTasks = currentTasks.filter(t => !isInternalTask(t));
+      const totalTasks = visibleTasks.length;
+      const completed = visibleTasks.filter(t => t.status === 'completed').length;
       const percent = totalTasks > 0 ? Math.round((completed / totalTasks) * 100) : 0;
 
       const isFiltered = filterProject && filterProject !== '__recent__';
@@ -2674,7 +2923,7 @@
     }
 
     function renderKanban() {
-      let filtered = currentTasks;
+      let filtered = currentTasks.filter(t => !isInternalTask(t));
       if (ownerFilter) {
         filtered = filtered.filter(t => t.owner === ownerFilter);
       }
@@ -3429,6 +3678,16 @@
             debouncedRefresh(data.sessionId, data.type === 'metadata-update');
           }
 
+          if (data.type === 'plan-update') {
+            refreshOpenPlan();
+          }
+
+          if (data.type === 'agent-update') {
+            if (currentSessionId && data.sessionId === currentSessionId) {
+              fetchAgents(currentSessionId);
+            }
+          }
+
           if (data.type === 'team-update') {
             console.log('[SSE] Team update:', data.teamName);
             debouncedRefresh(data.teamName, false);
@@ -3470,6 +3729,10 @@
       { bg: 'rgba(99, 102, 241, 0.14)', color: '#4f46e5' },  // indigo
     ];
     const ownerColorCache = {};
+    function isInternalTask(task) {
+      return task.metadata && task.metadata._internal === true;
+    }
+
     function getOwnerColor(name) {
       if (ownerColorCache[name]) return ownerColorCache[name];
       let hash = 5381;
@@ -3665,7 +3928,13 @@
 
       await Promise.all(promises);
 
-      const tasks = currentSessionId === sessionId ? currentTasks : [];
+      let tasks = currentSessionId === sessionId ? currentTasks : [];
+      if (tasks.length === 0) {
+        try {
+          const r = await fetch(`/api/sessions/${sessionId}`);
+          if (r.ok) tasks = await r.json();
+        } catch {}
+      }
       _planSessionId = sessionId;
       showInfoModal(session, teamConfig, tasks, planContent);
     }
@@ -3723,8 +3992,13 @@
       // Team info section
       if (teamConfig) {
         const ownerCounts = {};
+        const memberDescriptions = {};
         tasks.forEach(t => {
-          if (t.owner) ownerCounts[t.owner] = (ownerCounts[t.owner] || 0) + 1;
+          if (isInternalTask(t) && t.subject) {
+            memberDescriptions[t.subject] = t.description;
+          } else if (t.owner) {
+            ownerCounts[t.owner] = (ownerCounts[t.owner] || 0) + 1;
+          }
         });
 
         const members = teamConfig.members || [];
@@ -3739,11 +4013,13 @@
 
         members.forEach(member => {
           const taskCount = ownerCounts[member.name] || 0;
+          const memberDesc = memberDescriptions[member.name];
           html += `
             <div class="team-member-card">
               <div class="member-name">🟢 ${escapeHtml(member.name)}</div>
               <div class="member-detail">Role: ${escapeHtml(member.agentType || 'unknown')}</div>
               ${member.model ? `<div class="member-detail">Model: ${escapeHtml(member.model)}</div>` : ''}
+              ${memberDesc ? `<div class="member-detail" style="margin-top: 4px; font-style: italic; color: var(--text-secondary);">${escapeHtml(memberDesc.split('\n')[0])}</div>` : ''}
               <div class="member-tasks">Tasks: ${taskCount} assigned</div>
             </div>
           `;
@@ -3784,6 +4060,20 @@
 
     let _planSessionId = null;
 
+    function refreshOpenPlan() {
+      if (!_planSessionId || !document.getElementById('plan-modal').classList.contains('visible')) return;
+      fetch(`/api/sessions/${_planSessionId}/plan`)
+        .then(r => r.ok ? r.json() : null)
+        .then(data => {
+          if (data?.content) {
+            _pendingPlanContent = data.content;
+            const body = document.getElementById('plan-modal-body');
+            body.innerHTML = DOMPurify.sanitize(marked.parse(_pendingPlanContent));
+          }
+        })
+        .catch(() => {});
+    }
+
     function openPlanForSession(sid) {
       fetch(`/api/sessions/${sid}/plan`).then(r => r.ok ? r.json() : null).catch(() => null)
         .then(data => {
@@ -3832,7 +4122,7 @@
       }
 
       bar.classList.add('visible');
-      const owners = [...new Set(currentTasks.map(t => t.owner).filter(Boolean))].sort();
+      const owners = [...new Set(currentTasks.filter(t => !isInternalTask(t)).map(t => t.owner).filter(Boolean))].sort();
       select.innerHTML = '<option value="">All Members</option>' +
         owners.map(o => {
           const c = getOwnerColor(o);
@@ -4132,5 +4422,22 @@
       </div>
     </div>
   </div>
+
+  <div id="agent-modal" class="modal-overlay plan-modal-overlay" onclick="closeAgentModal()">
+    <div class="modal plan-modal" onclick="event.stopPropagation()">
+      <div class="modal-header">
+        <h3 id="agent-modal-title" class="modal-title">Agent</h3>
+        <button class="modal-close" aria-label="Close dialog" onclick="closeAgentModal()">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <path d="M18 6L6 18M6 6l12 12"/>
+          </svg>
+        </button>
+      </div>
+      <div id="agent-modal-body" class="modal-body" style="overflow-y: auto; flex: 1;"></div>
+      <div class="modal-footer">
+        <button class="btn btn-primary" onclick="closeAgentModal()">Close</button>
+      </div>
+    </div>
+  </div>
 </body>
 </html>

package/server.js

@@ -8,6 +8,15 @@ const readline = require('readline');
 const chokidar = require('chokidar');
 const os = require('os');
 
+const isSetupCommand = process.argv.includes('--install') || process.argv.includes('--uninstall');
+
+if (isSetupCommand) {
+  const { runInstall, runUninstall } = require('./install');
+  (process.argv.includes('--install') ? runInstall() : runUninstall())
+    .then(() => process.exit(0))
+    .catch(e => { console.error(e.message); process.exit(1); });
+}
+
 const app = express();
 const PORT = process.env.PORT || 3456;
 
@@ -32,6 +41,7 @@ const TASKS_DIR = path.join(CLAUDE_DIR, 'tasks');
 const PROJECTS_DIR = path.join(CLAUDE_DIR, 'projects');
 const TEAMS_DIR = path.join(CLAUDE_DIR, 'teams');
 const PLANS_DIR = path.join(CLAUDE_DIR, 'plans');
+const AGENT_ACTIVITY_DIR = path.join(CLAUDE_DIR, 'agent-activity');
 
 function isTeamSession(sessionId) {
   return existsSync(path.join(TEAMS_DIR, sessionId, 'config.json'));
@@ -219,13 +229,15 @@ function loadSessionMetadata() {
           const project = parentMeta?.project || leadMember?.cwd || teamConfig.working_dir || null;
 
           metadata[dir.name] = {
-            customTitle: parentMeta?.customTitle || null,
-            slug: parentMeta?.slug || null,
+            customTitle: teamConfig.description || dir.name,
+            slug: null,
             project,
             jsonlPath: parentMeta?.jsonlPath || null,
-            description: parentMeta?.description || teamConfig.description || null,
+            description: teamConfig.description || parentMeta?.description || null,
             gitBranch: parentMeta?.gitBranch || null,
-            created: parentMeta?.created || null
+            created: parentMeta?.created || null,
+            isTeamLeader: false,
+            teamLeaderId: teamConfig.leadSessionId || null
           };
         }
       }
@@ -294,6 +306,7 @@ app.get('/api/sessions', async (req, res) => {
             try {
               const taskPath = path.join(sessionPath, file);
               const task = JSON.parse(readFileSync(taskPath, 'utf8'));
+              if (task.metadata && task.metadata._internal) continue;
               if (task.status === 'completed') completed++;
               else if (task.status === 'in_progress') inProgress++;
               else pending++;
@@ -367,6 +380,21 @@ app.get('/api/sessions', async (req, res) => {
       }
     }
 
+    // Hide leader UUID sessions that are represented by a team session
+    const teamLeaderIds = new Set();
+    for (const [sid, session] of sessionsMap) {
+      if (session.isTeam) {
+        const cfg = loadTeamConfig(sid);
+        if (cfg?.leadSessionId) teamLeaderIds.add(cfg.leadSessionId);
+      }
+    }
+    for (const leaderId of teamLeaderIds) {
+      const session = sessionsMap.get(leaderId);
+      if (session && session.taskCount === 0) {
+        sessionsMap.delete(leaderId);
+      }
+    }
+
     // Convert map to array and sort by most recently modified
     let sessions = Array.from(sessionsMap.values());
     sessions.sort((a, b) => new Date(b.modifiedAt) - new Date(a.modifiedAt));
@@ -478,6 +506,30 @@ app.get('/api/teams/:name', (req, res) => {
   res.json(config);
 });
 
+// API: Get agents for a session
+app.get('/api/sessions/:sessionId/agents', (req, res) => {
+  let sessionId = req.params.sessionId;
+  // For team sessions, resolve to leader's session UUID
+  const teamConfig = loadTeamConfig(sessionId);
+  if (teamConfig && teamConfig.leadSessionId) {
+    sessionId = teamConfig.leadSessionId;
+  }
+  const agentDir = path.join(AGENT_ACTIVITY_DIR, sessionId);
+  if (!existsSync(agentDir)) return res.json([]);
+  try {
+    const files = readdirSync(agentDir).filter(f => f.endsWith('.json'));
+    const agents = [];
+    for (const file of files) {
+      try {
+        agents.push(JSON.parse(readFileSync(path.join(agentDir, file), 'utf8')));
+      } catch (e) { /* skip invalid */ }
+    }
+    res.json(agents);
+  } catch (e) {
+    res.json([]);
+  }
+});
+
 app.get('/api/version', (req, res) => {
   const pkg = require('./package.json');
   res.json({ version: pkg.version });
@@ -640,6 +692,13 @@ function broadcast(data) {
   }
 }
 
+app.use('/api', (req, res) => {
+  res.status(404).json({ error: 'Not found' });
+});
+
+// File watchers and server startup (skip for --install/--uninstall)
+if (!isSetupCommand) {
+
 // Watch for file changes (chokidar handles non-existent paths)
 const watcher = chokidar.watch(TASKS_DIR, {
   persistent: true,
@@ -706,35 +765,83 @@ plansWatcher.on('all', (event, filePath) => {
   if ((event === 'add' || event === 'change' || event === 'unlink') && filePath.endsWith('.md')) {
     lastMetadataRefresh = 0;
     broadcast({ type: 'metadata-update' });
+    if (event === 'change') {
+      const slug = path.basename(filePath, '.md');
+      broadcast({ type: 'plan-update', slug });
+    }
   }
 });
 
-app.use('/api', (req, res) => {
-  res.status(404).json({ error: 'Not found' });
+// Watch agent-activity directory for subagent lifecycle events
+const agentActivityWatcher = chokidar.watch(AGENT_ACTIVITY_DIR, {
+  persistent: true,
+  ignoreInitial: true,
+  depth: 2
 });
 
-// Start server
-const server = app.listen(PORT, () => {
-  const actualPort = server.address().port;
-  console.log(`Claude Task Viewer running at http://localhost:${actualPort}`);
+const AGENT_FILE_CAP = 20;
 
-  if (process.argv.includes('--open')) {
-    import('open').then(open => open.default(`http://localhost:${actualPort}`));
+agentActivityWatcher.on('all', (event, filePath) => {
+  if ((event === 'add' || event === 'change') && filePath.endsWith('.json')) {
+    const relativePath = path.relative(AGENT_ACTIVITY_DIR, filePath);
+    const sessionId = relativePath.split(path.sep)[0];
+    // Cleanup: if session dir exceeds cap, delete oldest files by mtime
+    if (event === 'add') {
+      try {
+        const sessionDir = path.join(AGENT_ACTIVITY_DIR, sessionId);
+        const files = readdirSync(sessionDir).filter(f => f.endsWith('.json'));
+        if (files.length > AGENT_FILE_CAP) {
+          const withStats = files.map(f => {
+            const fp = path.join(sessionDir, f);
+            return { file: fp, mtime: statSync(fp).mtimeMs };
+          }).sort((a, b) => a.mtime - b.mtime);
+          const toDelete = withStats.slice(0, files.length - AGENT_FILE_CAP);
+          for (const { file } of toDelete) {
+            fs.unlink(file).catch(() => {});
+          }
+        }
+      } catch (e) { /* ignore */ }
+    }
+    broadcast({ type: 'agent-update', sessionId });
+    // For team sessions, also broadcast with team name so frontend picks it up
+    if (existsSync(TEAMS_DIR)) {
+      try {
+        const teamDirs = readdirSync(TEAMS_DIR, { withFileTypes: true }).filter(d => d.isDirectory());
+        for (const td of teamDirs) {
+          const cfg = loadTeamConfig(td.name);
+          if (cfg && cfg.leadSessionId === sessionId) {
+            broadcast({ type: 'agent-update', sessionId: td.name });
+            break;
+          }
+        }
+      } catch (e) { /* ignore */ }
+    }
   }
 });
 
-server.on('error', (err) => {
-  if (err.code === 'EADDRINUSE') {
-    console.log(`Port ${PORT} in use, trying random port...`);
-    const fallback = app.listen(0, () => {
-      const actualPort = fallback.address().port;
-      console.log(`Claude Task Viewer running at http://localhost:${actualPort}`);
+const server = app.listen(PORT, () => {
+    const actualPort = server.address().port;
+    console.log(`Claude Task Viewer running at http://localhost:${actualPort}`);
 
-      if (process.argv.includes('--open')) {
-        import('open').then(open => open.default(`http://localhost:${actualPort}`));
-      }
-    });
-  } else {
-    throw err;
-  }
-});
+    if (process.argv.includes('--open')) {
+      import('open').then(open => open.default(`http://localhost:${actualPort}`));
+    }
+  });
+
+  server.on('error', (err) => {
+    if (err.code === 'EADDRINUSE') {
+      console.log(`Port ${PORT} in use, trying random port...`);
+      const fallback = app.listen(0, () => {
+        const actualPort = fallback.address().port;
+        console.log(`Claude Task Viewer running at http://localhost:${actualPort}`);
+
+        if (process.argv.includes('--open')) {
+          import('open').then(open => open.default(`http://localhost:${actualPort}`));
+        }
+      });
+    } else {
+      throw err;
+    }
+  });
+
+} // end if (!isSetupCommand)