Beads-Kanban: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a VS Code extension that provides a Kanban board interface for issues stored in a .beads SQLite database. The extension uses the bd CLI daemon for all database operations, providing efficient incremental loading and real-time updates. The board uses column-based loading to keep large databases (10,000+ issues) responsive.

Development Commands

Build and Watch

• npm run compile - Compile TypeScript and copy assets (DOMPurify)
• npm run watch - Watch mode for development
• npm run lint - Run ESLint on TypeScript files

Packaging the Extension

IMPORTANT: Use PowerShell for packaging on Windows

Git Bash has issues running vsce package (silent failures with no output). Always use PowerShell:

# In PowerShell (not Git Bash)
vsce package

This will:

1. Run vscode:prepublish script (which runs npm run compile)
2. Compile TypeScript, copy dependencies, and build webview bundle
3. Create beads-kanban-{version}.vsix file

Common Issues:

• If packaging fails silently in Git Bash, switch to PowerShell
• Ensure you've run npm run compile successfully before packaging
• Check that all TypeScript files compile without errors (tsc -p .)

Code Quality

The project uses ESLint with strict TypeScript rules:

• .eslintrc.json contains project-specific configuration
• Test files (.test.ts and files in test/) have relaxed rules (allow any types)
• All source code must pass npm run lint with no errors
• Use unknown type instead of any in production code, with proper type assertions

Type Safety Patterns:

When replacing any types with unknown for ESLint compliance:

1. CLI Result Handling: Cast results from execBd() to expected types:

   const result = await this.execBd(['info', '--json']);
   const info = result as { daemon_connected?: boolean } | null;