Set up · GitHub

Your buddy on GitHub

A Block Buddy is a face for your agent, drawn from its name. GitHub shows an app as a square logo inside a coloured circle. Use the tile, and set the circle to your buddy's own colour, so the two read as one.

What GitHub shows: the tile inside a circle of the badge colour you pick. Here, the buddy's own: #69798c.

Get the files

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

App logobrass-otto-tile-256.png256 × 256 PNG, transparent corners. GitHub recommends 200 px.
Bot account picturebrass-otto-pad-512.png512 × 512 PNG, opaque. For a machine user, whose picture GitHub shows as a circle.

Animated GIFA short loop per mode, for READMEs and PR comments, where GIFs play. GitHub takes a GIF logo too, but doesn't say whether it plays. Coming soon.

Set it on your GitHub App

Download the App logo (the 256 × 256 tile).
On GitHub, open your profile picture menu → Settings → Developer settings → GitHub Apps, and click Edit on your app. For an app your organization owns, start from the organization's Settings instead.
Under Display information, upload the PNG, keep the crop square, and click Set new avatar.
In Badge background color, enter #69798c, your buddy's ground colour. The tile's corners then melt into the circle. Save.
Using a bot account (a machine user) instead? Sign in as it, go to Settings → Public profile → Profile picture → Edit → Upload a photo, and choose the Bot account picture.

GitHub allows one free machine account besides your own. Copilot's agents, and the Claude and Codex agents in Agent HQ, keep the faces GitHub gives them.

For agents

The app logo is set by a person: there's no API for it, and no field in an app manifest. An agent can still show its mode where people look: a check run can carry images, so add the face for each state to its output.

Instructions

platform: github (GitHub App, shown as app-name[bot])
crop:     square image inside a circular badge, colour of your choice
variant:  tile (transparent corners), badge colour = the buddy's ground colour
file:     brass-otto-tile-256.png
badge:    #69798c
format:   PNG, JPG or GIF, under 1 MB, 200 x 200 recommended
buddy:    Brass Otto
hash:     0x4f7857573d121112474507868c95e98e2cbb66d73cc61e786482793f28ed9bb0
method:   the app owner, in the web UI (Display information). No API, no manifest field.
per-mode: check run output.images[] = {alt, image_url, caption}. GitHub Apps only.
map:      queued > idle · in_progress > working · action_required > needs-you
          success > glad · failure, timed_out > error · cancelled, skipped > sheepish
machine:  a machine user's picture: PNG, JPG or GIF under 1 MB, about 500 px, a circle > brass-otto-pad-512.png
checked:  2026-10-21

curl: a check run wearing the working face

curl -X PATCH "https://api.github.com/repos/OWNER/REPO/check-runs/CHECK_RUN_ID" \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $INSTALLATION_TOKEN" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  -d '{"status":"in_progress","output":{"title":"Brass Otto is working","summary":"Running the tests.",
       "images":[{"alt":"Brass Otto, working","image_url":"https://YOUR-DOMAIN/brass-otto-tile-working-256.png","caption":"working"}]}}'

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	PNG, JPG or GIF
Max size	Under 1 MB
Dimensions	200 × 200 recommended. A machine user's picture: about 500 × 500, under 3000 × 3000.
Crop	A square logo inside a circle of your badge colour. The exact inset isn't published unverified
Animation	GIF is accepted. Whether a GIF logo plays unverified
Who can set it	The app's owner or the organization's app managers, in the web UI
Per-mode faces	Not on the logo. In a pull request's Checks, yes: one image per check run state.

Last checked 2026-10-21 against Creating a custom badge for your GitHub App, Check runs and Custom agents configuration. If a step is wrong, the platform's own docs win.