@stilero/bankan 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniele Eliasson
+
+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,363 @@
+<p align="center">
+  <img src="docs/images/ban_kan_logo_readme.svg" alt="Ban Kan logo" width="520" />
+</p>
+
+# Ban Kan
+
+<p align="center">
+<strong>Run AI coding agents like a Kanban board.</strong>
+</p>
+
+<p align="center">
+Plan → Implement → Review → Pull Request
+</p>
+
+<p align="center">
+  The control center for managing many AI coding agents in one simple UI.
+</p>
+
+<p align="center">
+Bring order to parallel AI development without leaving your local workflow.
+</p>
+
+<p align="center">
+  <img src="docs/images/bankan_screenshot.png" alt="Ban Kan dashboard showing backlog, planning, implementation, review, and done columns" width="1200" />
+</p>
+
+<p align="center">
+  <a href="https://github.com/stilero/bankan/actions/workflows/ci.yml">CI</a>
+  ·
+  <a href="https://github.com/stilero/bankan">GitHub</a>
+  ·
+  <a href="https://github.com/stilero/bankan/issues">Issues</a>
+</p>
+
+<p align="center">
+⭐ If Ban Kan helps you ship faster, please consider starring the repo.
+</p>
+
+---
+
+## What Is Ban Kan
+
+Ban Kan is a **local control center for AI coding agents** that work across real repositories.
+
+Instead of one long AI chat trying to do everything, tasks move through a structured pipeline inspired by a Kanban board:
+
+Backlog → Planning → Implementation → Review → Done
+
+Each stage can use different agents, prompts, and concurrency settings. Developers keep full visibility and control over what is happening at every step.
+
+Ban Kan combines:
+
+- structured workflows
+- parallel agent execution
+- human approvals
+- local repository access
+- optional pull request automation
+
+All in one dashboard.
+
+---
+
+## Why Ban Kan Exists
+
+Most AI coding workflows eventually break down in the same way:
+
+- one giant prompt tries to do planning, coding, and review
+- context grows and token usage explodes
+- agents overwrite each other’s work
+- there is no clear review stage
+- parallel development becomes chaos
+
+Ban Kan fixes this with a model developers already understand:
+
+**a Kanban board with specialized AI agents.**
+
+Each stage has a clear responsibility, and tasks move forward only when the previous step succeeds.
+
+<table>
+  <tr>
+    <td align="center" width="50%">
+      <img src="docs/images/before_claude_windows.png" alt="Four separate Claude Code terminal windows used to coordinate parallel agent work before Ban Kan" width="100%" />
+      <br />
+      <strong>Before Ban Kan</strong>
+      <br />
+      Managing multiple agents means juggling separate terminal windows and fragmented context.
+    </td>
+    <td align="center" width="50%">
+      <img src="docs/images/bankan_multi_tasks.png" alt="Ban Kan dashboard showing multiple tasks and agent output in one coordinated interface" width="100%" />
+      <br />
+      <strong>With Ban Kan</strong>
+      <br />
+      Tasks, agent stages, approvals, and live output stay visible in one shared dashboard.
+    </td>
+  </tr>
+</table>
+
+---
+
+## Built for Agile Development
+
+Ban Kan fits naturally into Agile workflows where work is organized as stories.
+
+Each story moves through a structured lifecycle that mirrors how real development teams operate:
+
+```mermaid
+flowchart LR
+    A[Story / Task Created] --> B[Planning Agent]
+    B --> C[Implementation Agent]
+    C --> D[Review Agent]
+    D --> E[Done / Pull Request]
+```
+
+This structure makes Ban Kan especially useful when working with:
+
+- Agile user stories
+- sprint backlogs
+- feature tasks
+- incremental development
+
+Instead of one AI trying to solve everything in a single prompt, each stage has a clear responsibility — just like in a real Agile team.
+
+Developers plan the story, agents implement the work, reviewers validate the result, and the change moves forward when it meets quality gates.
+
+---
+
+## What It Looks Like In Practice
+
+Example story: **Add Stripe payments**
+
+Below is the same task moving through Ban Kan's workflow from creation to completion.
+
+### 1. Create the task
+
+<p align="center">
+  <img src="docs/images/workflow/add_task.png" alt="Ban Kan add task modal used to create the Stripe payments task" />
+</p>
+
+The developer creates a task in the dashboard and defines the story to be planned and executed.
+
+### 2. Planning starts
+
+<p align="center">
+  <img src="docs/images/workflow/planning_stage_started.png" alt="Ban Kan planning stage showing the Stripe payments task as planning starts" />
+</p>
+
+The planner agent picks up the task, analyzes the repository, and prepares an implementation plan.
+
+### 3. Review and approve the plan
+
+<p align="center">
+  <img src="docs/images/workflow/planning_approve_plan.png" alt="Ban Kan planning stage showing an approval-ready plan for the Stripe payments task" />
+</p>
+
+The generated plan is shown in the dashboard so the developer can approve it before any code is written.
+
+### 4. Implementation runs
+
+<p align="center">
+  <img src="docs/images/workflow/implementing_task.png" alt="Ban Kan implementation stage showing the Stripe payments task being actively worked on by an agent" />
+</p>
+
+After approval, the implementor agent creates its workspace, writes the code, and reports progress live in the UI.
+
+### 5. Review stage
+
+<p align="center">
+  <img src="docs/images/workflow/review_stage.png" alt="Ban Kan review stage showing the Stripe payments task being validated by a reviewer agent" />
+</p>
+
+The reviewer agent validates the implementation, checks for issues, and decides whether the task is ready to move forward.
+
+### 6. Done / ready for PR
+
+<p align="center">
+  <img src="docs/images/workflow/done_stage.png" alt="Ban Kan done stage showing the Stripe payments task completed and ready for pull request creation" />
+</p>
+
+Once review passes, the task moves to Done and can be used as the basis for a pull request.
+
+Multiple tasks can move through these stages simultaneously with different agents assigned to each step.
+
+---
+
+## Installation
+
+### Run instantly
+
+```bash
+npx bankan
+```
+
+### Install globally
+
+```bash
+npm install -g bankan
+bankan
+```
+
+### Run from source
+
+```bash
+git clone https://github.com/stilero/bankan.git
+cd bankan
+
+npm run install:all
+npm run setup
+npm run dev
+```
+
+Ban Kan starts a local server, opens your browser automatically, and serves the dashboard from the same process.
+
+---
+
+## Requirements
+
+- Node.js >= 18
+- git
+- One AI CLI tool:
+  - claude
+  - codex
+- Native build tools for node-pty
+
+macOS: Xcode Command Line Tools  
+Linux: build-essential
+
+---
+
+## Quick Start
+
+1. Launch Ban Kan
+
+```bash
+bankan
+```
+
+2. Complete the setup wizard
+
+3. Add one or more local repositories
+
+4. Create a task in the dashboard
+
+5. Approve the generated plan
+
+6. Watch agents implement and review the change
+
+7. Optionally create a pull request
+
+---
+
+## How It Works
+
+```mermaid
+flowchart TD
+    A[Developer creates task] --> B[Planner agent analyzes repository]
+    B --> C[Plan generated]
+    C --> D{Approve plan?}
+    D -->|Yes| E[Implementor writes code]
+    D -->|No| F[Revise plan]
+    E --> G[Reviewer validates changes]
+    G --> H{Review passed?}
+    H -->|Yes| I[Done / PR created]
+    H -->|No| E
+```
+
+Multiple tasks can run in parallel across different agents.
+
+---
+
+## Key Features
+
+### Parallel AI agents
+Run multiple planning, implementation, and review agents simultaneously.
+
+### Local-first workflow
+Repositories stay on your machine. Agents operate directly on local clones and workspaces.
+
+### Human approval gates
+Developers approve plans before implementation begins.
+
+### Live agent terminals
+Open the terminal of any running agent and take control when needed.
+
+### VS Code workspace support
+Open a task workspace directly from the dashboard.
+
+### PR automation
+Configure GitHub settings to automatically create pull requests.
+
+### Real-time dashboard
+Track:
+
+- active tasks
+- blocked tasks
+- agent activity
+- context usage
+
+---
+
+## CLI
+
+Ban Kan keeps the CLI intentionally simple.
+
+```bash
+bankan --port 3005
+bankan --no-open
+bankan --help
+```
+
+Options:
+
+- `--port` bind to a specific port
+- `--no-open` start without opening a browser
+
+Most workflows happen inside the dashboard after launch.
+
+---
+
+## Architecture
+
+Ban Kan includes:
+
+- Node / Express backend orchestration
+- WebSocket communication for live updates
+- React dashboard built with Vite
+- CLI launcher that starts the local app
+- Configurable planner, implementor, and reviewer agent pools
+
+---
+
+## Development
+
+```bash
+npm run setup
+npm run dev
+```
+
+Useful scripts:
+
+- `npm run build` – build client bundle
+- `npm run dev` – run server + Vite client
+- `npm run setup` – interactive setup wizard
+- `npm run install:all` – install all dependencies
+
+---
+
+## Contributing
+
+Contributions are welcome.
+
+1. Fork the repository
+2. Open an issue before starting work
+3. Create a focused branch
+4. Make your changes
+5. Submit a pull request
+
+Screenshots are appreciated for UI updates.
+
+---
+
+## License
+
+MIT

package/bin/bankan.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+
+import { existsSync } from 'node:fs';
+import net from 'node:net';
+import { spawn, execFileSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT_DIR = join(__dirname, '..');
+
+function parseArgs(argv) {
+  const args = { noOpen: false, port: null };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
+    if (arg === '--no-open') {
+      args.noOpen = true;
+      continue;
+    }
+
+    if (arg === '--help' || arg === '-h') {
+      args.help = true;
+      continue;
+    }
+
+    if (arg === '--port' || arg === '-p') {
+      const value = argv[i + 1];
+      if (!value || !/^\d+$/.test(value)) {
+        throw new Error('`--port` expects a numeric value.');
+      }
+      args.port = parseInt(value, 10);
+      i += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return args;
+}
+
+function printHelp() {
+  process.stdout.write(`Ban Kan\n\nUsage:\n  bankan [--port <number>] [--no-open]\n`);
+}
+
+function isPortAvailable(port, host) {
+  return new Promise((resolve) => {
+    const tester = net.createServer();
+    tester.once('error', () => resolve(false));
+    tester.once('listening', () => {
+      tester.close(() => resolve(true));
+    });
+    tester.listen(port, host);
+  });
+}
+
+async function findAvailablePort(preferredPort, host, { exact = false } = {}) {
+  if (exact) {
+    const available = await isPortAvailable(preferredPort, host);
+    if (!available) {
+      throw new Error(`Port ${preferredPort} is already in use.`);
+    }
+    return preferredPort;
+  }
+
+  for (let port = preferredPort; port < preferredPort + 20; port += 1) {
+    if (await isPortAvailable(port, host)) {
+      return port;
+    }
+  }
+
+  throw new Error(`Unable to find an open port near ${preferredPort}.`);
+}
+
+function openBrowser(url) {
+  if (process.platform === 'darwin') {
+    spawn('open', [url], { detached: true, stdio: 'ignore' }).unref();
+    return;
+  }
+
+  if (process.platform === 'win32') {
+    spawn('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore' }).unref();
+    return;
+  }
+
+  spawn('xdg-open', [url], { detached: true, stdio: 'ignore' }).unref();
+}
+
+function runSetup() {
+  execFileSync(process.execPath, [join(ROOT_DIR, 'scripts', 'setup.js')], {
+    env: process.env,
+    stdio: 'inherit',
+  });
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  process.env.BANKAN_RUNTIME_MODE = 'packaged';
+
+  const { getRuntimePaths } = await import('../server/src/paths.js');
+  const runtimePaths = getRuntimePaths();
+
+  if (!existsSync(runtimePaths.clientDistDir)) {
+    throw new Error('Built client assets are missing. Rebuild the package before publishing.');
+  }
+
+  if (!existsSync(runtimePaths.envFile) && !existsSync(runtimePaths.settingsFile)) {
+    runSetup();
+  }
+
+  const { default: config } = await import('../server/src/config.js');
+  const { startServer } = await import('../server/src/index.js');
+
+  const host = '127.0.0.1';
+  const preferredPort = args.port ?? config.PORT;
+  const port = await findAvailablePort(preferredPort, host, { exact: args.port !== null });
+  const { server, port: resolvedPort } = await startServer({ port, host });
+  const url = `http://${host}:${resolvedPort}`;
+
+  process.stdout.write(`Ban Kan available at ${url}\n`);
+
+  if (!args.noOpen) {
+    try {
+      openBrowser(url);
+    } catch (err) {
+      process.stderr.write(`Failed to open browser automatically: ${err.message}\n`);
+    }
+  }
+
+  const shutdown = () => {
+    server.close(() => process.exit(0));
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err.message}\n`);
+  process.exit(1);
+});

package/client/dist/assets/index-BZkAflU1.css

@@ -0,0 +1,32 @@
+/**
+ * Copyright (c) 2014 The xterm.js authors. All rights reserved.
+ * Copyright (c) 2012-2013, Christopher Jeffrey (MIT License)
+ * https://github.com/chjj/term.js
+ * @license MIT
+ *
+ * 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.
+ *
+ * Originally forked from (with the author's permission):
+ *   Fabrice Bellard's javascript vt100 for jslinux:
+ *   http://bellard.org/jslinux/
+ *   Copyright (c) 2011 Fabrice Bellard
+ *   The original design remains. The terminal itself
+ *   has been extended to include xterm CSI codes, among
+ *   other features.
+ */.xterm{cursor:text;position:relative;user-select:none;-ms-user-select:none;-webkit-user-select:none}.xterm.focus,.xterm:focus{outline:none}.xterm .xterm-helpers{position:absolute;top:0;z-index:5}.xterm .xterm-helper-textarea{padding:0;border:0;margin:0;position:absolute;opacity:0;left:-9999em;top:0;width:0;height:0;z-index:-5;white-space:nowrap;overflow:hidden;resize:none}.xterm .composition-view{background:#000;color:#fff;display:none;position:absolute;white-space:nowrap;z-index:1}.xterm .composition-view.active{display:block}.xterm .xterm-viewport{background-color:#000;overflow-y:scroll;cursor:default;position:absolute;right:0;left:0;top:0;bottom:0}.xterm .xterm-screen{position:relative}.xterm .xterm-screen canvas{position:absolute;left:0;top:0}.xterm .xterm-scroll-area{visibility:hidden}.xterm-char-measure-element{display:inline-block;visibility:hidden;position:absolute;top:0;left:-9999em;line-height:normal}.xterm.enable-mouse-events{cursor:default}.xterm.xterm-cursor-pointer,.xterm .xterm-cursor-pointer{cursor:pointer}.xterm.column-select.focus{cursor:crosshair}.xterm .xterm-accessibility:not(.debug),.xterm .xterm-message{position:absolute;left:0;top:0;bottom:0;right:0;z-index:10;color:transparent;pointer-events:none}.xterm .xterm-accessibility-tree:not(.debug) *::selection{color:transparent}.xterm .xterm-accessibility-tree{-webkit-user-select:text;user-select:text;white-space:pre}.xterm .live-region{position:absolute;left:-9999px;width:1px;height:1px;overflow:hidden}.xterm-dim{opacity:1!important}.xterm-underline-1{text-decoration:underline}.xterm-underline-2{text-decoration:double underline}.xterm-underline-3{text-decoration:wavy underline}.xterm-underline-4{text-decoration:dotted underline}.xterm-underline-5{text-decoration:dashed underline}.xterm-overline{text-decoration:overline}.xterm-overline.xterm-underline-1{text-decoration:overline underline}.xterm-overline.xterm-underline-2{text-decoration:overline double underline}.xterm-overline.xterm-underline-3{text-decoration:overline wavy underline}.xterm-overline.xterm-underline-4{text-decoration:overline dotted underline}.xterm-overline.xterm-underline-5{text-decoration:overline dashed underline}.xterm-strikethrough{text-decoration:line-through}.xterm-screen .xterm-decoration-container .xterm-decoration{z-index:6;position:absolute}.xterm-screen .xterm-decoration-container .xterm-decoration.xterm-decoration-top-layer{z-index:7}.xterm-decoration-overview-ruler{z-index:8;position:absolute;top:0;right:0;pointer-events:none}.xterm-decoration-top{z-index:2;position:relative}:root{--bg: #0C0C0E;--bg1: #111114;--bg2: #16161A;--bg3: #1C1C22;--border: #252530;--border2: #2E2E3C;--amber: #F5A623;--steel2: #6AABDB;--green: #3DDC84;--red: #FF4D4D;--yellow: #FFD166;--purple: #A78BFA;--blue: #60A5FA;--text: #E8E8F0;--text2: #9090A8;--text3: #50505E;--font-mono: "DM Mono", monospace;--font-head: "Syne", sans-serif}*,*:before,*:after{box-sizing:border-box;margin:0;padding:0}html,body,#root{height:100%;overflow:hidden}body{font-family:var(--font-mono);font-size:13px;color:var(--text);background:var(--bg);-webkit-font-smoothing:antialiased}::-webkit-scrollbar{width:6px;height:6px}::-webkit-scrollbar-track{background:transparent}::-webkit-scrollbar-thumb{background:var(--border2);border-radius:3px}::-webkit-scrollbar-thumb:hover{background:var(--text3)}@keyframes card-enter{0%{opacity:0;transform:translate(-12px) scale(.97)}to{opacity:1;transform:translate(0) scale(1)}}@keyframes pulse{0%,to{opacity:1}50%{opacity:.4}}@keyframes fade-in{0%{opacity:0;transform:translateY(8px)}to{opacity:1;transform:translateY(0)}}@keyframes toast-in{0%{opacity:0;transform:translate(100px)}to{opacity:1;transform:translate(0)}}button{font-family:var(--font-mono);cursor:pointer;border:none;background:none;color:var(--text);font-size:12px}input,textarea,select{font-family:var(--font-mono);font-size:13px;color:var(--text);background:var(--bg);border:1px solid var(--border);border-radius:4px;padding:8px 12px;outline:none}input:focus,textarea:focus,select:focus{border-color:var(--amber)}select option{color:var(--text);background:var(--bg1)}