Custom Fields Storage

Overview

Custom field data is stored separately from core beads issues in .beads/integrations/clickup/custom_fields.jsonl. This prevents bd CLI from overwriting ClickUp-specific metadata.

File Structure

.beads/
├── issues.jsonl                           # Core beads data
└── integrations/
    └── clickup/
        ├── config.yaml                    # Field definitions
        ├── custom_fields.jsonl            # Custom field data
        └── sync_state.jsonl               # Sync state

Data Format

custom_fields.jsonl (one line per issue):

{
  "issue_id": "bdclickup-abc",
  "custom_fields": {
    "lifecycle_stage": "Core Functionality UAT",
    "category": "Engineering",
    "effort": "Low"
  },
  "clickup_metadata": {
    "task_id": "86ewmwc4k",
    "task_url": "https://app.clickup.com/t/86ewmwc4k",
    "last_synced_at": "2026-02-17T14:22:07Z"
  }
}

Migration

If you have existing projects with custom_fields in issues.jsonl, run:

python scripts/migrate_custom_fields.py --project-dir . --remove

This extracts custom_fields from issues.jsonl and stores them in custom_fields.jsonl.

Usage

Via MCP tools:

# Create issue with custom fields
mcp__beads__bd_create({
    "title": "Fix authentication bug",
    "type": "bug",
    "priority": "p1",
    "lifecycle_stage": "Core Functionality UAT",
    "category": "Engineering"
})

# Update custom fields
mcp__beads__bd_update({
    "issue_id": "bdclickup-abc",
    "lifecycle_stage": "Integration"
})

Via bd CLI (custom fields preserved):

# bd CLI doesn't touch custom_fields.jsonl
bd update bdclickup-abc --status completed

# Custom fields remain intact

Field Name Normalization

Config files can have numbered prefixes for field ordering:

custom_fields:
  01_lifecycle_stage:
    clickup_field_id: abc-123
  02_category:
    clickup_field_id: def-456

When creating/updating issues, use normalized names (without prefixes):

mcp__beads__bd_create({
    "lifecycle_stage": "Core Functionality UAT",  # Not 01_lifecycle_stage
    "category": "Engineering"                      # Not 02_category
})

The FieldMapper automatically handles prefix normalization.