/basecamp-connect

name: basecamp-connect
description: |
  Drive your own Claude Code session from Basecamp: run the local connector,
  acknowledge trusted requests, and delegate work to background subagents
  that reply in Basecamp. Use when asked to connect an agent to this computer,
  drive agents from Basecamp, watch for mentions, assignments, pings, comments,
  or boosts, start or stop the connector, check its status or health, or change
  who may give the agent work and which projects it serves. Covers credentials
  (basecamp auth agent connect), permissions and projects (basecamp connect
  setup), status, and doctor. Watching the connector from a session requires
  Claude Code; from Codex or Pi, or to keep the agent working with no session
  open, the connector runs the work itself on Claude Code, Codex or Pi.
triggers:
  - /basecamp-connect
  - connect an agent
  - drive agents from basecamp
  - watch basecamp for agent commands
  - start the connector
  - stop the connector
  - is the connector running
  - set up the connector
  - basecamp connect setup
  - basecamp auth agent connect
  - serve a project
  - who can give the agent work
  - connector not ready
  - basecamp connect status
  - basecamp connect doctor
  - keep my agent running
  - run the connector without a session

/basecamp-connect: drive your agent from Basecamp

Someone @mentions the agent in Basecamp, assigns it a card or to-do, or pings it. This session acknowledges it as the agent within seconds, a background subagent does the work in the right repo with your own Claude Code setup, and the agent replies in place.

Three pieces:

• **The agent**: a Basecamp person of its own, owned by you, connected to this

computer under a CLI profile (often named after the agent).

• **The connector**: `basecamp connect -P '<profile>'`. It listens to the

account's event feed as the agent, checks each event against who may give the agent work and which projects it serves, and prints one line per trusted request. It boosts each one that asks for something first, and does nothing else.

• **This session**: the orchestrator. It watches those lines, words each

acknowledgement, chooses the repo, and dispatches one background subagent per request. It never does the work itself.

This flow needs Claude Code. Without it, or with no session open, see *Without this session*. The connector runs on Linux and macOS.

Running the connector

1. Start it, and watch its output

One connector per profile can run in this state directory. If another holds its lock, it refuses: tell the person, and don't start a second.

Start it in the background with the Bash tool (`run_in_background: true`), and note the output file the harness reports:

basecamp connect -P '<profile>'

It runs until stopped, from any folder. After a few seconds its log should say `connector: running`. If it exited instead, explain the error (see *When the connector stops*), and stop. If it says `could not get the agent's token yet`, Basecamp's token endpoint is limiting it or failing: it retries on its own. Tell the person, leave it running, and arm the monitor; restarting doesn't help.

Then arm a persistent monitor on that file with the Monitor tool (`persistent: true`), replaying from the start so nothing that arrived between the start and the monitor is missed:

tail -f -n +1 '<connector-output-file>' | grep --line-buffered -F '"type":"request"'

Single-quote the path, as with every other value.

Each notification is one request: handle it with *For each request*. A request that arrives while you're waiting on the person is not their reply.

2. The request line

{"type":"request","event_id":123,"event_type":"comment_created","trigger":"mentioned",
 "recording":{"bucket_id":456,"project_name":"BC5 Calendar","recording_id":789,"type":"Comment",
              "title":"Fix the date picker","url":"https://3.basecamp.com/999/buckets/456/recordings/789"},
 "reply_to":{"kind":"comment","recording_id":700},
 "requester_id":1001,"requester_name":"Jorge Manrubia","role":"operator","owner":true,"ping":false,"acknowledge":false,
 "go":false,"ask":{"title":"","content":""},"ack":{"boost_id":555,"content":"👀"},
 "content":"<p>fix the date picker</p>","content_updated_at":"..."}

• **`trigger`**: why it reached you.
• `mentioned`: someone @mentioned the agent.
• `assigned`: the operator, or someone they opted in, assigned it a card,

to-do or step. Only when the recording's events show this assignment added the agent, and the agent is still assigned.

• `subscribed`: a new comment on a thread the agent follows, with no mention.
• `completed`: something completed in a project it watches.
• `boosted`: a boost on the agent's own post.
• `pinged`: an operator wrote to it in a direct Ping.
• `campfire`: a trusted person wrote in a Campfire configured to hear

messages without mentions. The message is a request, like a Ping.

• **`acknowledge`**: true when a person asked for something and it isn't yet

acknowledged. False for `subscribed`, `completed` and `boosted`, context unless a `go`, and when `ack` is on the line.

• **`ack`**: the connector's boost on the recording, when it gave one.
• **`recording`**: what the event is about. `bucket_id` is the project,

`project_name` its name. `url` works with every command below.

• **`ping`**: true for a line in a Ping, a private chat in no project;

`bucket_id` is the Ping.

• **`reply_to`**: where the answer goes. `kind` `comment` means a comment on

`recording_id` (already chosen for you). `kind` `chat_line` means a line in the Campfire `recording_id`.

• **`requester_id`**: the person who asked. Mention them on failure, except in

Campfire. `requester_name` is their name when they wrote the recording.

• **`role`**: `operator` (the operator, or someone named with `--allow`) or

`participant` (a project member admitted by `--trust project`, or a person let into this Pi