Set up · Linear

Your buddy on Linear

A Block Buddy is a face for your agent, drawn from its name. In Linear, an agent appears with its app's name and icon. Linear doesn't publish the icon's shape, so use the pad file: opaque and safe in a circle or a square.

Where Linear shows it: the mention and filter menus, delegated issues and the agent's sessions. Shown here as a circle; Linear doesn't document the shape.

Get the files

Drawn in your browser from the name above. Nothing is uploaded anywhere.

App iconbrass-otto-pad-512.png512 × 512 PNG, opaque. Linear recommends at least 256 px.
Directory listingbrass-otto-pad-400.png400 × 400 PNG, to scale to the listing's 320 × 320 colour icon

Listing in Linear's integration directory also needs a white, one-colour 320 × 320 icon. We don't make a one-colour version yet.

Set it on your Linear app

Download the App icon (the 512 × 512 PNG).
In Linear, go to Settings → API → Applications, and create a new app or open yours.
Name it after your buddy, upload the PNG as its icon, turn on Agent session events under webhooks, and save.
Install it in the workspace with an OAuth link that includes actor=app and the app:mentionable and app:assignable scopes. A workspace admin approves.
@mention the agent or delegate an issue to it. Its face shows in the menu and in the session.

Building the app from a manifest? Its display.iconUrl field takes an image URL and fills in the form for you; a person still submits it.

For agents

The app icon is set by a person, and it's the face on every agent activity: thoughts, actions and replies have no icon of their own. One place takes a face per message: a comment or issue created with createAsUser and displayIconUrl. It shows as "Brass Otto (via your app)". Save it for moments that matter, like a finished job or an error.

Instructions

platform: linear (agent = an OAuth app installed with actor=app)
crop:     not documented; use opaque, circle-safe art
variant:  pad (the tile at 74%, centred on its own ground colour, opaque)
file:     brass-otto-pad-512.png
format:   PNG, at least 256 x 256 recommended. Format and size limits aren't documented.
buddy:    Brass Otto
hash:     0x4f7857573d121112474507868c95e98e2cbb66d73cc61e786482793f28ed9bb0
method:   app icon: a person, in Settings > API > Applications (or a manifest's display.iconUrl)
per-mode: not on agent activities. Only on commentCreate / issueCreate with createAsUser + displayIconUrl (actor=app).
map:      pending > idle · thought > thinking · action > working · elicitation, awaitingInput > needs-you
          response > speaking · complete > glad · error > error · stale > offline
checked:  2026-10-21

GraphQL: a comment wearing the glad face

mutation {
  commentCreate(input: {
    issueId: "ISSUE_ID"
    body: "Done. The fix is in the linked pull request."
    createAsUser: "Brass Otto"
    displayIconUrl: "https://YOUR-DOMAIN/brass-otto-pad-glad-256.png"
  }) { success comment { id } }
}

A face per mode is hosted for the prebuilt names, so the URL above works as it is for them. For any other name, the download kit makes the idle still only, for now.

Limits

Format	Not documented for the app icon. The directory listing takes SVG, JPEG or PNG. unverified
Max size	Not documented unverified
Dimensions	At least 256 × 256 recommended. Directory listing: 320 × 320, plus a white one-colour version.
Crop	Not documented unverified
Animation	Not documented. Our animated files aren't offered here until it is.
Who can set it	A person, in the app's settings. Installing it needs a workspace admin.
Per-mode faces	Only on comments and issues the agent posts with `displayIconUrl`. Not on session activities.

Last checked 2026-10-21 against Agents, Agent interaction, OAuth actor authorization and OAuth app manifests. Linear's agent APIs are a developer preview; we re-check this page every month or two. If a step is wrong, the platform's own docs win.