Basecamp 4 Assistant

Fulfill Basecamp requests by writing and executing Python code against BasecampClient.

Workflow

1. Locate config and client files
2. Initialize the client
3. Resolve project/resource names to IDs
4. Execute the request
5. Print clear output summarizing what was done or found

Step 1: Locate Files

Find basecamp_config.json — check in order:

1. basecamp_config.json (cwd)
2. basecamp_docs/basecamp_config.json
3. scripts/basecamp_config.json (skill repo bundled location)
4. Ask the user

Find basecamp_client.py — check in order:

1. Same directory as config
2. basecamp_client.py (cwd)
3. basecamp_docs/basecamp_client.py
4. scripts/basecamp_client.py (skill repo bundled location)
5. Ask the user

Step 2: Initialize

import sys, os, json

config_path = "<resolved_config_path>"
client_dir  = os.path.dirname(os.path.abspath("<resolved_client_path>"))

if client_dir not in sys.path:
    sys.path.insert(0, client_dir)

from basecamp_client import create_client_from_config

bc = create_client_from_config(config_path)

Step 3: Resolve Names to IDs

Users refer to projects by name. Always resolve:

projects = bc.get_projects()
project = next((p for p in projects if p["name"].lower() == "some name".lower()), None)
if not project:
    # Try partial match
    project = next((p for p in projects if "some name".lower() in p["name"].lower()), None)
project_id = project["id"]

Most tools require a dock-resolved tool ID. Use cached helpers:

todoset_id    = bc.get_todoset_id(project_id)
board_id      = bc.get_message_board_id(project_id)
vault_id      = bc.get_vault_id(project_id)
schedule_id   = bc.get_schedule_id(project_id)
chat_id       = bc.get_chat_id(project_id)
card_table_id = bc.get_card_table_id(project_id)

Finding a to-do list by name:

todoset_id = bc.get_todoset_id(project_id)
lists = bc.get_todolists(project_id, todoset_id)
target = next(l for l in lists if l["name"].lower() == "list name".lower())

Key Behaviors

• Pagination: All get_* list methods auto-paginate via Link headers. They return the complete list.
• Rich text: Message bodies, to-do descriptions, document content, and comments accept HTML (<strong>, <em>, <a href>, <ul>/<li>, <br>).
• Token refresh: The client auto-refreshes expired tokens on HTTP 401 and persists to config.
• Rate limits: The client auto-retries on HTTP 429 with Retry-After.
• update_todo WARNING: Omitting an optional param CLEARs its value. Always pass all fields you want to keep.
• Error handling: If a project or resource isn’t found, say so clearly rather than crashing.

API Reference

For the complete method listing with signatures, see references/api_reference.md.

Key categories: Projects, To-dos (sets/lists/groups/items), Messages (boards/types/comments), Documents & Vaults, Uploads & Attachments, Schedule Entries, Campfires & Chatbots, Card Tables (columns/cards/steps), People & Access, Questionnaires & Answers, Recordings, Subscriptions, Events, Webhooks, Templates, Client Features, Inboxes, Lineup Markers.