Building the Bucket Linear Agent

We’re on a mission to enable developers to ship quality features faster. A key part is making the work around building those features frictionless, and one way we’re doing that is by deeply integrating with the tools you use.

Recently, we shipped Bucket MCP, so you can flag features directly from your code editor. As well as Bucketbot for GitHub to automatically clean up flags for you. We’d also started work on a Linear integration when they announced their Agents platform. So we jumped at the chance to join their beta.

Linear for Agents turns AI into teammates, so you can assign an agent to issues, mention them in comments, and collaborate on projects together. For Bucket, that means we could build an agent to create and manage feature flags for you from within Linear. So we did.

The resulting agent can create a feature key on Bucket from a comment on an issue in Linear. And if you want to change who can access that feature, it can do that for you, too.

The goal with the Bucket agent was to create an experience that feels native to working in Linear, complementing its workflows and interaction patterns. Here’s how we built it, and the lessons we learned that you can apply when building your own Linear agent.

How Linear Agents work

Agents are designed to work much like other users in a Linear workspace. You can @-mention them, as well as assign them issues, they can create and reply to comments, and collaborate on projects and documents. Agents can be used for internal use only or used by others in their workspaces via the Linear integrations directory. 

To create an agent, you make a new Application on Linear like you would for any OAuth app. But in the configuration, make sure to enable webhooks as well as Inbox notifications. This will notify your webhook when events happen relevant to the app's user. The name you set is what folks will use to interact with your agent, so set something that’s short and memorable. We kept it simple: @bucket.

Depending on your agent’s functionality, you may need to enable the app:assignable or app:mentionable permission scopes, so that you can assign and @-mention your agent.

Linear agents are installed into workspaces, so you need to keep track of the unique ID for each workspace it is installed in. For Bucket, we also needed to know which app in Bucket a user is using the agent with, so we added a dropdown menu for users to specify the default app.

Tasking and interacting with an agent is handled with webhooks. The inbox notifications webhook provides the key info you need, like user and org IDs, as well as notification type. These are triggered by events, such as mentions, emoji reactions, new comments, and when an agent is assigned something.

Making agent interactions⁠ feel natural

Linear promotes agents as ‘artificial teammates, natural collaboration,’ and they worked with us to ensure that working with our agent felt less like working with a bot and more like a co-worker. To that end, Linear recommends:

• Immediately acknowledging when an agent has been interacted with.
• Always responding when work is complete with a comment or reply to the original user.

However, Linear Agents doesn’t currently have a built-in affordance to signal that an agent is working. When a request to create a feature flag comes in, for example, it can take a few seconds for the Bucket agent to do the work of creating the flag and letting the user know. So that folks know something is happening, we chose to show a thought balloon emoji (💭) while a request is being worked on, removing it once it’s done.

Another thing we had to think through was how to know when a user wanted to interact with the agent. @-mentions are useful, but we all forget to use them consistently when messaging with co-workers. We expect the same to happen with agents, too, and it still needs to work anyway. So, instead of requiring a mention, after the initial request, we listen to issueNewComment notifications and determine whether an agent response is needed.

We needed to make sure that flags don’t accidentally get enabled or edited if the LLM got confused. So we implemented a confirmation check for key changes, like changing flag access rules. To make this as seamless as possible, you can add a comment to accept a change or react to the agent’s request with an emoji, like ✅ and 👍. We also trigger notifications using the Linear API resulting from the agent’s changes, so that team mates are kept up to date, too.

Let the flags flow

With the agent setup and interactions being handled in response to webhooks, hooking things up with Bucket itself was quite straightforward. Since we’d already built the Bucket MCP server, we added a handler in Bucket to grab the key info from the webhook and call an OpenAPI LLM with our MCP tools registered, which works much like our CLI MCP.

As ever, when working with LLMs, the tricky part is getting the LLM to do the thing you want it to reliably. Given its non-deterministic nature, we needed to refine our prompts and tweak the context provided to get it to understand requests and respond appropriately and consistently. This has a big impact on the experience of using the agent. Things like:

• Getting it to use proper names for IDs and structuring responses
• Outputting features as a table rather than a list
• Formatting key info in code marks

These, as well as using informal language in responses, all help to make it more useful and less robotic.

Linear is well-placed to help automate every part of the product development lifecycle – from writing specs to reviewing PRs. They’re already working on adding more primitives to make working with agents even easier, and were responsive and helpful to feedback as we were building out our agent.

We're just getting started with integrating with Linear and would love your feedback on making what we have more useful. We've plans to add:

• Feedback/adoption result summaries to the Bucket agent
• Add support for link embeds in Linear
• Integrating our feature feedback function with Linear's customer requests so you can capture customer requests directly from within your application.

If you’re up for beta testing or have feedback, get in touch.