Local Development

Run agents and coordinate work locally without deploying to a ludus host.

Goal

Understand how to use the Beads CLI for work tracking, run agents in local mode, and test changes before deploying.

Prerequisites

• Completed Dev Setup
• bd CLI installed and working
• Ludus CLI installed (uv sync in ludus/)

Steps

1. Working with Beads locally

Initialize a beads database in any project:

cd your-project
bd init --prefix myproj

Create and manage work items

# Create a task
bd create --title="Implement feature X" --description="Details here" --type=task --priority=2

# List open work
bd list --status=open

# Find ready work (no blockers)
bd ready

# Claim a task (atomic — fails if already claimed)
bd update <id> --claim

# Close when done
bd close <id> --reason="Implemented and tested"

Work with dependencies

# Create dependent tasks
bd create --title="Write tests" --type=task --priority=2
bd dep add <test-id> <feature-id>    # Tests depend on feature

# Check what's blocked
bd blocked

# View dependency tree
bd dep tree <id>

View project status

bd stats                    # Overview of open/closed/in_progress
bd list --status=in_progress  # Active work
bd stale --days 7           # Stale items

2. Running agents locally

The Ludus CLI supports local mode for several commands:

cd meta/ludus

# Run the watcher locally (monitors beads, wakes agents)
uv run ludus run watcher --local

# Run the comments processor locally
uv run ludus run comm --local

# Run the issue closer locally
uv run ludus run close --local

Local mode skips SSH connections and runs directly against local repos.

3. Testing Ludus CLI changes

cd meta/ludus

# Run all tests
uv run pytest tests/ -v

# Run a specific test
uv run pytest tests/test_ludus_cli.py -v -k "test_status"

4. Testing Tabula changes

cd meta/tabula

# Dev server with hot reload
npm start

# Production build (catches broken links)
npm run build

# Serve the production build locally
npm run serve

tip

Always run npm run build before pushing — Tabula's onBrokenLinks: 'throw' setting means broken internal links will fail the build.

Validation

# Beads CLI works with your database
bd stats

# Ludus CLI tests pass
cd meta/ludus && uv run pytest tests/ -v

# Tabula builds cleanly
cd meta/tabula && npm run build

If Things Go Wrong

Problem	Solution
bd ready shows nothing	Check bd list --status=open — work may be blocked. Use bd blocked to see blockers.
Dolt corruption after concurrent access	Remove and reinitialize: delete .beads/dolt/, then bd init.
bd staleness errors	Force reimport: bd import --force -i .beads/issues.jsonl
Ludus tests fail on import	Ensure you ran uv sync recently. Check Python version ≥ 3.11.
Tabula build fails with broken links	Check the error output for the specific broken link. Fix the path or remove the link.