viban

Visual Kanban — Issue tracking designed for AI agents.

Register bugs. Claude picks them up, resolves them, and creates PRs — while you keep finding the next issue.

# You find a bug and register it
/viban:add "Login fails after password reset"

# Claude assigns itself the top-priority issue and starts working
/viban:assign

# Or resolve 3 issues in parallel — each in its own git worktree
/viban:parallel-assign 3

Why viban?

GitHub Issues, Linear, and Jira are built for humans coordinating with humans. viban is built for humans coordinating with AI agents.

| | Traditional trackers | viban | |---|---|---| | Who resolves issues? | Human developers | AI agents (Claude Code) | | Parallel work | Manual branch management | Isolated worktrees, zero conflicts | | Where it lives | External SaaS | Your repo (single JSON file) | | Setup | Accounts, permissions, integrations | npm install -g claude-plugin-viban | | Context switching | Browser ↔ terminal | Everything in terminal | | Already using GitHub Issues? | — | Two-way sync included |

Quick Start

For Claude Code Users

/install claude-plugin-viban
/viban:setup

For Terminal Users

npm install -g claude-plugin-viban

Then start tracking:

viban add "Fix login error" "Users cannot login after password reset" P1 bug
viban add "Add dark mode" P2 feat
viban                        # Open TUI board

How It Works

Sequential Mode

Run multiple terminal sessions — one for QA, one for resolution, one for monitoring:

┌───────────────────┐  ┌───────────────────┐  ┌───────────────────┐
│    Session 1      │  │    Session 2      │  │    Session 3      │
│                   │  │                   │  │                   │
│  Product QA       │  │  Issue Work       │  │  viban TUI        │
│  + /viban:add     │  │  + /viban:assign  │  │                   │
│                   │  │                   │  │  (always open)    │
│  Find bugs,       │  │  Pick & resolve   │  │  Monitor board    │
│  register issues  │  │  issues           │  │  in real-time     │
└───────────────────┘  └───────────────────┘  └───────────────────┘

Parallel Mode

Resolve multiple issues at once with /viban:parallel-assign:

┌───────────────────┐
│   Coordinator     │  /viban:parallel-assign 3
│                   │
│  Assigns issues,  │──┬──────────────────────────────────────┐
│  creates worktrees│  │                                      │
│  collects results │  ▼                  ▼                   ▼
│                   │  ┌──────────┐  ┌──────────┐  ┌──────────┐
│                   │  │ Agent 1  │  │ Agent 2  │  │ Agent 3  │
│                   │  │ wt/#12   │  │ wt/#13   │  │ wt/#14   │
│                   │  │ Analyze  │  │ Analyze  │  │ Analyze  │
│                   │  │ Implement│  │ Implement│  │ Implement│
│                   │  │ Commit   │  │ Commit   │  │ Commit   │
│  Push, create PRs │  └──────────┘  └──────────┘  └──────────┘
│  Run tests, report│
└───────────────────┘

• Each agent works in an isolated git worktree (.viban/worktrees/{ID})
• Zero interference between agents — no merge conflicts
• Coordinator pushes branches, creates PRs, and runs tests after all agents finish

Claude Code Skills

These are the core AI-agent commands. Each one is a Claude Code slash command.

/viban:add — Register an issue

Analyzes your description and creates a structured issue with proper priority, type, and description.

/viban:add "Search is broken on mobile"
→ Infers: P1 bug, enriches description, registers to backlog

/viban:assign — Assign and resolve

Picks the highest-priority unblocked backlog issue, assigns it, and follows your project's workflow to resolve it.

/viban:assign
→ Picks #7 (P0 bug), analyzes code, implements fix, creates PR

/viban:parallel-assign — Parallel resolution

Assigns N issues (default 3, max 5) and spawns one agent per issue in isolated git worktrees.

/viban:parallel-assign 3
→ Assigns #8, #9, #10 — three agents work simultaneously
→ Each commits on its own branch, coordinator creates PRs

/viban:review — Checkout for IDE review

Checks out the issue branch and soft-resets so all changes appear as staged diffs in your IDE.

/viban:review
→ Finds first review card, checks out branch, staged diffs ready in IDE
/viban:review 12
→ Checks out branch for issue #12

/viban:approve — Approve and merge

Merges the issue branch, cleans up the worktree, and marks the card as done.

/viban:approve 12
→ Squash-merges PR, removes worktree/branch, marks #12 done

/viban:reject — Reject with feedback

Returns the issue to in_progress with optional feedback for the agent to address.

/viban:reject 12 "Missing error handling in auth flow"
→ Moves #12 back to in_progress, records feedback as comment

/viban:setup — Install and configure

Installs dependencies, detects your project conventions, and generates a workflow file.

TUI

viban    # Launch interactive board

3-column Kanban board (backlog → in_progress → review). Completed issues move to history.

| Level | Screen | Controls | |-------|--------|----------| | 1 | Column List | ↑↓ select, Enter to enter | | 2 | Card List | ↑↓ select, Enter for details, a to add | | 3 | Card Details | Change status, delete |

CLI Reference

# Board
viban list                                          # Show board
viban list --status backlog --priority P0,P1        # Filter
viban list --type bug --search "auth"               # Search
viban history                                       # Completed issues
viban stats                                         # Throughput metrics
viban export [md|html]                              # Export board

# Issues
viban add "Title" ["Desc"] [P0-P3] [type] [--parent <id>]
viban edit <id>                                     # Edit in editor
viban get <id>                                      # JSON details
viban priority <id> <P0-P3>
viban comment <id> "msg"
viban attach <id> <file1> [file2...]

# Workflow
viban assign                                        # Assign top backlog
viban review [id]                                   # → review
viban move <id> <status> [--force]                   # → any status
viban done <id> [--purge] [--force]                  # → done

# Dependencies
viban link <id> blocks <id>
viban unlink <id> blocks <id> [--dry-run]

# Maintenance
viban sync                                          # GitHub sync
viban backup / viban restore [file]
viban changelog [range]
viban update

Two-way sync with GitHub Issues. Comments, dependencies, and sub-tasks are synced.

viban sync --init       # Initialize (auto-detects from git remote)
viban sync --dry-run    # Preview changes
viban sync              # Pull + push
viban sync --push-new   # Push local-only issues to GitHub

Status mapping:

| viban | GitHub | |-------|--------| | backlog | (no label) | | in_progress | in-progress | | review | review | | done | (issue closed) |

Requires gh CLI authenticated with gh auth login.

Create .viban/templates.json to define defaults per issue type:

{
  "bug": {
    "priority": "P1",
    "description": "## Bug Report\n\n**Steps to reproduce:**\n\n**Expected:**\n\n**Actual:**"
  },
  "feat": {
    "priority": "P2",
    "description": "## Feature\n\n**User story:**\n\n**Acceptance criteria:**"
  }
}

Unset fields are filled from the template when the type matches.

Data Location

| Priority | Location | When | |----------|----------|------| | 1 | $VIBAN_DATA_DIR | Explicit override | | 2 | .viban/ | Default |

Auto-migrates from legacy .git/ location.

Priority Levels

| Priority | Description | |----------|-------------| | P0 | Critical — blocks all work | | P1 | High — must do soon | | P2 | Medium — normal priority | | P3 | Low — nice to have |

Type Tags

bug · feat · refactor · chore

Status Flow

backlog → in_progress → review → done
   ↑           ↑           │
   └───────────┴───────────┘
        (viban move)

Issues are stored in .viban/viban.json:

{
  "version": 2,
  "next_id": 4,
  "issues": [
    {
      "id": 1,
      "title": "Fix authentication bug",
      "description": "Users cannot login after password reset",
      "status": "in_progress",
      "priority": "P1",
      "type": "bug",
      "assigned_to": "session-abc123",
      "parent_id": null,
      "blocked_by": [3],
      "comments": [
        {"text": "Root cause found", "created_at": "2026-01-23T14:00:00Z"}
      ],
      "attachments": [],
      "created_at": "2026-01-23T10:00:00Z",
      "updated_at": "2026-01-23T14:30:00Z"
    }
  ]
}

Requirements

• zsh
• python3 (macOS/Linux built-in)
• gum
• jq
• gh (optional, for GitHub sync)

Development

brew install gum jq
zsh tests/run_all.zsh    # 20 suites, 237 tests

See docs/release.md for publishing.

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Open a Pull Request

License

MIT — see LICENSE.

Links

• npm · Issues · Docs