Connectors

Connectors let agents use selected external services from a channel. GitHub and Linear are read-only: agents cannot change a repository, create a ticket, or update an issue there. With Plane, an agent can file a work item for you without you leaving the conversation, change an existing one when you ask, and answer questions about Plane from Plane itself. With Google, an agent saves files from a conversation to Drive and reads and adds rows to the Sheets you choose. GitHub can also post updates in a channel when a pull request is merged.

A connection belongs to the workspace it was made in. If you are in more than one workspace, connecting GitHub, Linear, Plane or Google in one of them gives the others nothing: their agents cannot use it and cannot read its token. Disconnecting deletes the stored token along with the connection.

GitHub

Use GitHub when you want answers about code, pull requests, issues, releases, or recent shipped work in a repository.

Connect GitHub

1. Open Settings → Connectors.
2. Create a fine-grained GitHub personal access token with read-only access to Pull requests, Issues, Contents, and Metadata.
3. Paste the token and enter each repository as owner/repo, one per line.
4. Select Validate & Save.

The token is validated before Woodstock saves the connection. Agents can only read the repositories in this list. To change the list or remove access, disconnect GitHub and connect it again with the new scope.

Ask about GitHub

Before an agent can use GitHub's flexible reader, an owner opens Settings → Agents, selects the agent, and ticks github_read in its GitHub tools. Connecting GitHub does not grant this tool automatically. The three focused GitHub tools remain available separately.

Ask the Researcher in a channel, for example:

What shipped recently in tinkerslabs/woodstock?

Find the pull request that added the GitHub connector and summarize it.

List every pull request merged on 8 October, not just the most recently updated ones.

A pull request that merged is reported as merged, with its merge time. A pull request closed without merging stays closed, so questions such as “What merged most recently?” do not confuse an abandoned pull request with shipped work. Issues keep their ordinary open or closed state.

Available GitHub tools

• github_read — reads GitHub through its read-only tools for the approved repositories, including pull requests, issues, files, commits, branches, tags, releases, and Actions. It supports GitHub's own filters and pagination, so an agent can enumerate a whole date range instead of sampling a short recent list. It cannot write to GitHub or read a repository outside the connection's list.
• github_list_recent — lists recently updated pull requests and issues in the approved repositories.
• github_search_prs — searches approved repositories for a pull request or issue by keyword.
• github_get_pr — reads the title, state, description, and link for one pull request or issue.

Linear

Use Linear when you want to know what a team is working on, what is in progress, or which recent issues relate to a question.

Connect Linear

1. Open Settings → Connectors and select Connect Linear.
2. Authorize Woodstock in Linear.
3. Return to Woodstock, select I've authorized — continue, then choose the Linear teams the Researcher may read.
4. Select Save scope.

The connection only exposes recent issues from the selected teams. Disconnecting Linear removes that access.

Ask about Linear

Ask the Researcher in a channel, for example:

What is the team working on this week?

Show me the recent in-progress work for our product team.

Available Linear tool

• linear_list_recent — lists recently updated issues from the selected teams, including each issue’s identifier, title, state, and link.

Plane

Use Plane when something in a conversation should become a work item: a bug someone just hit, a screenshot of a broken screen, a request a teammate made in passing. You ask the agent in the channel, and the work item appears in Plane. You can also ask the agent what is happening in Plane, and it answers from Plane itself, or ask it to change a work item that already exists.

File a work item

In a channel, mention the agent and name the Plane project. Attach a screenshot if you have one:

@Marcie add this to BUG

The agent files the work item and answers with a link to it, for example:

Filed as BUG-123. Add it to Cycle 38 too?

The work item in Plane has:

• a title the agent writes from your message
• your note
• a line saying who asked and where, for example Asked by Somchai in #design via Woodstock
• the screenshot or files you pointed at, as attachments. They can be on your message or on an earlier message in the conversation

If a file cannot be attached, the work item is still filed and the agent tells you which file did not attach.

Add it to the current cycle

When the project has a cycle running today, the agent asks whether to add the work item to it. Reply to the agent's message (use Reply on it) with "yes", and the agent adds it and says so:

Added to Cycle 38.

Reply "no" to leave it out. A plain "yes" sent to the channel without replying to the agent's message, or without mentioning the agent, does not reach it.

Ask about Plane

An agent with Plane reading switched on (see Connect Plane, step 4) answers questions about Plane by reading it, for example:

@Marcie what's open in BUG?

@Marcie what's in the current cycle for CHAT?

@Marcie who has BUG-12?

@Marcie which Plane projects can you file into?

The answer comes from what Plane returned: work item titles, their states and assignees, and links to them in Plane. While it reads, the conversation shows each Plane lookup as a step. Reading works in direct messages and private channels too.

The agent reads with the same Plane account it files with, so it sees what that account can see in Plane. Reading never changes anything in Plane. Asked to change something, it says which of its tools can do that, or that none can.

Change a work item

An agent with Plane writing switched on (see Connect Plane, step 4) changes an existing work item when you ask, for example:

@Marcie rename BUG-12 to "Checkout button hidden on small phones"

@Marcie set BUG-12 to high priority and move it to In Progress

It looks the work item up in Plane first, then sends Plane the change, so it needs Plane reading switched on as well to find a work item by its identifier. There is no approval card: switching Plane writing on for an agent is the approval, so the change happens in the same turn. The conversation shows the lookup and the update as steps, and the reply links the work item so you can open it in Plane.

What it can change is whatever Plane's own update of a work item accepts: its title, description, state, priority, assignees, labels, start and target dates (including clearing a date), and the other fields Plane lets that action set. Only the fields you ask about are sent; everything else on the work item stays as it was. Assignees and labels are sent as the whole list, so "also assign Alice" keeps the people already assigned and adds her. It changes one work item per update and cannot delete one.

When it cannot make the change, it says so instead of claiming it did:

• you did not say which work item, or more than one matches: it asks which one you mean;
• Plane refused, for example because its account is only a Guest in that project: it says Plane refused and why, and nothing was changed;
• the answer from Plane was lost on the way back: it says it does not know whether the change landed, and reads the work item again before trying anything else. It never repeats a change on its own.

Each change is recorded in the channel's Activity as a Plane update the agent sent for you.

Which projects the agent can file into

The agent files into Plane as its own Plane account. That account can file into a project only when it is a Contributor or Admin there. It can see more projects than that: as a Guest it can read a project but not file into it.

To let the agent file into another project, have an admin of that project in Plane add the account as a Contributor. If the agent cannot file, it says why instead of trying again:

• you named a project the account cannot see: it says so and lists the ones it can;
• Plane refused for permission: it names the missing role and that a project admin can grant it. With Plane reading switched on, it checks which account it uses and that account's role in the project before it answers. You can also ask it "which Plane projects can you file into?" at any time.

Connect Plane (owner)

1. In Plane, sign in as the account the agent should use and create a personal access token in that workspace (Settings → API tokens).
2. In Woodstock, open Settings → Connectors, find Plane, and enter the Plane workspace slug (the part of the address after app.plane.so/) and the token.
3. Select Validate & Save. Woodstock checks the token with Plane before saving, then shows the projects the account can see. This list includes projects where the account is a Guest and cannot file.
4. Open Settings → Agents, choose the agent, and in its Plane group tick Plane File Work Item and Plane Add To Current Cycle for filing. Tick Plane Read separately to let it answer questions about Plane, and Plane Write (together with Plane Read) to let it change existing work items. Each is its own switch: Plane Read never lets an agent change anything, even when Plane Write is on. Connecting Plane ticks nothing for you.

The token is stored encrypted and never appears in a channel, a message, or what an agent reads.

If Plane refuses the agent

When Plane turns a request down, the agent tells you in plain words what Plane said, whether anything changed in Plane, and what to do next. For example:

I couldn't add this — Plane refused Woodstock's access (it said the token was invalid or expired). Nothing was changed in Plane. Say "retry" to try again; if it keeps failing, someone who can open Settings → Connectors can reconnect Plane.

• Access refused (the token is no longer accepted): ask again once; if it keeps happening, someone who can open Settings → Connectors disconnects Plane and connects it again with a new token.
• Can't reach that project or item: the Plane account Woodstock uses isn't a member there. A project admin in Plane can add it.
• Already there: Plane already has it; the agent reads it instead of sending it again.
• No clear answer (Plane timed out or failed on a change): the change may or may not have happened, so the agent checks before trying again.

The agent doesn't retry on its own. In How I worked, the refused step shows as failed with what Plane answered, like Plane refused: access rejected (401), and the refusal is kept with the run so it can be looked into later.

Available Plane tools

• plane_file_work_item — files a work item in a Plane project, with the files you point at attached.
• plane_add_to_current_cycle — adds a work item to its project's current cycle.
• plane_read — reads Plane: projects, work items, cycles, modules, members and their roles, comments, pages and the rest of what Plane lets its account read. It cannot change anything.
• plane_write — changes an existing work item through Plane's own update action, with the fields you asked to change. It cannot create, delete or do anything else in Plane.

What Plane cannot do yet

• No filing or changing in direct messages or private channels. Ask from a public channel. Reading works everywhere.
• Filing sets the title and description only. To set labels, assignees, priority or dates, ask the agent to change the work item after it is filed (needs Plane Write).
• Only work item updates. Deleting work items and other changes in Plane, such as comments, cycles beyond the current one, or pages, are not available.
• Anyone who can open Settings → Connectors can replace the token. The agent then files as whichever Plane account that token belongs to. Who may change a connection is on the roadmap.
• No updates from Plane yet. Changes made in Plane do not show up in a channel.
• Images attached to a work item cannot be read. The agent can list attachments and read text ones (notes, CSV, Markdown), but not pictures.
• Text in Plane reaches the agent as written. A comment or page in Plane could contain instructions aimed at the agent. Switch reading on for agents you trust with what that Plane account can see; a protection that keeps outside text from steering an agent is on the roadmap.

Google Drive and Sheets

Connect the team's Google account once and choose the files and folders the team works in. After that, anyone in the channel can ask the agent to save a file to Drive or work in one of those Sheets, and it is done in Google.

Connect Google from a channel

1. In a channel, ask the agent to connect:

   @Marcie connect our Google

   The agent posts a Connect Google card: Marcie will be able to read and add to only the Google files you choose. The agent also posts this card on its own when you ask for Google work before Google is connected.

2. Tap Connect Google. Whoever taps is the one connecting. Google opens in a new tab and asks you to allow See, edit, create, and delete only the specific Google Drive files you use with this app. That is the only permission Woodstock asks for: it cannot see the rest of your Drive.

3. Right after you allow it, the tab says Connected as finance@acme.co and closes, and Google's file picker opens over Woodstock. Browse it as you would Drive — My Drive folder by folder, Shared with me or shared drives — or search. Choose any files the agent should use and, if you want files saved somewhere specific, folders. If the tab stays open, close it and go back to Woodstock.

4. The card turns into Connected as finance@acme.co · Claims, Receipts 2026, and a short Google update in the same thread tells everyone in the channel. Tap Choose files on that card any time to add more; the picker opens right there, with no new tab.

Ask again once the card says connected: the agent does not yet carry on with your earlier request by itself (see What Google cannot do yet).

Choose which agents can use Google

Connecting ticks nothing for you. Open Settings → Agents, choose the agent, and in its Google group tick the switches it should have:

• Google Sheets Read — read the values in the Sheets the connection reaches.
• Google Sheets Write — add rows to those Sheets.
• Google Drive Read — look up a file or folder the connection reaches.
• Google Drive Write — save files from the conversation to Drive.

Save a file to Drive

Attach a file, or point at one already in the conversation, and ask:

@Marcie save this receipt to Drive, in Receipts 2026

The file lands in that folder with its own name, and the agent replies with the file's name as a link to it in Drive. Without a folder, it goes to My Drive.

Work in a Sheet

@Marcie what's in the Claims sheet?

@Marcie add it to the Claims sheet: 14 Oct, taxi, ฿240

The agent reads the cell values from Google, or appends one row and says where it went (for example Claims!A12:C12). The channel's activity shows each saved file and each added row.

What the agent can reach

Only the files someone chose in the picker for this workspace's connection, and the files the agent created through it. Asked about anything else, the agent says so before contacting Google and lists what it can reach:

I can't reach Travel 2026 yet. I can reach: Claims, Receipts 2026.

It comes with a Choose files card that opens the same picker in place, so you can add the file. This holds even when the same Google account is connected in two workspaces: each workspace reaches only its own choices.

Signed out and disconnecting

If Google stops accepting the sign-in (someone removed Woodstock's access in their Google account, for example), the agent says Google signed this connection out and posts a Connect Google card. Tap Connect again on it and sign in; the same account keeps the files it had chosen.

To end the connection, ask:

@Marcie disconnect Google

and tap Disconnect on the card. Woodstock deletes its stored sign-in and the files chosen for this workspace; connecting again starts with no files chosen. Other workspaces connected to the same Google account keep working. To remove Woodstock from your Google account altogether, for every workspace at once, use your Google Account's Security → Third-party apps & services.

Available Google tools

• google_sheets_read — reads a Sheet's tabs and cell values.
• google_sheets_write — appends rows to a Sheet.
• google_drive_read — looks up a file's or folder's details.
• google_drive_write — saves a file from the conversation to Drive.

What Google cannot do yet

• The agent doesn't carry on by itself after you connect. Ask again once the card says connected. Picking up the original request is on the roadmap.
• Files already inside a chosen folder are not reachable. Choosing a folder lets the agent save into it; to read a Sheet, open the folder in the picker and choose that Sheet itself.
• The agent reads Sheets only. You can choose a document, a PDF or any other file, and the agent sees its name and details, but reading what is inside one is on the roadmap.
• Connect from a channel only. A Google card in Settings → Connectors is on the roadmap.
• Connect from a browser, not the phone app. Google allows neither signing in nor its file picker inside an app; connecting and choosing files from the phone app is on the roadmap.
• Disconnecting doesn't remove Woodstock from your Google account. It ends the connection in Woodstock only; removing Woodstock in your Google Account settings ends it everywhere.
• No Gmail, Calendar or Google Docs yet.
• Each member's own Google is not supported. One Google account per workspace.
• Any member can choose files. The picker browses the Drive of the Google account that connected, so every member of the workspace sees that Drive's file names while choosing. Limiting Choose files to the member who connected is on the roadmap.

Updates from GitHub

When a pull request is merged in our GitHub organization, a short update shows up by itself in the channel it was set up for. Nobody has to ask an agent or open GitHub. When an automated run (GitHub Actions) fails on a repository's main branch, an update says so too, and another says when it is fixed. See Failed and fixed runs.

The update is posted by GitHub and shows:

• Merged and the repository, for example tinkerslabs/woodstock
• the pull request's title. Select the title to open the pull request on GitHub
• the pull request number, who opened it (their GitHub name, including bots) and when it was merged, in your local time

An update is marked unread like any other message, so the channel's unread dot lights up for everyone who is not looking at it. It does not buzz anyone's phone, it does not wake an agent, and it is not copied to Discord. If you ask an agent about it later, the agent can read it in the channel like any other message.

Failed and fixed runs

When a GitHub Actions run fails on a repository's default branch (usually main), GitHub posts an update in the same channel as the merged pull requests:

• Failed in red, with the repository
• the workflow's name, for example CI & Deploy. Select it to open the failed run on GitHub
• the run number, the branch, what started the run (usually the merge's title), who started it, and when it failed

Later failures of the same workflow post nothing more, so a run that keeps failing does not fill the channel. When that workflow passes on the branch again, a Fixed update in green follows, linking the passing run. Scheduled runs count too, so a nightly job that fails on main shows up.

Runs on other branches and on pull requests never post, and neither do cancelled runs: they fail all the time while people work. A passing run posts nothing unless the channel showed that workflow failing. Like a merged pull request, a failed run does not buzz anyone's phone and does not wake an agent.

Which channel gets which updates

Each update stream sends merged pull requests, failed runs, or both to one channel. One GitHub connection can have several streams, for example merges in the app repository to #project-woodstock and merges in the website repository to #marketing. A stream can name its repositories or cover every repository in the organization. Pull requests that are closed without merging, or merged in a repository no stream covers, do not show up.

What updates cannot do yet

• A merge that happens while Woodstock is down is not shown. GitHub does not retry, so the owner can re-send it by hand from GitHub's Recent Deliveries list.
• Streams are set up by the workspace owner by hand. Choosing a stream's channel and repositories in Settings is on the roadmap, and so is connecting GitHub in one click.
• A failed run that happens while Woodstock is down can go unnoticed. The next passing run then has no failure to fix, so it posts nothing either. Re-send the failed run from GitHub's Recent Deliveries list to show it.
• A late, older run can say Fixed or Failed at the wrong moment. If a newer run already failed without posting (because the workflow was already failing), an older run passing afterwards still posts Fixed. The same holds the other way round: an older run that times out after a newer one passed posts Failed until the next pass. Runs on one branch rarely finish out of order.
• Failed runs name the workflow, not the job. Open the run to see which step failed.
• Merged pull requests and failed runs only. Other GitHub events and Plane updates are on the roadmap. Failed runs work for organizations whose webhook Woodstock's operator sets up; any organization will work once GitHub connects in one click.

Owner setup

Some of this is done once for Woodstock, and some once per channel.

Once for Woodstock. The GitHub side is one pipe from the organization into Woodstock, shared by every workspace:

1. Create the shared secret and store it on the server: add GITHUB_WEBHOOK_SECRET to .env.staging (for example the output of openssl rand -hex 32), then run pnpm api:secrets --only GITHUB_WEBHOOK_SECRET. Do this before the release that brings updates.
2. After that release, apply the database change with pnpm db:push.
3. In GitHub, open the organization's Settings → Webhooks → Add webhook. Set Payload URL to https://<API host>/connectors/github/events, Content type to application/json, and Secret to the value from step 1. Choose Let me select individual events, select Pull requests, and (for failed runs) Workflow runs, and save.

Once per channel, in any workspace. Write one update stream in the database. Each stream names the organization, its repositories and the channel, so only the workspace owner decides which organization's updates reach which channel. The steps and SQL are in the build spec's human steps (docs/domains/connectors/updates/v1-merged-prs-show-up-in-a-channel.md, H2b for a workspace that already has a GitHub connection, H2c for one that does not). Then merge a pull request and check that the update appears in the channel.

Failed runs in a channel that already gets merges. Add one value to that channel's stream, then read the row back and check both values are there:

update update_streams
   set filter = jsonb_set(filter, '{events}', (filter->'events') || '"workflow_run_failures"')
 where id = '<stream id>' and not (filter->'events' ? 'workflow_run_failures');
select id, filter from update_streams where id = '<stream id>';

A stream carries failed runs only when its events list includes workflow_run_failures, and only for the repositories the stream names.

Adding a second workspace does not need a second webhook: one merge shows up in every channel whose stream covers its repository, in every workspace, at the same time. Everyone in the channel sees the pull request titles, even from a private repository — give a stream to a workspace only when its members may see that repository.

When GitHub connects in one click (on the roadmap), the pipe belongs to Woodstock's GitHub app: connecting approves it, and nobody opens a GitHub webhook page again.

What is not available yet

Slack and Notion are not connected to Woodstock yet. Agents cannot write back to GitHub or Linear; Plane and Google are the connectors an agent can write to.

Once connected, ask an agent about information in that approved source from a channel.