Kanban

一个终端看板应用，使用 Rust 开发，灵感来自 Helix 编辑器的键位设计。

特别适合与 AI 协作：基于 Markdown 文件存储，一键复制任务内容（Y），快速将任务目录和内容分享给 AI 助手，让 AI 帮你规划和管理任务。

预览

核心特性

• 📁 基于文件存储 - Markdown + TOML，易于版本控制，AI 可直接读取项目目录
• 🤖 内置 MCP Server - 直接与 Claude Code 等 AI 工具集成，让 AI 帮你管理看板
• 📋 快速复制 - 一键复制任务到剪贴板 (Y)，方便分享给 AI
• 🪟 窗口管理 - 垂直/水平分屏、最大化，自动保存和恢复工作区布局
• ⌨️ Helix 风格键位 - 符合直觉的键盘快捷键，命令模式支持
• 🎯 多项目支持 - 全局项目 + 本地项目（.kanban/）
• 📝 编辑器集成 - 支持外部编辑器 (Vim/Neovim/VSCode/Helix 等)
• 🔍 Markdown 预览 - 内置预览和外部预览工具支持

安装

Homebrew (macOS/Linux) - 推荐

最简单的安装方式，自动下载预编译的二进制文件：

brew tap menzil/tap
brew install helix-kanban

预编译二进制文件

从 GitHub Releases 下载适合你系统的预编译版本：

macOS:

# Apple Silicon (M1/M2/M3)
curl -L https://github.com/menzil/helix-kanban/releases/latest/download/hxk-macos-aarch64.tar.gz | tar xz
sudo mv hxk-macos-aarch64 /usr/local/bin/hxk

# Intel
curl -L https://github.com/menzil/helix-kanban/releases/latest/download/hxk-macos-x86_64.tar.gz | tar xz
sudo mv hxk-macos-x86_64 /usr/local/bin/hxk

Linux:

# x86_64
curl -L https://github.com/menzil/helix-kanban/releases/latest/download/hxk-linux-x86_64.tar.gz | tar xz
sudo mv hxk-linux-x86_64 /usr/local/bin/hxk

# ARM64
curl -L https://github.com/menzil/helix-kanban/releases/latest/download/hxk-linux-aarch64.tar.gz | tar xz
sudo mv hxk-linux-aarch64 /usr/local/bin/hxk

Windows: 直接从 Releases 页面 下载 hxk-windows-x86_64.exe

从 crates.io 安装

如果你已经安装了 Rust 工具链：

cargo install helix-kanban --locked

💡 提示：使用 --locked 参数可以确保使用项目指定的依赖版本，避免版本冲突。

从源码构建

git clone https://github.com/menzil/helix-kanban.git
cd helix-kanban
cargo build --release

快速开始

首次运行会显示欢迎对话框，自动检测系统编辑器和 Markdown 预览器：

hxk

配置管理

查看当前配置：

hxk config show

设置编辑器：

hxk config editor nvim
hxk config editor "code --wait"

设置 Markdown 预览器：

hxk config viewer glow
hxk config viewer "open -a Marked 2"

MCP Server 集成 (AI 协作)

helix-kanban 内置了 MCP (Model Context Protocol) server，可以直接与 Claude Code 等 AI 工具集成。

配置

编辑 ~/.claude/settings.json:

{
  "mcpServers": {
    "helix-kanban": {
      "command": "hxk",
      "args": ["mcp"],
      "type": "stdio"
    }
  }
}

重启 Claude Code 后，AI 就可以直接操作你的看板了！

可用功能

AI 可以通过 MCP 协议：

• 📋 列出所有项目（带序号）
• 📝 查看和创建任务
• ✏️ 更新任务属性（标题、优先级、标签）
• 🔄 移动任务到不同状态
• 🗑️ 删除任务
• 📊 查看项目状态列
• 🚀 批量创建任务

性能优势

集成版本直接调用内部 API，比独立 MCP server 更快：

• ⚡ 启动速度：~5ms
• 💾 内存占用：~2MB
• 🔧 零配置：随 hxk 一起安装

详细文档：MCP-INTEGRATION.md

键位绑定

基础导航

任务操作

项目管理

窗口管理

状态管理

命令模式

按 : 进入命令模式，支持的命令：

• :q / :quit - 退出应用
• :open / :po - 打开项目
• :new / :pn - 创建新项目（全局）
• :new-local / :pnl - 创建新项目（本地）
• :add / :tn - 创建新任务
• :edit / :te - 编辑任务
• :view / :tv - 预览任务
• :reload / :r / :refresh - 重新加载当前项目
• :reload-all / :ra / :refresh-all - 重新加载所有项目
• :vsplit / :sv - 垂直分屏
• :hsplit / :sh - 水平分屏
• :maximize / :max - 最大化/恢复窗口
• :reset-layout - 重置窗口布局
• :help / :h - 显示帮助

数据存储

全局项目

全局项目存储在用户主目录下：

~/.kanban/projects/

本地项目

在任何目录下按 n 创建本地项目，会在当前目录的 .kanban/ 下存储：

your-project/
├── .kanban/
│   └── kanban-project/
│       ├── .kanban.toml
│       ├── todo/
│       ├── doing/
│       └── done/
└── ... (你的其他文件)

项目结构

project-name/
├── .kanban.toml          # 项目配置
├── todo/                 # Todo 任务
│   ├── 001.md
│   └── 002.md
├── doing/                # 进行中任务
│   └── 003.md
└── done/                 # 完成的任务
    └── 004.md

任务文件格式

任务以 Markdown 格式存储：

# 任务标题

created: 2025-12-10T10:30:00+08:00
priority: high

任务的详细描述内容...

## 子任务

- [ ] 子任务 1
- [x] 子任务 2

配置文件

应用配置存储在：

~/.kanban/config.toml

配置示例：

editor = "nvim"
markdown_viewer = "glow"

# 隐藏的全局项目列表（软删除）
hidden_projects = ["old-project", "archived-project"]

状态自动保存

应用会自动保存窗口布局和工作状态，下次启动时恢复：

保存内容：

• 分屏结构（垂直/水平分割）
• 每个面板打开的项目
• 当前选中的列和任务
• 聚焦的面板

保存位置：~/.kanban/state.json

使用场景：

• 经常需要同时查看多个项目？设置好分屏布局后，下次启动自动恢复
• 关闭应用后重新打开，无需重新配置窗口布局
• Space w m 最大化窗口专注单个项目，需要时快速恢复多窗口视图

开发

# 运行开发版本
cargo run

# 运行测试
cargo test

# 构建 release 版本
cargo build --release

致谢

• 键位设计灵感来自 Helix Editor
• UI 框架使用 ratatui

许可证

MIT OR Apache-2.0