Configuration Reference¶

config.yaml¶

Place at .beads/integrations/clickup/config.yaml in each project that uses the integration.

Security: Never put your API token in this file. Set CLICKUP_API_TOKEN in your project's .env.

clickup¶

ClickUp connection settings.

Key	Required	Description
`mcp_server_url`	No	ClickUp MCP endpoint. Default: `https://mcp.clickup.com/mcp`
`workspace_id`	Yes	Your ClickUp workspace/team ID
`default_list_id`	Yes	Target ClickUp list. Set by `bd clickup setup`.

sync¶

Controls what and how to sync.

Key	Default	Description
`enabled`	`true`	Enable/disable all sync
`direction`	`bidirectional`	`bd-to-clickup`, `clickup-to-bd`, or `bidirectional`
`auto_create`	`true`	Create ClickUp tasks for new bd issues
`auto_update`	`true`	Update ClickUp tasks when bd issues change
`auto_sync_from_clickup`	`true`	Pull ClickUp changes back to bd
`require_pr_approval`	`false`	Gate `bd close` on merged GitHub PR (MCP only)
`poll_interval`	`300`	Seconds between ClickUp polls. `0` disables polling.
`sync_dependencies`	`true`	Sync issue dependencies to ClickUp

dependencies¶

Maps bd dependency types to ClickUp relationship types.

bd type	ClickUp type	Notes
`blocks`	`depends_on`	A blocks B → B depends_on A
`related`	`dependency_of`	Loose bidirectional coupling
`discovered-from`	`dependency_of`	Optional, often noisy
`parent-child`	`subtask`	Uses ClickUp subtask API

field_mapping¶

Maps bd field values to ClickUp equivalents.

Status mapping — keys are bd statuses, values are exact ClickUp status names (case-sensitive, must match your list):

field_mapping:
  status:
    open: "to do"
    in_progress: "in progress"
    completed: "completed"

Priority mapping — bd uses P0–P4, ClickUp uses 1 (Urgent) – 4 (Low):

  priority:
    p0: 1  # Urgent
    p1: 2  # High
    p2: 3  # Normal
    p3: 4  # Low
    p4: 4  # Low

filters¶

Control which issues are synced.

Key	Default	Description
`sync_labels`	`[]`	Only sync issues with these labels (empty = all)
`exclude_labels`	`["no-sync"]`	Never sync issues with these labels
`sync_priorities`	`[]`	Only sync these priorities (empty = all)
`sync_types`	`[]`	Only sync these issue types (empty = all)

conflict_resolution¶

Key	Default	Description
`strategy`	`last-write-wins`	Also: `bd-priority`, `clickup-priority`, `manual`
`conflicts_file`	`.beads/.../conflicts.jsonl`	Used when strategy is `manual`

advanced¶

Key	Default	Description
`sync_hierarchical`	`true`	Sync parent-child as ClickUp subtasks
`sync_comments`	`true`	Bidirectional comment sync
`batch_size`	`50`	Max tasks per sync batch
`max_retries`	`3`	Retry attempts for failed API calls
`retry_delay`	`5`	Seconds between retries

visualization¶

Controls the task graph feature (bd clickup graph).

Key	Default	Description
`auto_classify_stages`	`true`	Use LLM to classify tasks into lifecycle stages
`llm_provider`	`openai`	`openai` or `anthropic`
`llm_model`	`gpt-4o-mini`	Model for classification
`classification_cache`	`true`	Cache results to minimise API cost
`cache_ttl_days`	`30`	Cache lifetime in days

github¶

Key	Default	Description
`api_token`	`""`	GitHub token (or set `GITHUB_TOKEN` env var)
`poll_prs`	`true`	Auto-complete tasks when PR is approved

Full example¶

# .beads/integrations/clickup/config.yaml
clickup:
  workspace_id: "9018124630"
  default_list_id: ""   # set by bd clickup setup

sync:
  enabled: true
  direction: "bidirectional"
  require_pr_approval: false
  poll_interval: 300

field_mapping:
  status:
    open: "to do"
    in_progress: "in progress"
    completed: "completed"
  priority:
    p0: 1
    p1: 2
    p2: 3
    p3: 4
    p4: 4

filters:
  exclude_labels: ["no-sync"]

conflict_resolution:
  strategy: "last-write-wins"

visualization:
  auto_classify_stages: true
  llm_provider: "openai"
  llm_model: "gpt-4o-mini"

templates.yaml¶

Place at .beads/templates.yaml in each project.

Controls the structure of issue descriptions created by bd create.

How it works¶

Each key under template: becomes a bold section header in the issue description:

objective → **Objective:**
plan → **Plan:**
definition_of_done → **Definition of Done:**
testing_plan → **Testing/Evaluation Plan:**
results → **Results:** (auto-appended as TBD if omitted)
Any other key is title-cased: my_section → **My Section:**

The placeholder [title] is replaced with the issue title at creation time.

Full example¶

# .beads/templates.yaml
template:
  objective: "[title]"
  plan: |
    1. Step one
    2. Step two
    3. Step three
  definition_of_done: |
    - [ ] Acceptance criterion 1
    - [ ] Acceptance criterion 2
    - [ ] Acceptance criterion 3
  testing_plan: "Manual verification"
  # results is auto-appended as "TBD" if omitted

Custom sections¶

Add any key you want:

template:
  objective: "[title]"
  background: "Context goes here."
  dependencies: "None"
  plan: |
    1. Step one
  definition_of_done: |
    - [ ] Done