viban

Visual Kanban - A simple, lightweight local Kanban board for AI-human collaborative issue tracking.


!viban screenshot

Why viban?

- No Worktree Complexity - Just a single JSON file. No git worktrees, no complex setup.
- Lightweight & Fast - Pure shell script with minimal dependencies. Starts instantly.
- Local First - Your issues stay in your repo. No external services or accounts needed.
- AI-Native - Built for Claude Code integration from the ground up.

Recommended Workflow

The most effective way to use viban is with multiple terminal sessions:

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

- Session 1: QA your product, find issues, run /viban:task to register them
- Session 2: Run /viban:assign to pick the next issue and resolve it
- Session 3: Keep viban TUI open to monitor the board

This separation keeps your workflow clean and prevents context switching.

Features

- 3-Column Kanban Board: backlog → in_progress → review → done
- Priority Levels: P0 (critical) to P3 (low priority)
- Type Tags: bug, feat, chore, refactor
- TUI Navigation: Interactive terminal UI with gum
- Parallel Sessions: Multiple Claude Code sessions can work simultaneously
- Session Assignment: Prevents duplicate work across parallel agents
- Claude Code Integration: Built-in commands for automated issue resolution

Requirements

- zsh
- python3 (macOS/Linux built-in)
- gum
- jq

> Tip: If using Claude Code, run /viban:setup to install all dependencies automatically.

Installation

$3

`bash
/plugin marketplace add https://github.com/happy-nut/claude-plugin-viban
/plugin install viban
/viban:setup # Installs all dependencies automatically
`

$3

`bash
curl -fsSL https://raw.githubusercontent.com/happy-nut/claude-plugin-viban/main/install.sh | bash
`

Or via npm (requires zsh, gum, jq pre-installed):
`bash
npm install -g claude-plugin-viban
`

Troubleshooting: viban command not found

Add npm global bin to your PATH:
`bash


For zsh

echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.zshrc && source ~/.zshrc

For bash

echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc && source ~/.bashrc
`


Usage

$3

`bash
viban # Launch TUI
`

Navigation:

| 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 |

TUI Features:
- Navigate between backlog, in_progress, review, done columns
- View issue cards with priority and type badges
- Create new issues with rich descriptions
- Move issues between statuses
- Delete issues

$3

`bash
viban list # Display kanban board
viban add "Title" "Description" P2 feat # Create new issue
viban assign [session-id] # Assign top backlog issue
viban review [id] # Move issue to review
viban done # Mark issue as done
viban get # Get issue details (JSON)
viban help # Show help message
`

Examples:

`bash


Add a high-priority bug

viban add "Fix login error" "Users cannot login after password reset" P1 bug

List all issues

viban list

Assign first backlog issue to current session

viban assign

Mark issue #5 as done

viban done 5

Get issue details as JSON

viban get 3
`

$3

viban provides commands for automated issue management in Claude Code:

#### /viban:assign - Auto-resolve next issue

Automatically picks the highest priority backlog issue and executes the full resolution workflow:

1. Fetches top backlog issue
2. Assigns to current session
3. Analyzes and implements the fix
4. Marks as review/done upon completion

Use cases:
- Autonomous issue resolution
- Parallel agent workflows
- Pre-prioritized backlog processing

#### /viban:task - Create structured issue

Analyzes a problem and creates a properly structured viban issue:

1. Prompts for problem description
2. Analyzes symptoms, root cause, expected behavior
3. Creates issue with proper title, description, priority, type

Use cases:
- Bug reporting
- Feature requests
- Converting free-form descriptions to structured issues

Configuration

$3

viban stores issues in viban.json with the following priority:

| Priority | Location | When Used |
|----------|----------|-----------|
| 1 | $VIBAN_DATA_DIR | Explicit override via environment variable |
| 2 | .git/ (git common dir) | In a git repository (shared across worktrees) |
| 3 | .viban/ | Non-git directories (fallback) |

Why Git Common Dir?
- Shared across git worktrees (parallel work sessions)
- Survives branch switches
- Single source of truth for the repository

For Non-Git Projects:
`bash


viban will automatically create .viban/viban.json in current directory

cd /path/to/non-git-project
viban add "First issue" "Description" P2 feat

Creates: /path/to/non-git-project/.viban/viban.json

`

Custom Data Directory:
`bash
export VIBAN_DATA_DIR="/path/to/shared/data"
viban list # Uses /path/to/shared/data/viban.json
`

$3

viban automatically initializes when first used:
- Creates data directory if not exists
- Creates viban.json with empty issue list
- No manual setup required

$3

`
backlog → in_progress → review → done
↑ ↑
(assign) (complete)
`

$3

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

$3

| Type | Use Case |
|------|----------|
| bug | Fixing broken functionality |
| feat | New feature or enhancement |
| refactor | Code restructuring |
| chore | Maintenance tasks |
| docs | Documentation updates |
| test | Test additions/fixes |

Data Structure

Issues are stored in viban.json:

`json
{
"version": 1,
"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",
"created_at": "2025-01-23T10:00:00Z",
"updated_at": "2025-01-23T14:30:00Z"
}
]
}
`

Parallel Session Handling

Multiple Claude Code sessions can work simultaneously:

1. Each session calls /viban:assign
2. Session ID is recorded in assigned_to field
3. Other sessions skip already-assigned issues
4. Completion moves issue to review or done

This prevents duplicate work and enables parallel agent workflows.

File Structure

`
claude-plugin-viban/
├── .claude-plugin/
│ └── plugin.json # Plugin metadata
├── .github/
│ └── workflows/
│ ├── ci.yml # CI testing
│ └── release.yml # NPM publishing
├── bin/
│ └── viban # Main TUI/CLI script
├── docs/
│ └── CLAUDE.md # Claude Code integration guide
├── scripts/
│ ├── check-deps.sh # Dependency checker
│ └── tui_coprocess.py # Persistent Python coprocess for TUI rendering
├── skills/
│ ├── assign/SKILL.md # /viban:assign skill
│ ├── setup/SKILL.md # /viban:setup skill
│ └── task/SKILL.md # /viban:task skill
├── LICENSE # MIT License
├── package.json # NPM package config
└── README.md # This file
`

Development

$3

`bash


Install dependencies

brew install gum jq

Make executable

chmod +x bin/viban scripts/check-deps.sh

Run tests

./bin/viban help

Test in a git repo

cd /path/to/git/repo
viban add "Test issue" "Test description" P2 feat
viban list
`

$3

`bash


Update version in package.json

npm version patch # or minor, major

Create and push tag

git tag v1.0.1
git push origin v1.0.1

GitHub Actions will automatically publish to npm

`

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)
5. Open a Pull Request

License

MIT License - see LICENSE file for details.

Author

happy-nut

- GitHub: @happy-nut
- Repository: claude-plugin-viban

Links

- npm package
- Documentation
- Issues