claude-os/docs/guides/REALTIME_KANBAN_GUIDE.md

Real-Time Kanban Board Guide

Overview

Claude OS features a real-time Kanban board that automatically syncs with your agent-os spec files as they're created and updated. This provides live visibility into your development progress without any manual intervention.

How It Works

The real-time Kanban system consists of three integrated components:

agent-os updates tasks.md
        ↓ (2 sec debounce)
Spec Watcher detects change
        ↓
Auto-syncs to database
        ↓ (within 3 seconds)
Kanban board auto-refreshes
        ↓
You see updated tasks in real-time! 🎉

1. Spec File Watcher

The Spec Watcher monitors your project's agent-os/specs/ folder for file changes:

• Watches: All tasks.md and spec.md files in your specs folders
• Triggers on: File modifications and new file/folder creation
• Debounce: 2-second delay to batch rapid changes
• Auto-starts: Launches automatically when MCP server starts

Technical Details:

• Location: app/core/spec_watcher.py
• Uses: watchdog library for filesystem monitoring
• Monitors: /path/to/project/agent-os/specs/**/*
• Thread-safe: Uses locks for concurrent access

2. Automatic Database Sync

When the spec watcher detects changes, it:

1. Parses the updated tasks.md file
2. Extracts tasks in checkbox format:

   - [x] 1.0 Complete database layer
   - [ ] 2.1 Write tests for services
   

3. Updates the SQLite database with new/modified tasks
4. Tracks task status (todo, in_progress, done, blocked)

Supported Task Formats:

The parser supports two formats:

Checkbox Format (recommended for agent-os):

- [x] 1.0 Complete database layer
  - [x] 1.1 Write 2-8 focused tests for database models
  - [x] 1.2 Create migration: add_manual_time_slots_support
- [ ] 2.0 Complete service layer
  - [ ] 2.1 Write 2-8 focused tests for services

Classic Format (legacy support):

### PHASE1-TASK1: Database Setup
**Title:** Setup Database Schema
**Description:** Create all required database tables
**Estimated Time:** 2 hours
**Risk Level:** low
**Status:** ✅ COMPLETED

3. Frontend Auto-Refresh

The Kanban board frontend:

• Polls: Every 3 seconds for database updates
• Refreshes: Automatically when new data is detected
• Smooth: Uses React Query for optimistic updates
• Animations: Framer Motion for smooth task transitions

Using the Kanban Board

Accessing the Board

1. Open Claude OS web interface
2. Select your project from the sidebar
3. Click the "Kanban Board" tab
4. Board loads automatically with all specs and tasks

Board Layout

The Kanban board displays:

Top Section:

• Summary statistics (total specs, total tasks, completed tasks)
• "Sync Specs" button (manual sync if needed)
• "Show Archived" toggle

Spec Cards: Each spec shows:

• Spec name and status
• Progress bar
• Task counts by status
• Four columns: Todo, In Progress, Done, Blocked

Task Cards:

• Task code (e.g., PHASE1-TASK1)
• Title
• Risk level badge
• Estimated/actual time
• Dependencies

Manual Sync Button

While the board updates automatically, you can manually trigger a sync:

1. Click "Sync Specs" button at the top
2. All spec files are re-parsed
3. Database updates immediately
4. Board refreshes within 3 seconds

Use this when:

• Testing the sync functionality
• Recovering from errors
• Adding a new spec folder manually

Configuration

Spec Watcher Management

The spec watcher starts automatically, but you can control it via API:

Start watcher for a project:

curl -X POST http://localhost:8051/api/spec-watcher/start/{project_id}

Stop watcher for a project:

curl -X POST http://localhost:8051/api/spec-watcher/stop/{project_id}

Start all project watchers:

curl -X POST http://localhost:8051/api/spec-watcher/start-all

Check watcher status:

curl http://localhost:8051/api/spec-watcher/status

Example status response:

{
  "status": {
    "enabled": true,
    "projects_watched": 1,
    "projects": {
      "1": {
        "project_path": "/Users/you/Projects/myapp",
        "specs_path": "/Users/you/Projects/myapp/agent-os/specs",
        "watching": true
      }
    }
  }
}

Adjusting Refresh Rate

The default refresh rate is 3 seconds. To change it:

File: frontend/src/components/KanbanBoard.tsx

const { data: kanbanData, isLoading } = useQuery({
  queryKey: ['kanban', projectId, includeArchived],
  queryFn: async () => {
    // ... fetch logic
  },
  refetchInterval: 3000, // Change this value (milliseconds)
});

Recommended values:

• 3000ms (3s): Real-time updates, good UX
• 5000ms (5s): Balanced performance
• 10000ms (10s): Low-traffic, battery-saving

Debounce Delay

The spec watcher waits 2 seconds after detecting a change before syncing. To adjust:

File: app/core/spec_watcher.py

class SpecFileHandler(FileSystemEventHandler):
    def __init__(self, project_id: int, project_path: str):
        # ...
        self.debounce_delay = 2.0  # Change this value (seconds)

Why debounce?

• Prevents sync spam during rapid file edits
• Batches related changes together
• Reduces database load

Project Structure Requirements

For the Kanban board to work, your project must have this structure:

your-project/
└── agent-os/
    └── specs/
        ├── 2025-10-29-feature-name/
        │   ├── spec.md          # Optional: Feature specification
        │   └── tasks.md         # Required: Task breakdown
        └── 2025-11-01-another-feature/
            ├── spec.md
            └── tasks.md

Folder naming convention:

• Format: YYYY-MM-DD-feature-slug
• Example: 2025-10-29-manual-appointment-times
• Slug becomes the spec name (spaces replace hyphens)

Troubleshooting

Tasks Not Showing Up

Check 1: Is the spec watcher running?

curl http://localhost:8051/api/spec-watcher/status

If "watching": false, restart the watcher:

curl -X POST http://localhost:8051/api/spec-watcher/start/{project_id}

Check 2: Are your tasks in the right format?

Tasks must use the checkbox format with numeric prefixes:

- [ ] 1.0 Task title
- [x] 2.1 Another task

Not this:

- [ ] Task without number
- Some random text

Check 3: Is tasks.md in the right location?

✅ project/agent-os/specs/2025-10-29-feature/tasks.md
❌ project/specs/tasks.md
❌ project/agent-os/tasks.md

Check 4: Check the MCP server logs

tail -50 logs/mcp_server.log

Look for:

• ✅ Updated spec 'Feature Name' with X tasks
• Any error messages about parsing

Board Not Auto-Refreshing

Check 1: Is polling enabled?

Open browser DevTools → Network tab → Filter by "kanban"

You should see requests every 3 seconds to:

GET /api/projects/1/kanban?include_archived=false

If not, check that React Query is configured correctly.

Check 2: Clear browser cache

Ctrl+Shift+R (Windows/Linux)
Cmd+Shift+R (Mac)

Check 3: Check frontend logs

Open browser Console and look for errors related to:

• React Query
• Axios requests
• WebSocket connections (if applicable)

Sync Taking Too Long

Expected timings:

• File change detected: < 1 second
• Debounce wait: 2 seconds
• Database sync: < 1 second
• Frontend refresh: 3 seconds
• Total: ~6 seconds max

If slower:

1. Check disk I/O (is your disk slow?)
2. Check database size (vacuum if needed):

   sqlite3 data/claude-os.db "VACUUM;"
   

3. Check CPU usage (spec parsing is CPU-intensive for large specs)

Parser Errors

Common issues:

Issue: "No tasks found"

• Cause: Tasks not in checkbox format
• Fix: Add - [ ] or - [x] before task lines

Issue: "Invalid task code"

• Cause: Missing numeric prefix (e.g., 1.0, 2.1)
• Fix: Add numbers: - [ ] 1.0 Task title

Issue: "Spec not found"

• Cause: Folder name doesn't match expected format
• Fix: Rename to YYYY-MM-DD-feature-name

Advanced Usage

Custom Task Status Updates

You can manually update task status via API:

curl -X PATCH http://localhost:8051/api/tasks/{task_id}/status \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress",
    "actual_minutes": 120
  }'

Valid statuses: todo, in_progress, done, blocked

Archiving Specs

Archive completed specs to declutter the board:

Via UI:

1. Click "Archive" button on spec card
2. Spec moves to archived view

Via API:

curl -X POST http://localhost:8051/api/specs/{spec_id}/archive

To view archived specs:

• Toggle "Show Archived" checkbox in the UI

Bulk Operations

Sync all specs for a project:

curl -X POST http://localhost:8051/api/projects/{project_id}/specs/sync

Response:

{
  "project_id": 1,
  "message": "Specs synced successfully",
  "synced": 0,
  "updated": 3,
  "total": 3,
  "errors": []
}

Performance Considerations

Database Size

Each task creates a database row. For large projects:

Estimate storage:

• 100 specs × 50 tasks = 5,000 rows
• SQLite handles this easily (millions of rows supported)

Optimize periodically:

sqlite3 data/claude-os.db "VACUUM; ANALYZE;"

Frontend Performance

With many tasks, the Kanban board may slow down:

Optimization tips:

1. Archive old specs (reduces rendered tasks)
2. Increase refresh interval to 5-10 seconds
3. Filter by status (show only active tasks)

File Watcher Overhead

The spec watcher uses minimal resources:

• CPU: < 1% idle, ~5% during sync
• Memory: ~20 MB per project
• Disk I/O: Only on file changes

Disable if needed:

curl -X POST http://localhost:8051/api/spec-watcher/stop/{project_id}

API Reference

See full API documentation in docs/API_REFERENCE.md

Key endpoints:

• GET /api/projects/{id}/kanban - Get Kanban data
• GET /api/projects/{id}/specs - List all specs
• POST /api/projects/{id}/specs/sync - Manual sync
• PATCH /api/tasks/{id}/status - Update task status
• POST /api/specs/{id}/archive - Archive spec
• GET /api/spec-watcher/status - Watcher status

Related Documentation

• What is Claude OS: docs/guides/WHAT_IS_CLAUDE_OS.md
• Session Workflow: docs/guides/IDEAL_SESSION_WORKFLOW.md
• API Reference: docs/API_REFERENCE.md
• Quick Start: docs/QUICK_START_CLAUDE_OS.md

Support

If you encounter issues:

1. Check the logs: tail -f logs/mcp_server.log
2. Check watcher status: curl http://localhost:8051/api/spec-watcher/status
3. Try manual sync: Click "Sync Specs" button
4. Restart MCP server: ./scripts/restart_mcp.sh
5. Open an issue: GitHub Issues