## Fabric Kanban — Multi-Agent Orchestration Board (Research Preview)

<p align="center">
  <img src="./web-ui/public/fabric-logo-white.svg" width="200" alt="Fabric Logo" />
</p>

<p align="center">
  <strong>A kanban foundation for coding agents — Fabric edition</strong>
</p>

<p align="center">
  A replacement for your IDE better suited for running many agents in parallel and reviewing diffs. Each task card gets its own terminal and worktree, all handled for you automatically. Enable auto-commit and link cards together to create dependency chains that complete large amounts of work autonomously.
</p>

> [!WARNING]
> Fabric Kanban is a research preview and uses experimental features of CLI agents like bypassing permissions and runtime hooks for more autonomy.

---

## Quick Start

### Install & Run

```bash
# Run once (no install)
npx @fabriccode/kanban

# Or install globally
npm i -g @fabriccode/kanban

# Launch
fabric-kanban
```

### From Source

```bash
git clone https://github.com/Fabric-Pro/fabric-kanban.git
cd fabric-kanban
npm install
npm run build
npm link
fabric-kanban
```

---

## Features

| Feature | Description |
|---------|-------------|
| **Parallel Agents** | Each task card runs in its own worktree with isolated terminal |
| **Auto-Commit/PR** | Enable autonomous mode — agents commit or open PRs on completion |
| **Dependency Chains** | Link tasks so one completing triggers the next |
| **Visual Diff Review** | See changes per task, leave comments, send back to agent |
| **Git Integration** | Full git UI: history, branches, fetch, pull, push |
| **Multi-Agent Support** | Claude, Codex, Gemini, OpenCode, Droid, Cline |

---

## Usage

### 1. Open Fabric Kanban

```bash
# Run directly (no install required)
npx @fabriccode/kanban

# Or install globally
npm i -g @fabriccode/kanban
fabric-kanban
```

Run this from the root of any git repo. Fabric Kanban will detect your installed CLI agent and launch a local running webserver in your browser. No account or setup required, it works right out of the box.

### 2. Create Tasks

Create a task card manually, or open the sidebar chat and ask your agent to break work down into tasks for you. Fabric Kanban injects board-management instructions into that session so you can simply ask it to add tasks, link tasks, or start work on your board.

### 3. Link and Automate

<kbd>⌘</kbd> + click a card to link it to another task. When a card is completed and moved to trash, linked tasks auto-start. Combine with auto-commit for fully autonomous dependency chains: one task completes → commits → kicks off the next → repeat. It's a pretty magical experience asking your agent to decompose a big task into subtasks that auto-commit — it'll cleverly do it in a way that parallelizes for maximum efficiency and links tasks together for end-to-end autonomy.

### 4. Start Tasks

Hit the play button on a card. Fabric Kanban creates an ephemeral worktree just for that task so agents work in parallel without merge conflicts. Under the hood, it also symlinks gitignored files like `node_modules` so you don't have to worry about slow `npm install`s for each copy of your project.

> [!NOTE]
> [Symlinks (symbolic links)](https://en.wikipedia.org/wiki/Symbolic_link) are special "shortcuts" pointing to another file or directory, allowing access to the target from a new location without duplicating data. They work great in this case since you typically don't modify gitignored files in day-to-day work, but for when you do then don't use Fabric Kanban.

As agents work, Fabric Kanban uses hooks to display the latest message or tool call on each card, so you can monitor hundreds of agents at a glance without opening each one.

### 5. Review Changes

Click a card to view the agent's TUI and a diff of all the changes in that worktree. Fabric Kanban includes its own checkpointing system so you can also see a diff from the last messages you've sent. Click on lines to leave comments and send them back to the agent.

To easily test and debug your app, create a Script Shortcut in settings. Use a command like `npm run dev` so that all you have to do is hit a play button in the navbar instead of remembering commands or asking your agent to do it.

### 6. Ship It

When the work looks good, hit **Commit** or **Open PR**. Fabric Kanban sends a dynamic prompt to the agent to convert the worktree into a commit on your base ref or a new PR branch, and work through any merge conflicts intelligently. Or skip review by enabling auto-commit / auto-PR and the agent ships as soon as it's done. Move the card to trash to clean up the worktree (you can always resume later since Fabric Kanban tracks the resume ID).

### 7. Keep Track with Git Interface

Click the branch name in the navbar to open a full git interface to browse commit history, switch branches, fetch, pull, push, and visualize your git all without leaving Fabric Kanban. Keep track of everything your agents are doing across branches as work is completed.

---

## Configuration

Data is stored in `~/.fabric-kanban/`:

```
~/.fabric-kanban/
├── kanban/           # Global config
├── worktrees/        # Task worktrees
└── data/             # Session data
```

Project-specific config: `<project>/.fabric-kanban/kanban/config.json`

---

## Architecture

Fabric Kanban is built on:

- **Runtime**: Node.js + Express + tRPC
- **UI**: React + Tailwind CSS + Radix UI
- **Terminal**: node-pty + xterm.js
- **Agent SDK**: Cline SDK (`@clinebot/*`) for native agent sessions

### Agent Support

| Agent | Status | Detection |
|-------|--------|-----------|
| Claude (Claude Code) | ✅ | `claude` on PATH |
| Codex (OpenAI) | ✅ | `codex` on PATH |
| Gemini CLI | ✅ | `gemini` on PATH |
| OpenCode | ✅ | `opencode` on PATH |
| Droid | ✅ | `droid` on PATH |
| Cline CLI | ✅ | `cline` on PATH |

---

## Development

```bash
# Install dependencies
npm run install:all

# Run dev servers (2 terminals)
npm run dev        # Backend (port 3484)
npm run web:dev    # Frontend (port 4173)

# Build & test
npm run build
npm run check
```

---

## NPM Registry

Published to the public npm registry as `@fabriccode/kanban`:

```bash
# View package
npm view @fabriccode/kanban

# Install globally
npm i -g @fabriccode/kanban

# Run without install
npx @fabriccode/kanban
```

### Publishing (maintainers only)

```bash
npm run check      # Verify all tests pass
npm version patch  # Bump version
npm run build      # Build dist
npm publish        # Publish to registry
```

---

## Telemetry

Fabric Kanban uses telemetry to improve the product:

- Errors and crashes (via Sentry)
- Usage patterns (via PostHog)

No source code or sensitive data is collected.

---

## License

[Apache 2.0 © 2026 Fabric](./LICENSE)

---

## Development

See [PUBLISHING.md](./PUBLISHING.md) for development setup, local testing, and publishing instructions.

---

## Related

- [Fabric](https://github.com/Fabric-Pro/fabric) — Core platform
- [Weave](https://github.com/Fabric-Pro/fabric-weave) — Plugin framework
- [Fabric Agents](https://github.com/Fabric-Pro/fabric-agents) — Desktop agent app
