Linear

The Linear surface lets your team hand work to an agent without leaving Linear. Delegate an issue to the agent, or mention it in a comment, and the agent picks the issue up, reports progress inside the issue, and delivers its answer there. Behind the scenes each issue runs as a Brainbase task, so everything the agent does is also visible in the Brainbase app.

How it works

Connecting Linear installs a private Linear app that acts as a workspace agent. The app appears in Linear as its own user, so people can delegate issues to it, mention it, and read its updates the same way they would with a teammate.

1. You delegate or mention. Assigning the agent as an issue's delegate, or mentioning it in a comment, opens an agent session on that issue.
2. Brainbase starts a task. The issue's title, description, and the comment that triggered the session are sent to the agent as the first message of a Brainbase task. One issue maps to one task, so later sessions on the same issue continue the same conversation.
3. The agent works and reports. While it works, the session shows a running log of what the agent is doing. Tool calls appear as actions, and long-running steps post a short progress note so the session never looks stalled.
4. The answer lands in the issue. The agent's final response is posted into the session. If the agent needs something from you, it asks a question in the session and waits for your reply.

Before you start

• A Linear workspace admin. Creating a private app and authorizing it into a workspace are admin actions in Linear. If you are not an admin, have one with you for the setup steps.
• Access to the agent in Brainbase. You need to be able to edit the agent whose Surfaces you are configuring.

Connect Linear

Setup takes three steps and a few minutes. Open the agent, go to Surfaces, expand Linear, and choose Set up to open the Connect Linear page.

Step 1: Create the private app in Linear

1. Click Prepare the app. Brainbase generates an application manifest for this agent: the app's name and icon, the callback and webhook addresses Brainbase listens on, and the events the app subscribes to.
2. Click Open Linear's application form. Linear opens its new-application page with every field prefilled from the manifest.
3. Review the form and create the app. Nothing needs to be changed, but you can adjust the name or icon if you like. Linear does not allow the word *Linear* in an app name.

Step 2: Paste what Linear shows you

After the app is created, Linear shows three values: the Client ID, the Client secret, and the Webhook signing secret. Linear shows the two secrets only once, so copy them now. Paste all three into the matching fields on the Connect Linear page and click Save and authorize.

Step 3: Authorize the app into the workspace

Saving sends you to Linear's authorization screen. Approving it installs the app as a workspace agent with permission to read and write issues and to be assigned and mentioned. When Linear returns you to Brainbase, the surface shows Connected, awaiting the first webhook. The first event Linear sends for this agent, such as your first delegation, switches the status to Connected.

Working with the agent

Delegate an issue

Set the agent as the issue's delegate. The human assignee stays in place; delegation is how you tell the agent this issue is its job. If the issue is still in a backlog or to-do state, Brainbase moves it to your team's first in-progress state so the board reflects that work has started. Issues that are already in progress, done, or canceled keep their state.

Put the ask in the issue description. The description is the agent's brief, so a clear description with the expected outcome gives the best results. If you delegate an issue with an empty description, the agent asks you what you would like it to do.

Mention the agent

Mention the agent by name in a comment to give it an instruction without delegating the whole issue. A mention opens a session in that comment's thread, and the agent replies there. Mentions inside an existing discussion thread work too: the agent posts its answer in that thread so the people reading it see the reply, and in its own session.

Continue the conversation

• Reply in the session. Every session has a thread in the issue. Replying there sends a follow-up prompt; the agent picks it up with the full history of the issue's task.
• Send several prompts. Prompts are handled one at a time, in the order they were sent. If the agent is still working, your next prompt waits and runs as soon as the current turn finishes.
• Answer its questions. When the agent needs a decision or more detail, it asks in the session. Reply in the same thread to continue.
• Add context with ordinary comments. A comment that does not mention the agent is added to the conversation as context but does not start a run. The agent sees it the next time it works on the issue. Turn on Respond to every comment if you want every comment to start a run.

Pause and resume

Remove the agent as delegate to pause it on an issue. Work you already asked for finishes, and nothing new starts on that issue. Mention the agent again when you want it to continue; the same task and history carry over.

See the work in Brainbase

Each session carries an Open in Brainbase link to the task behind it. Use it to read the full transcript, inspect tool calls, or continue the conversation from the Brainbase app. Tasks created from Linear are titled with the issue identifier, so they are easy to find in the agent's task list.

What the agent can do in Linear

Connected agents get a built-in set of Linear tools. The tools work on any issue in a team the app can access, not only the issue that started the session, so you can ask the agent to look something up or leave a note elsewhere.

The agent cannot create, delete, or archive issues, and it cannot change team, workspace, or app settings. Every write it makes is attributed to the app in Linear, so the issue history always shows what the agent changed.

Settings

• Respond to every comment. Off by default. Delegations, mentions, and replies in a session always run the agent; ordinary comments are added as context. Turn this on to start a run for every human comment on a delegated issue.
• Generic Linear MCP. If the agent also has a generic Linear MCP server configured, the built-in Linear tools take over while the surface is connected, and the surface card tells you which server is being overridden. The generic server stays in the agent's configuration and is used again if you disconnect the surface.
• Disconnect. Removes the app from this agent and stops new work from Linear immediately. Run setup again at any time to reconnect.

Connection status

Best practices

• Write the issue description as the brief you would give a teammate, with the outcome you expect and any constraints.
• Keep one piece of work per issue. Each issue is its own conversation, so unrelated asks are easier to track as separate issues.
• Use the session thread for follow-ups so the agent has the history, and mention the agent from a discussion thread when the people in that thread need to see the answer.
• Ask the agent to move the issue to Done as part of the work if you want it to close the loop for you.
• Leave Respond to every comment off unless the agent should treat every comment as an instruction; mentions are the precise way to ask for something.
• Review the agent's instructions and tools before connecting a workspace where many people can delegate to it.

Troubleshooting