🔥 Kanby

A Beautiful Terminal-Based Kanban Board

Kanby brings the power of Kanban boards directly to your terminal with a clean, intuitive interface built using Python's curses library.

✨ Features

• 🎯 Multiple Projects: Organize different projects separately
• 📊 Customizable Columns: Default "To Do", "In Progress", "Done"
• 🎨 Priority Levels: Low, Mid, High priority tasks with color coding
• 💾 Persistent Storage: All data saved locally in JSON format
• ⌨️ Keyboard Navigation: Full keyboard control for efficiency
• 🎭 Beautiful UI: Clean, colorful terminal interface with splash screen
• 🚀 Fast & Lightweight: Minimal dependencies (Windows curses auto-installed on Windows)
• 🌍 Cross-Platform: Works on Linux, macOS, and Windows with proper curses support
• 🔧 CLI Options: Custom data file locations and more

📦 Installation

Using pip

pip install kanby

Windows Users: The windows-curses dependency will be automatically installed on Windows systems.

Using uv

uv add kanby

From source

git clone https://github.com/vladzima/kanby
cd kanby
pip install -e .

Windows Compatibility

Kanby automatically handles Windows curses compatibility. If you encounter issues on Windows, ensure you have:

• Python 3.7 or later
• The windows-curses package (installed automatically)

🚀 Usage

Simply run:

kanby

Or with custom data file:

kanby --data-file /path/to/your/kanban.json

For help:

kanby --help

⌨️ Keyboard Controls

Navigation

Task Management

Project Management

In Project Manager

Application

🎯 Task Management

Creating Tasks

1. Press a to add a new task
2. Enter the task title
3. Choose priority (L/M/H for Low/Mid/High)
4. Task appears in current column

Editing Tasks

1. Navigate to a task using arrow keys
2. Press e to edit
3. Modify title and/or priority
4. Changes are saved automatically

Moving Tasks

1. Select a task with arrow keys
2. Press m to enter move mode
3. Use arrow keys to move:
   • ← → : Move between columns
   • ↑ ↓ : Reorder within current column
4. Press Enter to confirm or Esc to cancel

Task Visibility & Scrolling

Column headers show task counts and visibility information:

• All visible: To Do (5) - shows total count when all tasks fit
• Scrolling needed: To Do (3-7/15) - shows visible range when scrolling
• Empty column: To Do (0) - indicates no tasks in column

Navigate through long task lists with ↑ ↓ arrows. Headers automatically update to show which tasks are currently visible on screen.

Priority Levels

Tasks display with compact priority indicators on the same line:

• [H] Task title: High priority (red color coding)
• [M] Task title: Mid priority (yellow color coding)
• [L] Task title: Low priority (green color coding)

This space-efficient format allows 3x more tasks to be visible on screen compared to the previous multi-line format.

📁 Project Management

Multiple Projects

• Press p to open the project manager
• Navigate with ↑ ↓ arrow keys
• Press Enter to switch to selected project

Creating Projects

1. In project manager, press n
2. Enter new project name
3. Project is created with default columns

Renaming Projects

1. In project manager, select project to rename
2. Press r to rename
3. Enter new project name
4. All tasks and data are preserved
5. Cannot rename to an existing project name

Deleting Projects

1. In project manager, select project
2. Press d to delete
3. Confirm with y
4. Cannot delete the last remaining project

🔧 Configuration

Data Storage

Kanby stores data in kanby_data.json in your current directory by default.

Custom Data File

Specify a custom location:

kanby --data-file ~/.config/kanby/my-projects.json

Data Format

The JSON file contains all projects and tasks:

{
  "Project Name": {
    "To Do": [
      {
        "id": "abc123",
        "title": "Task title",
        "priority": "High"
      }
    ],
    "In Progress": [],
    "Done": []
  }
}

🎨 Color Scheme

Kanby uses a carefully designed color scheme:

• Project names: Cyan
• Column headers: Blue (active: Green)
• Task priorities: Green (Low), Yellow (Mid), Red (High)
• Selected items: Yellow background
• Messages: Green (info), Red (error)
• Borders: White

💻 System Requirements

• Python 3.7 or higher
• Terminal with curses support
• Unix-like system (Linux, macOS) or Windows with proper terminal

🛠️ Development

Setup

git clone https://github.com/vladzima/kanby
cd kanby
pip install -e .

Running Tests

python -m pytest

Code Structure

kanby/
├── kanby/
│   ├── __init__.py    # Package initialization
│   └── main.py        # Main application logic
├── pyproject.toml     # Package configuration
├── README.md          # This file
└── LICENSE           # MIT License

🐛 Troubleshooting

Terminal Issues

If your terminal becomes corrupted after an error:

reset

Color Issues

If colors don't display properly, your terminal may not support them. Kanby will fall back to a monochrome display.

Size Issues

Kanby adapts to your terminal size, but works best with at least 80x24 characters.

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

How to Contribute

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Reporting Issues

Please use the GitHub issue tracker to report bugs or request features.

Made with ❤️ for terminal enthusiasts and productivity lovers