Dirban

Zero-database, folder-based Kanban board for builders, knowledge workers, and AI agents.

Dirban (Directory + Kanban) tracks task state using plain directories and Markdown files. It is designed for solo builders, knowledge workers, and AI agents (Cursor, Claude Code, Antigravity, Obsidian).

The physical directory is the task state. Moving a task between stages is just moving a file (mv).

• Directories as Columns: Workflow stages are plain folders (01-todo/, 02-doing/, 03-done/).
• Customizable Workflows: Tailor column names, staging pipelines, and priority tiers to your exact workflow using .dirban.json.
• Isolated Task Files: Each task is a self-contained Markdown file with an optional priority and checklist (- [ ]). Editing one task never collides with another in Git or file sync.
• Agent-Ready & Context-Efficient: AI tools and scripts read only the active task file (dirban current), keeping token usage low and focus sharp.
• Git is Completely Optional: While Dirban automates Git branching and worktrees for developers, it works equally well on plain folders (branchStrategy: "none") in Obsidian vaults, Dropbox, or local drives.
• Built for Fast Iteration: Cloud tools assume sprint cycles measured in weeks. Autonomous agents iterate in minutes. Dirban keeps pace without browser tabs, OAuth tokens, or sync delays.
• 100% Local & Future-Proof: Your data is just plain files. If you ever uninstall Dirban, your tasks remain standard Markdown notes readable in any text editor.

# Install globally via Bun or npm:
bun add -g dirban
# or: npm install -g dirban

# Or run instantly without installing:
# npx dirban init

(Alternatively, download a standalone prebuilt binary from GitHub Releases or build locally via bun link.)

# Run inside any repository, vault, or folder:
dirban init

This creates a lightweight task hierarchy under docs/tasks/:

docs/tasks/
├── backlog/       # Staging and future ideas
├── 01-todo/       # Ready to be picked up
├── 02-doing/      # Actively executing tasks (human or AI agent)
├── 03-done/       # Completed tasks
└── archive/       # Historical archive

# Create a new task with auto-assigned sequential ID
dirban new "Implement search filtering" --priority=p1

# Pick up and start work (moves to 02-doing/ & creates Git branch)
dirban start 26-001

# Inspect active task, branch alignment, and criteria checklist
dirban current

# Complete task (moves to 03-done/ and squashes branch)
dirban done

Work from the terminal or directly inside your editor:

# Launch interactive terminal Kanban board
dirban board

# Or print static board to stdout (ideal for CI, scripts, and piping)
dirban board --static

• Install directly in VS Code, VSCodium, Cursor, or Gitpod: Search for Dirban (syip.dirban-vscode).
• Focus View: Pinned sidebar panel showing the currently active task, branch alignment, and interactive checklist.
• Status Bar Indicator: Real-time status badge ($(checklist) 26-001 [2/5]) linking directly to the active task.
• Embedded Webview Kanban Board: Visual drag-and-drop Kanban board running natively inside an editor tab.

Dirban maps directly to the questions developers and AI agents ask when executing work:

Want to know what happens under the hood?
Every command maps to simple POSIX filesystem commands (mv, ls, cat) and standard Git operations. See Forget About Dirban: Zero Lock-In & Plain Shell Equivalents for the complete command-by-command mapping.

• 📋 Technical Specification & Standards (spec.md): Google OKF schemas, trunk-based branching, state precedence, and engine invariants.
• 📖 Why Dirban: Philosophy & Comparative Positioning: Fast agent cycles (minutes) vs cloud tools (weeks), comparison matrix, and trade-offs.
• ⚙️ Configuration Guide (.dirban.json): Custom columns, workflows, semantic priorities, and Git worktrees.
• 💻 CLI & TUI Reference Manual: Full command reference, options, and keyboard shortcuts.
• 🌿 Trunk-Based Git Workflow: Git branch automation, worktree isolation, and squash merging.
• 🐚 Forget About Dirban: Complete mapping of every Dirban command to raw POSIX shell (ls, mv, cat).

Dirban is under active development. Current focus areas:

• Enhanced Planning Mode (dirban plan): Smarter dependency graph visualization, multi-task batch promotions, and automated unblocking rules.
• Archive & History Search (dirban archive): Full-text searching across historical tasks, completed date indexing, and archival export options.

Feedback, bug reports, and suggestions are welcome on GitHub Discussions and Issues.

If you find Dirban useful, you can support its development:

MIT