Bear Metal · Bluebear

Bear Metal is the autonomous coding agent we run against our own backlog. It polls Linear for tickets delegated to it, builds a workspace, and opens a pull request through your GitHub App installation - ready for review, not just drafted.

LicenseMIT

RuntimeNode.js 22+

ModelsAnthropic, OpenAI, or Google

DeployContainer or self-hosted

Bear Metal is open source because a background coding agent has to run on infrastructure you control. You provide the GitHub App installation, the Linear token, and the model credentials. You decide which repositories it can reach, which tickets it works, and how long a session runs before it hands a ticket back to a human.

What Bear Metal Is Good At

Bear Metal is built for scoped, well-specified engineering tickets: the dependency bump, the small refactor, the bug with a known repro, the maintenance task that’s clear enough to hand off. It is not a replacement for the design and architecture work that needs a human in the loop from the start - it’s a worker for the queue of tickets behind that work.

Linear Delegation

Works tickets delegated to its bot user, not simply assigned. The original assignee stays on the ticket; Bear Metal works it on their behalf and hands it back when done.

GitHub App Permissions

Authenticates as a GitHub App installation scoped to contents, pull requests, and checks. There is no merge access - every change lands as a pull request.

Workspace Builder

A command or script you control prepares the repository before the agent runs, from a single clone to multi-repo routing by ticket label.

Time and Token Budgets

Per-session limits on iterations, wall-clock time, and tokens mean a stuck ticket hands back to a human instead of running indefinitely.

Stale Task Recovery

Heartbeat monitoring reclaims a task if a worker goes quiet, with a reclaim cap so a broken ticket doesn't loop forever.

Model Flexibility

Runs on Anthropic, OpenAI, or Google models depending on which API key you provide, with an override for a specific model ID.

Iterates to Mergeable

Watches a PR after opening it and re-dispatches on a failing check, a review comment, or a merge conflict - pushing fixes and resolving conflicts until the branch is mergeable.

How Bear Metal Works

Delegate a ticket. In Linear, delegate a ticket to the Bear Metal bot user. The original assignee stays on record.
Bear Metal picks it up. The manager polls Linear on a configurable interval and claims delegated tickets, up to your worker concurrency limit.
The workspace builder runs. Your command or script clones and prepares the target repository, or repositories, into a fresh workspace.
The coding agent works the ticket. It runs inside that workspace, bounded by the iteration, time, and token limits you configure.
A pull request opens. Bear Metal pushes a branch and opens or updates a PR through its GitHub App installation.
Bear Metal iterates until it's mergeable. It watches the PR for failing checks, review comments, and merge conflicts, and re-dispatches itself to push fixes until the branch is clean.
You get notified. The dashboard and an optional Slack notification show what shipped, what's in progress, and what needs attention.

Common Use Cases

Clear a backlog of well-scoped tickets without pulling a developer off deeper work.
Handle routine maintenance: dependency bumps, config updates, small refactors.
Route tickets to the right codebase in a multi-repo organization using ticket tags.
Run a continuously available agent for after-hours or low-priority ticket throughput.

Quick Start

Clone the repository and configure your environment:

git clone https://github.com/bluebear-io/bear-metal.git
cd bear-metal
npm install
cp .env.example .env

Fill in your GitHub App credentials, Linear API token, at least one LLM provider key, and a workspace builder command, then build and run:

npm run build
npm start

Or skip building from source and run the public container image instead:

docker run --env-file .env ghcr.io/bluebear-io/bear-metal:latest

The GitHub README has the full GitHub App setup guide, the Linear delegation model, workspace builder patterns for single- and multi-repo setups, and the complete environment variable reference.