agent-takkub 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 takkub
+
+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,71 @@
+<div align="center">
+
+# 🛩️ agent-takkub
+
+**A desktop cockpit for running a whole team of Claude Code agents — together, in one window.**
+
+You direct a **Lead**; the Lead orchestrates specialist teammates
+(frontend · backend · qa · reviewer · devops · …) as live panes.
+
+`Windows` · `macOS` · runs entirely on your machine
+
+</div>
+
+---
+
+## Install
+
+```bash
+npm install -g agent-takkub    # isolated Python runtime + a Desktop icon
+claude login                   # one-time auth — your Claude account
+takkub provision               # recommended plugins + browser tooling
+```
+
+Then **double-click “Takkub Cockpit” on your Desktop** — or run `agent-takkub`.
+
+> **Prerequisites:** Node ≥ 18 and Python ≥ 3.11 — *detected, never reinstalled.*
+> No clone, no manual wiring. Everything lands in an isolated `~/.agent-takkub`;
+> your existing `claude` CLI, plugins, and config are left untouched.
+
+---
+
+## Why
+
+- **🧠 One Lead, many specialists** — talk to the Lead; it spawns the right roles on demand.
+- **🔀 Real parallelism** — independent features fan out across panes; QA always runs last.
+- **🖥️ Live, steerable panes** — every teammate is a real `claude` process you can watch.
+- **🗂️ Multi-project tabs** — one isolated Lead per project, no cross-talk.
+- **🧩 Batteries included** — Playwright browser automation, curated skill plugins, session memory, decision logs.
+- **🔒 Local-first** — no SaaS, nothing leaves your machine; runs on your logged-in `claude`.
+
+---
+
+## The flow
+
+```
+you  →  Lead  →  assign  →  spawn claude pane  →  work  →  done  →  verify (QA)  →  ship
+                    ↑__________________ fan out across roles __________________↑
+```
+
+Say what you want. The Lead plans it, dispatches the right specialists, gathers
+their results, runs verification, and proposes the ship — you stay in control.
+
+---
+
+## Everyday commands
+
+| Command | |
+|---|---|
+| `takkub assign --role backend "…"` | spawn + task a teammate |
+| `takkub send --to qa "…"` | message a peer (Lead CC’d) |
+| `takkub provision` | install / repair plugins + browser tools |
+| `takkub doctor` | diagnose the environment |
+
+---
+
+## More
+
+- **Architecture & flow diagrams** — [`docs/system-overview/`](docs/system-overview/)
+- **From source / one-shot installer** (Chrome, gh, codex, rtk, …) — [`docs/INSTALL.md`](docs/INSTALL.md)
+
+<div align="center"><sub>Windows + macOS · built on PyQt6 · powered by the Claude Code CLI</sub></div>

package/npm/bin/agent-takkub.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+'use strict';
+// Launches the cockpit GUI from the provisioned (isolated) venv.
+const { spawnSync } = require('child_process');
+const { venvPythonIfExists } = require('../scripts/lib');
+
+const py = venvPythonIfExists();
+if (!py) {
+  console.error('agent-takkub is not provisioned. Run: npm install -g agent-takkub');
+  process.exit(1);
+}
+const r = spawnSync(py, ['-m', 'agent_takkub', ...process.argv.slice(2)], { stdio: 'inherit' });
+process.exit(r.status == null ? 1 : r.status);

package/npm/bin/takkub.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+'use strict';
+// The `takkub` CLI, run from the provisioned (isolated) venv.
+const { spawnSync } = require('child_process');
+const { venvPythonIfExists } = require('../scripts/lib');
+
+const py = venvPythonIfExists();
+if (!py) {
+  console.error('takkub is not provisioned. Run: npm install -g agent-takkub');
+  process.exit(1);
+}
+const r = spawnSync(py, ['-m', 'agent_takkub.cli', ...process.argv.slice(2)], { stdio: 'inherit' });
+process.exit(r.status == null ? 1 : r.status);

package/npm/scripts/lib.js

@@ -0,0 +1,43 @@
+'use strict';
+// Shared helpers for the npm wrapper. Pure path logic — importing this file
+// runs NOTHING and touches nothing on disk.
+
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+
+// The cockpit's per-install home. Deliberately SEPARATE from a git dev
+// checkout's `.venv`, so `npm install -g agent-takkub` never collides with a
+// from-source setup. Overridable via AGENT_TAKKUB_HOME so an isolated smoke
+// test can point at a throwaway dir and leave ~/.agent-takkub untouched.
+function agentTakkubHome() {
+  return process.env.AGENT_TAKKUB_HOME || path.join(os.homedir(), '.agent-takkub');
+}
+
+function venvDir() {
+  return path.join(agentTakkubHome(), 'venv');
+}
+
+// The venv's python, per-platform (Windows: Scripts\python.exe, else bin/python).
+function venvPython() {
+  const dir = venvDir();
+  return process.platform === 'win32'
+    ? path.join(dir, 'Scripts', 'python.exe')
+    : path.join(dir, 'bin', 'python');
+}
+
+function venvPythonIfExists() {
+  const p = venvPython();
+  return fs.existsSync(p) ? p : null;
+}
+
+// Windowless python for GUI launchers (Windows: pythonw.exe = no console
+// window pops up behind the cockpit). macOS has no separate pythonw.
+function venvPythonw() {
+  const dir = venvDir();
+  return process.platform === 'win32'
+    ? path.join(dir, 'Scripts', 'pythonw.exe')
+    : path.join(dir, 'bin', 'python');
+}
+
+module.exports = { agentTakkubHome, venvDir, venvPython, venvPythonIfExists, venvPythonw };

package/npm/scripts/postinstall.js

@@ -0,0 +1,114 @@
+'use strict';
+// npm postinstall bootstrap for `npm install -g agent-takkub`.
+//
+// SAFETY MODEL — check first, never clobber:
+//   • Detects what's already present (preflight.js, non-mutating) and REPORTS it.
+//   • Provisions ONLY into the isolated AGENT_TAKKUB_HOME (default
+//     ~/.agent-takkub) — never a repo `.venv`, never shared user state.
+//   • REUSES an existing cockpit venv (upgrade in place) instead of wiping it.
+//   • Does NOT touch the global claude CLI, ~/.claude plugins, or ~/.takkub
+//     config. Anything shared/missing is left for an explicit, detect-first
+//     `takkub doctor --fix` the user runs consciously.
+// Cross-platform (win32 + darwin); idempotent; fails loudly on missing Python
+// or a missing bundled wheel.
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { agentTakkubHome, venvDir, venvPython } = require('./lib');
+const preflight = require('./preflight');
+
+function findWheel() {
+  // Shipped alongside this package under dist/ (see package.json `files`).
+  const dist = path.join(__dirname, '..', '..', 'dist');
+  if (!fs.existsSync(dist)) return null;
+  const whl = fs.readdirSync(dist).filter((f) => f.endsWith('.whl')).sort();
+  return whl.length ? path.join(dist, whl[whl.length - 1]) : null;
+}
+
+function run(cmd, args) {
+  return spawnSync(cmd, args, { stdio: 'inherit' }).status === 0;
+}
+
+// Install the claude CLI only when it's missing — never overwrite an existing
+// (possibly version-pinned) global install. Returns true if claude is available
+// afterward. Best-effort: a failure just falls back to a "install it yourself"
+// hint in the next-steps.
+function ensureClaudeCli(present) {
+  if (present) return true;
+  const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  console.log('[agent-takkub] claude CLI not found — installing @anthropic-ai/claude-code…');
+  return run(npm, ['install', '-g', '@anthropic-ai/claude-code']);
+}
+
+function main() {
+  const env = preflight.detect();
+  preflight.report(env);
+
+  if (!env.python.present) {
+    console.error(
+      '\n[agent-takkub] Python >=3.11 not found. Install it, then re-run ' +
+        '`npm install -g agent-takkub`.'
+    );
+    process.exit(1);
+  }
+  const wheel = findWheel();
+  if (!wheel) {
+    console.error('\n[agent-takkub] bundled wheel missing under dist/ — package build is incomplete.');
+    process.exit(1);
+  }
+
+  fs.mkdirSync(agentTakkubHome(), { recursive: true });
+
+  // Reuse an existing venv (upgrade in place); create only when absent — never wipe.
+  if (env.venv.present) {
+    console.log('\n[agent-takkub] existing cockpit venv found — upgrading in place (not recreated).');
+  } else {
+    console.log(`\n[agent-takkub] creating venv at ${venvDir()}`);
+    if (!run(env.python.cmd, [...env.python.args, '-m', 'venv', venvDir()])) {
+      console.error('[agent-takkub] failed to create venv.');
+      process.exit(1);
+    }
+  }
+
+  const vpy = venvPython();
+  run(vpy, ['-m', 'pip', 'install', '--upgrade', 'pip', '--quiet']);
+  console.log('[agent-takkub] installing/upgrading cockpit + PyQt6 (may take a few minutes)…');
+  // Step 1: install/upgrade the cockpit + its deps (PyQt etc.) normally.
+  if (!run(vpy, ['-m', 'pip', 'install', '--upgrade', wheel])) {
+    console.error('[agent-takkub] pip install failed.');
+    process.exit(1);
+  }
+  // Step 2: force-refresh the app package itself. pip's --upgrade treats an
+  // equal version as "already satisfied" and SKIPS it, so a same-version
+  // reinstall (a repair, or a rebuilt wheel whose version didn't bump) would
+  // otherwise keep stale code. --no-deps scopes this to the tiny app package —
+  // PyQt was already handled in step 1, so this stays fast. Best-effort: step 1
+  // already succeeded, so a hiccup here shouldn't fail the whole install.
+  run(vpy, ['-m', 'pip', 'install', '--force-reinstall', '--no-deps', wheel]);
+
+  const claudeOk = ensureClaudeCli(env.claudeCli.present);
+
+  console.log(`\n[agent-takkub] ✓ cockpit ready (isolated in ${agentTakkubHome()}).`);
+  try {
+    const sc = require('./shortcut').create();
+    if (sc) console.log(`[agent-takkub] ✓ Desktop launcher created: ${sc}`);
+  } catch (_e) {
+    /* best-effort — a missing shortcut never fails the install */
+  }
+  console.log('   Left untouched: ~/.claude plugins, ~/.takkub config (nothing overwritten).');
+  console.log('\n   Next steps:');
+  if (!claudeOk) {
+    console.log('     • install the claude CLI: npm i -g @anthropic-ai/claude-code');
+  }
+  console.log('     1) claude login          # authenticate (one-time, your account)');
+  console.log('     2) takkub provision      # install recommended plugins + browser MCPs (idempotent)');
+  console.log('     3) double-click "Takkub Cockpit" on the Desktop  (or run: agent-takkub)\n');
+}
+
+try {
+  main();
+} catch (e) {
+  console.error('[agent-takkub] postinstall error:', e && e.message);
+  process.exit(1);
+}

package/npm/scripts/preflight.js

@@ -0,0 +1,57 @@
+'use strict';
+// Non-mutating environment detection. Runs ONLY `--version`-style probes and
+// filesystem existence checks — nothing here installs, writes, or overwrites.
+// This is what lets the installer "check first": report what's already present
+// and provision ONLY the gaps, so a machine that already has Python / claude /
+// a cockpit venv is never clobbered.
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const { venvPython, agentTakkubHome } = require('./lib');
+
+function probe(cmd, args) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8' });
+  if (r.status !== 0) return null;
+  return ((r.stdout || '') + (r.stderr || '')).trim();
+}
+
+function detectPython() {
+  const cands = process.platform === 'win32'
+    ? [['py', ['-3.11', '--version']], ['py', ['-3', '--version']], ['python', ['--version']]]
+    : [['python3.11', ['--version']], ['python3', ['--version']], ['python', ['--version']]];
+  for (const [cmd, args] of cands) {
+    const out = probe(cmd, args);
+    const m = out && out.match(/Python (\d+)\.(\d+)\.\d+/);
+    if (m) {
+      const maj = parseInt(m[1], 10);
+      const min = parseInt(m[2], 10);
+      if (maj > 3 || (maj === 3 && min >= 11)) {
+        // Drop the trailing '--version' so callers can reuse (cmd, args) to run python.
+        return { present: true, version: `${maj}.${min}`, cmd, args: args.slice(0, -1) };
+      }
+    }
+  }
+  return { present: false };
+}
+
+// Detect the whole environment without mutating anything.
+function detect() {
+  const claude = probe('claude', ['--version']);
+  return {
+    python: detectPython(),
+    node: probe('node', ['--version']),
+    claudeCli: claude ? { present: true, version: claude } : { present: false },
+    venv: { present: fs.existsSync(venvPython()), path: venvPython() },
+    home: agentTakkubHome(),
+  };
+}
+
+function report(d) {
+  console.log('[agent-takkub] environment check (nothing below is overwritten):');
+  console.log(`    Python >=3.11 : ${d.python.present ? '✓ ' + d.python.version + ' (reuse existing)' : '· missing'}`);
+  console.log(`    Node          : ${d.node ? '✓ ' + d.node : '· missing'}`);
+  console.log(`    claude CLI    : ${d.claudeCli.present ? '✓ ' + d.claudeCli.version + ' (kept as-is)' : '· not found'}`);
+  console.log(`    cockpit venv  : ${d.venv.present ? '✓ exists (reuse/upgrade)' : '· will create'} — ${d.home}`);
+}
+
+module.exports = { detect, report };

package/npm/scripts/shortcut.js

@@ -0,0 +1,110 @@
+'use strict';
+// Best-effort Desktop launcher creation (win32 + darwin). NEVER throws — a
+// failure just means no icon; the `agent-takkub` command still works. The
+// Desktop location is overridable via AGENT_TAKKUB_DESKTOP so an isolated test
+// (or a user who wants it elsewhere) doesn't touch the real Desktop.
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { venvPythonw, venvPython } = require('./lib');
+
+function desktopDir() {
+  return process.env.AGENT_TAKKUB_DESKTOP || path.join(os.homedir(), 'Desktop');
+}
+
+function iconAsset(name) {
+  return path.join(__dirname, '..', '..', 'assets', name);
+}
+
+// Single-quote a string for a PowerShell literal (double any embedded quote).
+function psStr(s) {
+  return "'" + String(s).replace(/'/g, "''") + "'";
+}
+
+function createWindows() {
+  const lnk = path.join(desktopDir(), 'Takkub Cockpit.lnk');
+  const target = venvPythonw();
+  const ico = iconAsset('icon.ico');
+  // WorkingDirectory = the venv root (…/venv), two levels up from Scripts\pythonw.exe.
+  const workdir = path.dirname(path.dirname(target));
+  const lines = [
+    '$ws = New-Object -ComObject WScript.Shell',
+    `$sc = $ws.CreateShortcut(${psStr(lnk)})`,
+    `$sc.TargetPath = ${psStr(target)}`,
+    "$sc.Arguments = '-m agent_takkub'",
+    `$sc.WorkingDirectory = ${psStr(workdir)}`,
+  ];
+  if (fs.existsSync(ico)) lines.push(`$sc.IconLocation = ${psStr(ico)}`);
+  lines.push("$sc.Description = 'agent-takkub dev team cockpit'");
+  lines.push('$sc.Save()');
+
+  fs.mkdirSync(desktopDir(), { recursive: true });
+  // Run from a temp .ps1 FILE, not an inline -Command: passing a long quoted
+  // command through Node→Windows arg-escaping mangles the quotes and produces
+  // an empty shortcut. A -File avoids all of that.
+  const ps1 = path.join(os.tmpdir(), `att-shortcut-${process.pid}.ps1`);
+  fs.writeFileSync(ps1, lines.join('\r\n') + '\r\n', 'utf8');
+  try {
+    const r = spawnSync(
+      'powershell',
+      ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', ps1],
+      { stdio: 'ignore' }
+    );
+    return r.status === 0 && fs.existsSync(lnk) ? lnk : null;
+  } finally {
+    try {
+      fs.unlinkSync(ps1);
+    } catch (_e) {
+      /* ignore */
+    }
+  }
+}
+
+function createMac() {
+  const appDir = path.join(desktopDir(), 'Takkub Cockpit.app');
+  const macos = path.join(appDir, 'Contents', 'MacOS');
+  const res = path.join(appDir, 'Contents', 'Resources');
+  fs.mkdirSync(macos, { recursive: true });
+  fs.mkdirSync(res, { recursive: true });
+
+  const launch = `#!/bin/sh\nexec ${JSON.stringify(venvPython())} -m agent_takkub "$@"\n`;
+  fs.writeFileSync(path.join(macos, 'launch'), launch);
+  fs.chmodSync(path.join(macos, 'launch'), 0o755);
+
+  const plist =
+    '<?xml version="1.0" encoding="UTF-8"?>\n' +
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" ' +
+    '"http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n' +
+    '<plist version="1.0"><dict>\n' +
+    '  <key>CFBundleName</key><string>Takkub Cockpit</string>\n' +
+    '  <key>CFBundleExecutable</key><string>launch</string>\n' +
+    '  <key>CFBundleIdentifier</key><string>com.takkub.cockpit</string>\n' +
+    '  <key>CFBundleIconFile</key><string>icon</string>\n' +
+    '  <key>CFBundlePackageType</key><string>APPL</string>\n' +
+    '</dict></plist>\n';
+  fs.writeFileSync(path.join(appDir, 'Contents', 'Info.plist'), plist);
+
+  // Convert the bundled png → icns with sips (macOS built-in). Best-effort.
+  const png = iconAsset('icon.png');
+  if (fs.existsSync(png)) {
+    spawnSync('sips', ['-s', 'format', 'icns', png, '--out', path.join(res, 'icon.icns')], {
+      stdio: 'ignore',
+    });
+  }
+  return fs.existsSync(path.join(macos, 'launch')) ? appDir : null;
+}
+
+// Returns the created launcher path, or null if unsupported/failed.
+function create() {
+  try {
+    if (process.platform === 'win32') return createWindows();
+    if (process.platform === 'darwin') return createMac();
+  } catch (_e) {
+    /* best-effort — never block the install over a shortcut */
+  }
+  return null;
+}
+
+module.exports = { create };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "agent-takkub",
+  "version": "1.0.0",
+  "description": "Desktop cockpit for orchestrating a team of Claude Code agents (Windows + macOS)",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai-agents",
+    "agent-orchestration",
+    "cockpit",
+    "desktop",
+    "cli",
+    "developer-tools"
+  ],
+  "author": "takkub",
+  "bin": {
+    "agent-takkub": "npm/bin/agent-takkub.js",
+    "takkub": "npm/bin/takkub.js"
+  },
+  "scripts": {
+    "postinstall": "node npm/scripts/postinstall.js"
+  },
+  "files": [
+    "npm/",
+    "dist/*.whl",
+    "assets/icon.ico",
+    "assets/icon.png"
+  ],
+  "os": [
+    "win32",
+    "darwin"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}