Agent Plugins

Plugins / agentic-advisor

agentic-advisor

v1.3.0

Sizes the agent's coding effort to how fragile the target is — before it writes code.

/plugin install agentic-advisor@linearb-ai
Rolling out to a team?

Roll out to your whole org

Admins can install and enable this for every developer from Claude.ai admin console → Claude Code → Managed settings. Paste this, then replace the token placeholder.

The token in managed settings is pushed to every developer's machine. Use a token created for this purpose, so you can rotate it on its own.

{
  "env": {
    "LINEARB_API_TOKEN": "<token from LinearB > Settings > API Tokens>"
  },
  "extraKnownMarketplaces": {
    "linearb-ai": {
      "source": {
        "source": "github",
        "repo": "linear-b/agent-plugins"
      },
      "autoUpdate": true
    }
  },
  "enabledPlugins": {
    "agentic-advisor@linearb-ai": true
  }
}
ChangelogSource

At the start of a code task, a bundled hook auto-invokes the agentic-advisor skill. It reads the repo's current health (LinearB rework %, unreviewed merges, recent incidents) plus local git history on the files being touched, then grades LOW / MEDIUM / HIGH effort and holds the agent to it: lean and token-efficient on calm repos, defensive (smallest change, guards, tests, clarifying questions) on fragile ones. It never blocks; if LinearB data is unavailable it defaults to MEDIUM.

Install

/plugin marketplace add linear-b/agent-plugins
/plugin install agentic-advisor@linearb-ai

Then export LINEARB_API_TOKEN (see Setup) and restart Claude Code — hooks load at startup.

What you'll see

The agent prints a one-line verdict before writing code, e.g.:

LinearB: api-service — LOW effort (healthy: rework 0.4%, 0 unreviewed merges, no incidents).

LinearB: payments-service — HIGH effort (rework 9.5% NEEDS FOCUS; target PaymentForm.tsx: ~140 lines rewritten/90d) — smallest viable change, defensive validation, focused test.

How it decides

What agentic-advisor looks at: LinearB repo health, incidents and ticket; local git history on the files you touch; and your request. Effort is the highest of the three. Only the grade and its metadata are reported to your own LinearB org; never code, file contents or full prompts. What LinearB looks at before your agent writes code You start a code task prompt, ticket key,or first file edit 1. LinearB API (your org, read-only) repo health cached 24h · ticket only when a key is named Repo health rework % (30d)unreviewedmerges Incidents recent + open,org-wide Ticket type, priority,points, labels 2. Local git (stays on your machine) only on fragile repos or sensitive files Files you'll touch lines rewritten (90d)fix / revert hints Ownership who owns the lines,is it your code? 3. Your request (no calls) scope, breadth, tricky logic, blast radius Effort = highest of 1, 2, 3 LOW lean, small diff MEDIUM normal care HIGH guards, tests, questions printed as one verdict line Reported to your own LinearB org (turn off: LINEARB_TELEMETRY=0) Sent grade + evidence, repo, branch, ticket key,your email, token counts Never sent source code, file contents,full prompts What agentic-advisor looks at: LinearB repo health, incidents and ticket; local git history on the files you touch; and your request. Effort is the highest of the three. Only the grade and its metadata are reported to your own LinearB org; never code, file contents or full prompts. What LinearB looks at before your agent writes code You start a code task prompt, ticket key, or first file edit 1. LinearB API (your org, read-only) repo health is cached for 24 hours Repo health rework % (30d)unreviewed merges Incidents recent + openorg-wide Ticket type, priority, points, labels(only when a key is named) 2. Local git (stays on your machine) only on fragile repos or sensitive files Files you'll touch lines rewritten(90d), fix/revert Ownership who owns the lines,is it your code? 3. Your request (no calls) scope, breadth, tricky logic, blast radius Effort = highest of 1, 2, 3 LOW lean, small diff MEDIUM normal care HIGH guards + tests printed as one verdict line Reported to your own LinearB org turn off: LINEARB_TELEMETRY=0 Sent grade + evidence, repo, branch,ticket key, your email, token counts Never sent source code, file contents, full prompts
  • Effort bands match LinearB's own rework benchmark: ELITE <3% / STRONG 3–6% → LOW; FAIR 6–7% → MEDIUM; NEEDS FOCUS >7% → HIGH. Effort = the highest-firing signal (rework, unreviewed merges, or a recent serious incident).
  • Task complexity: the request itself is graded too (scope, breadth, tricky logic, blast radius), so a demanding change in a calm repo still gets real care. If the prompt or branch names a ticket, its type, priority and estimate from LinearB count too (a Highest-priority bug raises the grade). The final effort is the highest of repo health, task complexity and (when it runs) phase 2.
  • Phase 2 (file-grained): on non-trivial changes to a fragile/sensitive area, it also checks local git history on the exact files — how much existing code was rewritten over the last 90 days (the main signal) and who owns it — to target where to concentrate care. Commit messages saying "fix"/"revert" count only as a weak hint.
  • Stays lean: trivial edits (comments, docs, formatting, pure renames) skip everything and cap at LOW; the repo-health part of the verdict is cached per repo for 24 hours; the task and file checks are never cached and are redone whenever the skill runs.

Triggers

Auto-fires (once per repo, per session) on a Jira ticket in the prompt, code-task keywords (fix / implement / refactor…), or the first source-file edit in a git repo. Skips questions, doc/text edits, and files outside a git repo. If the grade was decided but never printed (common at lower effort levels, where the model keeps it in its thinking), the next file read or edit is held once until the agent records the verdict line.

Usage telemetry (on by default)

Bundled hooks can report each effort decision to LinearB's reported-metrics API as the custom metric agentic_advisor.effort_decision (source: claude-code), so adoption is visible in the platform (usage per developer / per repo / by effort level). It's on by default whenever LINEARB_API_TOKEN is set — the same token the skill needs for its reads. Turn it off with export LINEARB_TELEMETRY=0. It's fire-and-forget: failures never block or slow your turn.

What it reports — two kinds of event, distinguished by tags.phase:

eventwhenvaluetoken tag
decision (phase=decision)on Stop, right after the verdict (or at SessionEnd, tagged backfill: session_end, if that turn was interrupted) — once per repo + effort level per session1 / 2 / 3 = LOW / MEDIUM / HIGHgrading_tokens — output tokens spent producing the verdict
tokens (phase=tokens)on SessionEnd, best-effort0 (not a grade — exclude from grade aggregates)coding_tokens — output tokens spent on the work after the verdict

Count adoption and grades from phase=decision rows; use phase=tokens rows only for the coding-token measurement. (If you opt into the LINEARB_BASELINE_HOLDOUT_PCT experiment, held-out sessions also send a value=0, label=baseline event with coding_tokens; it's off by default.)

Fields on both events:

fieldvalue
entity.contributor_emailyour git config user.email, or — if that's unset — the email of the Claude Code account you're signed in with (~/.claude.json); resolves to a contributor
tags.identity_sourcewhere that email came from: git, claude_account, or none
entity.repo_urlyour git remote → resolves to a repository
tags.effort_level, tags.repothe verdict's level (LOW/MEDIUM/HIGH) and repo name
tags.branch, tags.ticketcurrent git branch (join key to the PR later opened from it) and a Jira-style key parsed from it
tags.session_name, tags.modelsession title + model, for grouping
tags.plugin_versionthe plugin version that produced the event

Decision events also carry tags.evidence (the verdict's evidence snippet), tags.grading_duration_s, and tags.actual_effort (the session's reasoning-effort setting, when Claude Code exposes it).

All of this is sent only to your own LinearB org — the org your LINEARB_API_TOKEN belongs to — over HTTPS to your LinearB API (public-api.linearb.io unless you set LINEARB_API_URL); nothing goes anywhere else. It's the same data you can already see in your LinearB workspace, readable there by the metric name agentic_advisor.effort_decision (group by contributor / repo / effort level).

Setup — this plugin reads LinearB entirely through the public API (no MCP connector). Create an org-scoped API token (LinearB → Settings → API Tokens → Create API Token) and export it — the *same* token both reads health signals and reports telemetry:

export LINEARB_API_TOKEN="<your LinearB API token>"
# On-prem or regional LinearB? Point the plugin at your API (default https://public-api.linearb.io):
# export LINEARB_API_URL="https://<your-linearb-api-host>"

Then launch Claude Code from a shell that has it exported (hooks and the skill read the env at launch — a token added to an already-running session isn't seen until you restart; if you rely on ~/.zshrc, start Claude from an interactive shell). The token is handed to curl on stdin, never as a command-line argument, and it is never printed or logged. Without a token the skill degrades to MEDIUM effort (it never blocks).

Requirements

  • LINEARB_API_TOKEN exported (see Setup) — used for both reading signals and reporting. Without it, the skill degrades to MEDIUM rather than failing.
  • jq, git, and curl on PATH (used by the bundled hooks and the skill's API calls).
  • python3 (optional): without it grades are still reported, but token counts and grading time are left out.
  • No MCP connector required.

Opting out

  • Telemetry: export LINEARB_TELEMETRY=0 (also accepts false / off / no) and relaunch Claude Code. The skill keeps working with your token; only reporting stops.
  • Everything: disable the plugin (/plugin) to stop the auto-trigger. The hooks only inject a suggestion to run the skill and (optionally) report a metric — they never block your work.

Troubleshooting

Reporting is silent in the session by design, so the plugin keeps a local log instead: ${XDG_CACHE_HOME:-~/.cache}/agentic-advisor/report.log (rotated to report.log.old at 1 MB). It's on by default; turn it off with export LINEARB_DEBUG=0.

Each line starts with the time and plugin version, then one outcome:

  • Trigger: when it nudged the agent to run the skill (and why: a ticket key or code-task keywords), and when it held a tool call until the grade or the verdict line existed.
  • Skipped report: the reason, for example LINEARB_API_TOKEN not set in this session, no git remote resolved or skill never ran in this session.
  • Sent event: the grade, repo and HTTP status: 200 = recorded, 401/403 = bad token, 422 = rejected payload (with the server's reason).
  • Error: network failures with curl's reason (for example Could not resolve host), or a payload that couldn't be built.

No line contains your token, prompt or the payload; emails in server responses are redacted. The log is private to your user (folder 0700, file 0600).

Recent releases

#1.3.0

Latest Release notes

Changed

  • The troubleshooting log is now on by default, so a missing event can be diagnosed without asking the user to re-run anything. Turn it off with LINEARB_DEBUG=0. It stays local and private (0600), rotates at 1 MB, and never contains the token, prompt or payload.
  • The log now covers the trigger hook too: when it nudged the agent to run the skill, and when it held a tool call for the grade or the verdict line.
  • Every line starts with the plugin version.

Added

  • Errors are logged with their reason: network failures with curl's exit code and message, and rejected events (4xx/5xx) with the server's response, emails redacted.

#1.2.0

Release notes

Added

  • Ticket context: when the prompt or branch names a ticket (e.g. ABC-123), the skill fetches its type, priority, estimate and labels from LinearB (one call, same token) and uses them to raise the task-complexity grade, e.g. a Highest-priority bug. Skipped silently when there's no key or no PM integration. #10

#1.1.2

Release notes

Added

  • Opt-in troubleshooting log: LINEARB_DEBUG=1 writes each report's outcome (skip reason or HTTP status) to ${XDG_CACHE_HOME:-~/.cache}/agentic-advisor/report.log, rotated at 1 MB. Lines for sent events include the grade and repo name; no line contains the token, email, prompt or payload. The log stays private (folder 0700, file 0600, symlinked logs and rotation targets refused). #9

Changed

  • With no LINEARB_API_TOKEN, the verdict now says LINEARB_API_TOKEN not set and tells the user how to set it, instead of a generic "signals unavailable" that looked like a working setup. #9
  • Hooks no longer fail under set -u when HOME and XDG_CACHE_HOME are both unset. #9
All releases →