Skip to main content
Glama

Baron

Let your coding agent write to your work tracker — and keep the same flow when you change trackers. Baron is an open-source layer that turns issues, branches, PRs, CI runs, and deployments into one normalized contract, so your agent never learns a vendor's API, states, or column names.

Docs and site: baron.zanaat.dev

Baron running the task-start then task-finish recipes through its normalized ports

The problem

AI coding agents bake one vendor's API and one team's process into prompts. The moment your issues live in Azure DevOps but your code is on GitHub, or your board columns aren't literally "To Do / Done", or you switch trackers next quarter — the prompts break, and the agent falls back to raw, vendor-specific tools. You've hardcoded vendor lock-in into the way you work.

Related MCP server: Jira - GitHub MCP Server

What Baron does

Plenty of tools let an agent read your tracker. Baron is about the other direction: writing — creating work items, moving them, cutting branches, opening and merging PRs — which is where an agent does damage when it guesses a vendor's state machine wrong.

The agent speaks one abstract vocabulary in terms of roles (backlog → ready → in_progress → in_review → done; blocking is an orthogonal flag, so a blocked item keeps the role the work is actually in), and Baron translates to each provider's real API, states, and quirks. You confirm that mapping once, at baron init, and it is committed to your repo as configuration — not re-guessed by the model on every call.

Each port binds to a provider independently, so issues on Azure DevOps, scm on GitHub, and notify on Slack is a normal setup rather than a special case.

What it looks like

You:  Start work on STORE-142.

Baron  ▸ runs the task-start recipe as a single call:
  ✓ Loaded STORE-142 "Add rate limiting to the login endpoint"  (type role: task)
  ✓ Checked it: not done, has a canonical branch, not assigned to someone else
  ✓ Branched feature/STORE-142 from the repo's default branch
  ✓ Moved STORE-142 → in_progress, assigned to you
  ✓ Commented on the item: "Started work — on branch feature/STORE-142."

That same prompt on Azure DevOps sets the work item state to Active; on GitHub it applies an in-progress label — because in_progress is a role, not a vendor state.

The checks matter as much as the actions: if the item is already done, belongs to someone else, or is a container that should never be branched, the run stops before anything is created. The branch name is derived by Baron from the item's type role, so every agent and every recipe derives the same name for the same item instead of inventing one.

Why it's different

  • Capability ports, not "a tracker." issues / scm / ci / deploy / notify, each bound to a provider independently — so a consumer mixes providers rather than betting on one vendor spanning everything.

  • Normalize, don't raw-proxy. New capabilities become first-class normalized ports; a clearly labeled provider-native escape hatch is the explicit last resort, never the default path.

  • Capability gaps are never silent. When a provider lacks something (say, native issue hierarchy), Baron either emulates it (e.g. labels), degrades with a warning, or errors loudly — decided by policy, never swallowed.

  • Workflows are recipes, not prompts. Multi-step flows (task-start, task-finish, task-land, ship) are declarative YAML executed as a single call, with guards that stop a run before it mutates anything. The order lives in the recipe rather than being improvised per run.

The first of those is the one worth reading about rather than being told: You can't set a status in Jira walks through why a work tracker cannot be normalized by mapping four states onto everything — Jira refuses to set a status at all and makes you discover the permitted transitions first, Linear's workflow states belong to a team rather than the workspace, GitHub has no hierarchy to map. It is the argument this design answers.

Quick start

Published to npm — no clone, no build. From inside your project:

# 1. Configure — one command. Auto-detects owner/repo from your git remote, offers to sign you in
#    through your browser (or paste a token instead), writes .baron/credentials (gitignored) +
#    .baron/policy.json (issues + scm bound).
npx -y @zanaat/baron-cli@latest init --provider github      # or: --provider azure-devops

# 2. Check the policy against the live provider (drift → exit 1)
npx -y @zanaat/baron-cli@latest doctor

# 3. Run a workflow recipe
npx -y @zanaat/baron-cli@latest run --recipe task-start          # by name; or pass a path

On GitHub, step 1 opens the approval page and you confirm a short code — no permission list to read, no boxes to tick, no token to paste. Pasting a fine-grained token is still offered, because it is a narrower credential than any OAuth scope and an install that wants the tighter one should not have to fight the friendlier path to get it. Either way baron doctor verifies what the credential can actually do before you start work.

Or drive it from an agent — install the Claude Code plugin (MCP server + workflow skills in one):

/plugin marketplace add zanaat-dev/baron
/plugin install baron@baron

See Getting started for the full walkthrough. Contributing to Baron itself? Run from source with pnpm baron … — see CONTRIBUTING.

Or wire the MCP server into your agent and call the tools directly across every port — baron_issue_write op=create, baron_scm_write op=pr_create, baron_ci_read op=runs, baron_deploy_read op=deployments, baron_notify_send, plus baron_recipe_run for whole workflows. In Claude Code, the plugin also ships per-recipe skills (/baron:task-start, /baron:ship). See docs/mcp.md.

The server is listed in the official MCP Registry as io.github.zanaat-dev/baron, and runs as a container for anyone who would rather not have Node on the host — see docs/mcp.md.

New to it? The Azure DevOps setup walkthrough is copy-paste from scratch (PAT scopes, init → doctor → MCP, troubleshooting).

Providers

Provider

Ports

Azure DevOps

issues · scm · ci · deploy

GitHub

issues · scm · ci · deploy

Jira

issues

Linear

issues

Slack

notify

GitLab is on the roadmap — adding a provider never changes how the agent talks to Baron, which is the whole point. Until it lands, that name describes intent, not support.

Documentation

Guide

What it covers

Getting started

Install, prerequisites, first init → doctor → run.

Setup walkthrough — Azure DevOps

From-scratch, copy-paste setup on Azure DevOps + Claude Code.

Setup walkthrough — Linear

From-scratch setup on Linear: per-team scoped states, branches from GitHub.

Setup walkthrough — Jira

From-scratch setup on Jira Cloud: workflow-gated transitions and transition screens.

Concepts

Ports, roles, capability gaps, the knowledge loop — the mental model.

Configuration

.baron/policy.json, role/type/gap maps, credentials.

CLI

baron init / doctor / run reference.

Recipes

Writing YAML recipes: ask / do / message, interpolation, the op table.

MCP server & plugin

The MCP tools and the Claude Code plugin.

Trying it with Claude Code

Hands-on: wire the MCP server to a real project + a verification checklist.

Providers

Which provider supports which port and capability.

Demo script

Ready-to-record 60-second demo (Claude Code or CLI).

The full design decision record is in ARCHITECTURE.md; the contributor working contract is CLAUDE.md, contribution terms are in CONTRIBUTING.md, and the publish playbook is RELEASING.md.

Status

v1 is built end-to-end: the issues, scm, ci, and deploy ports across Azure DevOps and GitHub plus notify via Slack, the config engine (baron init / doctor), a multi-port MCP server, the YAML recipe engine + baron run, the knowledge loop, and a Claude Code plugin. Every adapter passes a network-free conformance suite; the Azure DevOps ports are additionally live-validated against a real project.

Baron now also runs this repository — its issues, branches, and pull requests move through its own GitHub adapter. That is a working proof, not adoption: Baron is young and has not yet been put through a stack it did not grow up on. If you run it against yours, the resulting bug report is the most useful thing you could send. What is planned next, and what is deliberately out of scope, is in ROADMAP.md.

License

Open-core. The core, the adapters (Azure DevOps, GitHub, Linear, Slack), the recipes, and the CLI/MCP server are licensed under Apache-2.0. Future commercial-tier features (SSO, secret-manager integrations, multi-team governance, audit) will ship under a separate commercial license — see ARCHITECTURE.md decision #20.

Available Tools

10 tools
baron_issue_moveA

Move a work item through the workflow, or flag it. ops: transition (id, role, optional fields) — the semantic role layer, resolving an abstract role to the provider’s native state/column/label; on a provider whose transition carries a screen (Jira) a refusal with code TRANSITION_FIELDS_REQUIRED names the fields to pass back, verbatim, as fields; reconcile (id) — clear a role label the provider’s own state contradicts, commanding no role; block (id, reason — required) and unblock (id, optional reason), which set and clear an ORTHOGONAL flag and leave the role alone, so an item keeps the role it is blocked in.

Inputs: op (required), id, role, fields, +1 more.

baron_issue_readA

Read work items. ops: get (id) → one normalized issue; query (role / typeRole / assignee, @me allowed / iteration, @current allowed / limit) → a filtered list; iterations (no args) → the provider's sprints, each with a current flag, empty where the provider has none.

Inputs: op (required), id, role, limit, +3 more.

baron_issue_writeA

Change a work item’s content. ops: create (title, typeRole, optional body/parentId/labels/initialRole); update (id, title and/or body — a patch, omitted fields are left alone); comment (id, body); assign (id, assignee — @me allowed); link (fromId, toId, type); set_iteration (id, iteration — @current allowed). Roles and type roles are abstract: the active policy maps them to the provider’s own states and types.

Inputs: op (required), id, body, toId, +9 more.

baron_memory_appendB

Record something durable in Baron's own store (not a provider's). ops: learning (title, body, optional tags) — a decision worth keeping; followup (title, optional body/tags) — an open loop to come back to.

Inputs: op (required), body, tags, title.

baron_memory_queryA

Read Baron's own store. ops: learning (optional tag/text/limit); followup (optional status/tag/limit).

Inputs: op (required), tag, text, limit, +1 more.

baron_native_requestA

ESCAPE HATCH — a raw, authenticated, NON-PORTABLE provider REST call. Last resort for when no normalized tool (issue/scm/ci/notify) covers the need. You supply the provider-native method + path (+ query/body); Baron only attaches the base URL + auth and returns the (size-capped) response. Prefer the normalized tools — this is provider-specific and will not port to another provider. Only providers bound in the active policy are reachable.

Inputs: path (required), method (required), provider (required), body, +1 more.

baron_recipe_listA

List the runnable recipes (built-ins + project recipes) with their declared inputs. Call this to discover what baron_recipe_run accepts before running a workflow.

Inputs: no named parameters.

baron_recipe_runA

Run a named recipe end-to-end as ONE deterministic, rule-enforced workflow (the engine — not you — enforces the step order). Supply all required inputs (from baron_recipe_list) in inputs; a missing required input errors rather than prompting. Prefer this over composing the individual issue/scm/ci tools yourself for a packaged workflow. Returns the run context as JSON (with its runId), and — when the recipe had anything to say — a SECOND text block with its messages. Read that block: it is where a recipe reports what it could not verify (task-land warns there when it merged past checks it could not see). Every run is journaled: if one fails partway, do NOT run it again from scratch (that repeats the steps that already mutated the provider — a second PR). Call this with resume: <runId> from the error instead: completed steps are replayed from the journal and the run carries on from where it stopped.

Inputs: name, inputs, resume.

baron_scm_readA

Read source-control state. ops: pr_status (pullRequestId) → normalized state, review decision, mergeability and a checks rollup; pr_for_branch (sourceBranch, optional state — open default / merged / closed / all) → the most recent matching PR or null. open is the idempotency probe before creating one; merged is the drift probe.

Inputs: op (required), state, sourceBranch, pullRequestId.

baron_scm_writeA

Change source-control state. ops: branch_create (name, optional fromBranch — idempotent); pr_create (title, sourceBranch, optional targetBranch/body/draft/assignees/autoComplete, plus linkedIssueKey and linkedIssueRelation — closes finishes the item on merge, relates only references it); pr_thread (pullRequestId, body); pr_ready (pullRequestId) — take it out of draft; pr_merge (pullRequestId, optional strategy/deleteSourceBranch). A provider that declines a merge surfaces as MERGE_FAILED rather than a false success.

Inputs: op (required), body, name, draft, +11 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool is scoped to a distinct domain and action: memory query/append, issue read/write/move, SCM read/write, recipe list/run, and a raw native escape hatch. Potentially overlapping operations like issue update vs issue transition are explicitly separated by content-change versus workflow-role semantics.

    Naming Consistency5/5

    All tools follow the same baron_<domain>_<action> snake_case pattern with clear domains and verbs. The naming is highly predictable, making it easy for an agent to infer where a capability lives.

    Tool Count5/5

    Ten tools is well-scoped for a development-workflow assistant. Grouping related operations under issue, scm, memory, and recipe domains keeps the tool count manageable without sacrificing coverage.

    Completeness4/5

    The core issue lifecycle and PR lifecycle are well covered, and recipes provide end-to-end workflow execution. Minor gaps remain: there are references to normalized CI/notify tools that are not exposed, no way to delete/close issues or resolve memory followups, and recipe authoring is not supported.

    Maintenance

    ActivityMaintained
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      B
      quality
      Not graded
      maintenance
      Enables AI-driven orchestration of GitHub development workflows including automated issue analysis, code generation, code review, and PR creation through multiple specialized agents. Integrates with GitHub Actions to automate the complete development process from issue to pull request.
      7
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Gives coding agents 73 native tools to run their own project management — filing, linking, and resolving bugs and features, planning sprints, migrating from Jira/Linear/Shortcut, and handling cross-agent contracts, channels, DMs, notifications, and audit trails. Runs locally or remotely with API-key auth, so agents track work with full intent and reasoning instead of losing it when their context window resets.
      538 npm
      1
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Gives AI coding agents native tools to pull their next prioritized, unblocked task with a full briefing (description, acceptance criteria, context files, conventions), comment and tick off criteria with evidence, ask the human decision-maker questions, and submit structured handoffs for review. It lets agents plan epics and sprints, report checks, create new tasks, and release work with checkpoints — all against a self-hosted board rather than files in the repo.
      1
      MIT