@tosin2013/kanbn

Kanbn

🎯 Transform your Git repository into an AI-powered Kanban board. Track tasks, manage sprints, and leverage AI to optimize your workflow - all from the command line.

✨ Key Features

• 🤖 AI-powered task decomposition
• 💬 Interactive project management assistant
• 📊 Visual progress tracking and burndown charts
• 🔄 Git-friendly markdown-based task management
• 🏃‍♂️ Sprint planning and execution
• 📱 Command-line interface for speed and efficiency
• 🌐 RAG integrations with HTML-to-Markdown conversion

🚀 Quick Start

# Install kanbn globally
npm install -g @tosin2013/kanbn

# Note: If you encounter issues on certain Linux distributions (e.g., Red Hat Linux 9.5),
# try using a newer Node.js version (12, 16, 20, or 22)

# Initialize a new board
kanbn init

# Or use AI-powered initialization
kanbn init --ai

# Or bootstrap a new project with our script (requires OpenRouter API key)
curl -O https://raw.githubusercontent.com/decision-crafters/kanbn/refs/heads/master/examples/bootstrap.sh
chmod +x bootstrap.sh
./bootstrap.sh

# Add a task
kanbn add

# View your board
kanbn board

# Get help for any command
kanbn help <command>

## 🐳 Using Docker Container

```bash
# Pull the latest container image
docker pull quay.io/takinosh/kanbn:latest

# Run Kanbn commands using the container
docker run -it --rm \
  -v $(pwd):/workspace \
  -e OPENROUTER_API_KEY=$OPENROUTER_API_KEY \
  quay.io/takinosh/kanbn:latest kanbn <command>

# For example, to initialize a new board:
docker run -it --rm \
  -v $(pwd):/workspace \
  quay.io/takinosh/kanbn:latest kanbn init

# Or to view your board:
docker run -it --rm \
  -v $(pwd):/workspace \
  quay.io/takinosh/kanbn:latest kanbn board

The container mounts your current directory as /workspace, allowing Kanbn to manage tasks in your local project. For detailed container usage instructions and advanced configurations, see DOCKER.md.

🧪 Example Scripts

Check out the examples directory for interactive scripts that demonstrate Kanbn's features:

• interactive-demo.sh - A comprehensive demo of Kanbn's features
• bootstrap.sh - Quickly set up a new Kanbn project with AI assistance
• github-repo-init.sh - How to use Kanbn with existing GitHub repositories

Run any example with:

./examples/interactive-demo.sh

📚 Documentation

For full documentation, visit https://decision-crafters.github.io/kanbn/

Available Commands

====================================================
COMMAND: kanbn help
DESCRIPTION: Show help menu
====================================================
Usage:
  kanbn ......... Show help menu
  kanbn <command> [options]

Where <command> is one of:
  help .......... Show help menu
  version ....... Show package version
  init .......... Initialise kanbn board
  board ......... Show the kanbn board
  task .......... Show a kanbn task
  add ........... Add a kanbn task
  edit .......... Edit a kanbn task
  rename ........ Rename a kanbn task
  move .......... Move a kanbn task to another column
  comment ....... Add a comment to a task
  remove ........ Remove a kanbn task
  find .......... Search for kanbn tasks
  status ........ Get project and task statistics
  sort .......... Sort a column in the index
  sprint ........ Start a new sprint
  burndown ...... View a burndown chart
  validate ...... Validate index and task files
  archive ....... Archive a task
  restore ....... Restore a task from the archive
  remove-all .... Remove the kanbn board and all tasks
  decompose ..... Use AI to break down tasks into subtas

AI Features

kanbn decompose  # Use AI to break down tasks
kanbn chat       # Chat with AI project assistant
kanbn task task-id --prompt  # Generate AI-friendly prompt from task data
kanbn integrations --add --name docs --url https://example.com/docs  # Add web content as context
kanbn chat --integration docs  # Chat with context from integrations

Environment Variables for AI Features

# Required for AI features
OPENROUTER_API_KEY=your_api_key_here

# Optional: Specify a different model (defaults to google/gemma-3-4b-it:free)
OPENROUTER_MODEL=google/gemma-3-4b-it:free

# Optional: Force real API calls in test environment
USE_REAL_API=true

You can add these to a .env file in your project root. A .env.example file is provided as a template.

🤝 Contributing

We welcome contributions! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

🧪 Testing

Run tests with:

npm test

Testing OpenRouter API Integration

To verify that your OpenRouter API key is working correctly, you can use the included test script:

./test-openrouter-api.sh

This script will:

• Load your API key from the .env file or environment variables
• Make a test request to the OpenRouter API
• Verify that the response contains the expected data

You can also run the full test suite including API tests with:

./test-all-commands.sh

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

[0.14.0] - 2025-05-03

Added

• Added IPv4 compatibility mode for Ollama connections to improve container environment reliability
• Added detailed debugging for Ollama connectivity in container environments
• Enhanced test scripts with better error handling and diagnostic output
• Added automatic fallback to hash-based embeddings when using OpenRouter

Fixed

• Fixed IPv6/IPv4 connectivity issues with Ollama in container environments
• Fixed module import error in integrations controller
• Improved Docker network configuration for better host-container communication
• Enhanced error handling in CI/CD workflows to properly fail on test errors
• Fixed "Error creating vector store: fetch failed" when using OpenRouter with integrations
• Fixed RAG manager to prioritize hash-based embeddings when OpenRouter is configured

Changed

• Updated Ollama client to explicitly use IPv4 addresses for all API calls
• Improved test scripts to better handle Ollama connectivity issues
• Enhanced CI/CD workflow to provide more detailed diagnostic information
• Improved vector store creation with better error handling and fallback mechanisms