PairCoder v2.41.2

AI-augmented pair programming framework with 299 CLI commands

Overview

bpsai-pair (PairCoder) is a comprehensive AI pair programming framework that provides structured workflows, enforcement gates, and integrations to ensure AI agents follow proper development practices.

• Planning & Task Management — Sprint planning, task lifecycle, Trello sync, and budget tracking
• Skill-Based Workflows — 9 built-in skills for TDD, code review, releases, architecture, and more
• Integration Hub — Trello, GitHub, MCP servers, and Toggl time tracking
• Architecture Enforcement — File size limits, function boundaries, import caps, and auto-split suggestions
• Telemetry & Feedback — Session telemetry, self-calibrating estimation, anomaly detection
• Workspace Orchestration — Multi-project workspaces, cross-repo contract detection, impact analysis
• Intelligence Pipeline — Usage snapshots, value extraction scoring, tamper detection
• Interactive Setup Wizard — Web-based project configuration with AI-guided setup
• Licensing & Security — Tiered feature gating, secret scanning, containment mode
• Quality Control — Browser-based QC with spec format, execution runtime, and gate enforcement
• Containment Mode — Tiered file access control via PreToolUse hooks
• Autonomous Sprint Execution — bpsai-pair engage runs full sprints: branch, tasks, PR, review, observations
• Machine Interface — --json envelope on all commands for programmatic consumption
• Health Check — bpsai-pair doctor validates setup with 9 checks and auto-repair
• Slash Commands — /make-it-so (intent to PR), /draft-backlog (engage-compatible backlogs)

Installation

# Core installation
pip install bpsai-pair

# With integrations
pip install bpsai-pair[trello]      # Trello board sync
pip install bpsai-pair[github]      # GitHub PR management
pip install bpsai-pair[mcp]         # MCP server support
pip install bpsai-pair[all]         # All extras

Quick Start

# Initialize a new project
bpsai-pair init

# Or use the interactive wizard
bpsai-pair wizard

# Check project status
bpsai-pair status

# Create a sprint plan
bpsai-pair plan new my-feature --type feature

# Start a task (with Trello sync)
bpsai-pair ttask start TRELLO-123

# Run architecture checks
bpsai-pair arch check

# Pack context for AI assistants
bpsai-pair pack

Key Command Groups

License Tiers

Check your license: bpsai-pair license status

What's New

Full release history and detailed notes: paircoder.ai.

v2.41.2 — Fleet upgrade race, fully closed

• If your fleet upgrade still rolled back on v2.41.1, this completes the fix. The background startup sync no longer races the explicit upgrade command — one process performs the upgrade and commits it, on every path (interactive, --auto, and the fleet transaction).

v2.41.1 — Upgrade-commit fix for the v2.41.0 fleet rollback

• If a v2.41.0 upgrade left your repo dirty, or a fleet upgrade rolled back, this is the fix. upgrade --auto --commit now derives what to commit from what the upgrade run wrote or deleted, instead of a fixed pattern list that a new artifact class could fall outside of.

v2.41.0 — Fail-closed completions and security scans, git-layer branch protection, honest fleet attestation

• Task completions can no longer silently skip acceptance-criteria verification. The completion path fails closed with a recorded reason on every route.
• Behavior change: security scans fail closed instead of reporting clean without scanning. A scan-deps run that resolves zero packages, or whose audit process crashes or returns unparseable output, is no longer treated as a passing result. If a CI scan starts failing after upgrading, it was never really scanning.
• Protected-branch enforcement now happens in git itself, on the commit operation, not only through tool-call matching.
• Hooks can never write or stage upgrade scaffolding, even as a side effect of a background check.
• Engage runs survive killed or hung child processes without stalling, and checkpoint in-progress work to a recovery branch on an interval.
• Release attestations are honestly ordered — website confirmation lands before a release is tagged, fleet confirmation moves to a post-publish step.
• Fleet inventory labels members vs. local-only repos, and a new fleet verify-agent-config command reports settings drift.
• Model recommendations and engage --dry-run advisories can account for task complexity, not only task type, falling back honestly to the doctrine table when the data does not support a confident, differentiated pick.

v2.40.0 — Contained residue, converged upgrades, quieter reviews

• Run artifacts are scanned before they are committed. Engage run residue passes the full secret battery; a hit is held in a gitignored quarantine path and a sanitized placeholder is committed in its place.
• Upgrades converge. A dry run after an upgrade no longer re-proposes changes that already applied, and a healthy upgrade reports as one consolidated summary.
• Reviews carry signal. Findings pass a skeptic stage before reaching the report, formatting gates skip repos that do not use them, and test files are measured against test limits.
• status reads context-sync state. A repo that tracks progress without plan records shows its real phase and next action.
• The base-branch guard has a reachable opt-out. A marker file disarms it, and disarming announces itself.

v2.39.0 — Multi-provider foundations and run-exit contracts

• Experimental local-model dispatch. Multi-provider foundations land alongside the existing hosted path.
• Engage preflight runs all at once. A single battery plus engage doctor reports every blocker in one pass instead of one per attempt.
• Sibling checkouts restore on every run exit, including circuit-breaker exits; a failed restore prints a loud contract-violation line.
• Refusals print runnable remediation. Engage emits executable recipes rather than prose descriptions of what to do.
• Smaller config surface. config.yaml reduces to a user-owned core; tool-owned sections refresh on upgrade with an audited, secret-masked diff.
• require_feature_branch defaults to enforced. An unset key means enforced after upgrade; an explicit false is kept permanently.

v2.38.0 — Done means verified

• Acceptance criteria are enforced, not aspirational. Engage completion now runs the same strict-AC gate as manual task completion; unverified criteria land a task as blocked with an audited bypass, never silently done.
• Verifiers can't fail open. Single-file provenance checks actually scan (or refuse loudly), and baseline generation merges instead of clobbering the repository-wide baseline.
• The statusline tells the truth. Real durations, costs from the single pricing source of truth, and estimates labeled as estimates.
• Untrusted text stays contained. PR bodies get full credential/PII scrubbing and blockquote containment; refusal classification uses the provider's own stop reason.

v2.37.0 — Opus 5, reliability, and honest benchmarks

• Claude Opus 5, day-one support. Registry, pricing, wizard picker, and a benchmark-panel row — while model routing deliberately stays on measured evidence, not release hype.
• A tier that still discriminates. hard-plus fixtures restore separation above the saturating hard tier, so frontier models keep producing routing signal.
• Engage runs you can trust. Resume actually skips completed tasks; a safe cleanup-orphans sweeper (dry-run first, preserved work excluded); a machine-level cap stops runaway concurrent runs from exhausting your machine.
• Benchmarks tell the truth. Refusals are classified only on real metered attempts, privacy settings are honored end-to-end and fail closed, and a matrix-regrade command rebuilds reports from retained artifacts at zero API cost.

v2.36.0 — Benchmarks that discriminate, prices that reconcile

• Difficulty tiers separate the field. Fixtures now carry easy/medium/hard tiers with 10 new hard fixtures; reports score per tier, so models that all ace small tasks still rank meaningfully on hard ones.
• Conditions are first-class rows. Pin thinking on/off and reasoning-effort per row (model@effort) and compare a model against itself, not just against others.
• One pricing source of truth. Five divergent internal price tables are unified; OpenRouter prices auto-resolve from the live catalog, reasoning tokens are counted, and recorded costs reconcile against what providers actually bill.
• Sturdier autonomous runs. Engage lands driver commits on the intended branch under worktree isolation, reports aborted runs honestly, guards each benchmark row against empty/null provider output, and the security-audit gate now reads the real branch diff.
• Faster CI, governed releases. Python CI shards 4-way (~4-minute cycles); releases pin a hash manifest of the shipped .claude/ payload so fleet upgrades auto-commit only on an exact match.

v2.35.2 — Benchmarks join reality, QC agent regains its browser

• Benchmark fixtures speak your task types. The matrix fixture set is re-keyed to the vocabulary real projects actually use (feature, bugfix, chore, refactor, review), with legacy strings alias-normalized at ingestion — so benchmark matrix-run --auto-seed primes the same calibration cells your production tasks read, instead of cells nothing joins.
• Fixtures can't over-demand. A fail-closed fixture lint rejects any fixture whose grading requirements aren't explicitly stated in its own prompt, ending a class of false cross-model failures.
• Divona sees Chrome again. The QC agent's tool allowlist had excluded the browser tools entirely; it now inherits the full toolset and knows to load deferred browser tools before assuming they're absent.
• GitHub Release notes publish again. The release workflow's notes extraction wrote to the wrong stream in CI, shipping empty release bodies; notes now publish with every release.

v2.35.1 — Telemetry restored, typed git-failure handling, memory seed packs

• Driver telemetry records again under parallel lanes. v2.35.0's run-root worktree isolation sent driver-task telemetry into the ephemeral worktree, which is destroyed at run teardown — runs recorded zero driver rows. Telemetry now lands in the durable checkout, and calibration reads from the same place.
• Git and GitHub failures are classified, not guessed. A typed failure taxonomy (transient / ambiguous / permanent) drives retries — unrecognized failures are never auto-retried — and error text is scrubbed of tokens and credentials.
• engage commit and branch seams fail closed. A staging failure now fails the task instead of silently dropping its diff, branch reuse must be provably safe, cross-repo dispatch fetches a missing base branch on demand, and a halted run can no longer exit 0 and cut a PR.
• Runtime memory seed packs. init/upgrade seed Claude Code's harness memory with shipped doctrine (provenance-stamped, refresh-on-write, organic memories untouched).

v2.35.0 — Parallel lanes, governed actions, fleet threat scanning

• engage lanes run in parallel. Each run's bookkeeping lives in an isolated worktree cut from the declared base, so multiple lanes no longer contend on one shared checkout (--no-worktree opt-out available), and a fail-closed count guard refuses dispatch if any task heading fails to parse.
• Enforcement moves to the action seam. An intent layer routes requests, artifact-chain preconditions replace prose-as-command, ad-hoc bypasses are audited, and tasks marked privileged run only through an isolated executor.
• Scan your fleet against advisories. bpsai-pair advisory scan takes an affected-package list (with CVE ids) and reports impacted repos across requirements/pyproject/package.json/lockfiles, with a --fail-on-impact exit code.
• Upgrades know your stack. A file-ownership manifest separates tool-owned from project-owned files, Node projects get Node verification workflows, and fleet audit-workflow-md reports stack-mismatched files before anything is touched.
• Scheduler and run exits tell the truth. Ready tasks dispatch in dependency order without false cascade-aborts, blocked-task residue can no longer delete sibling task files, and circuit-breaker aborts exit non-zero.

v2.34.0 — One completion pipeline, safer credentials, self-healing state

• Acceptance criteria verify the same way everywhere. task update, ttask done, and MCP completion tools now run through one reconciled completion pipeline instead of two separate legacy checkers.
• Trello gets tougher and safer. Requests retry with backoff and jitter on rate limits/server errors (honoring Retry-After), a board-index cache avoids repeated full-board scans, and credentials move from a plaintext file into your OS keyring (with automatic migration and a headless-CI fallback).
• state.md heals itself. Status data lives inside a managed fence that only PairCoder rewrites; a missing or damaged fence is repaired automatically instead of silently degrading bpsai-pair status. Phase/Goal/Last Action/Next are now derived from structured data instead of parsed prose.
• Fleet upgrades are transactional. A clean-tree precondition, automatic verify-and-rollback, and a single scoped commit — with anything under .claude/ left staged for your review.
• engage has a formal run-exit contract. Every run enforces a clean-tree boundary at each lifecycle hand-off, reports a distinct blocked status, scopes commits to their actual diff, and preserves (rather than discards) recovery data on failure, with any recovered secrets quarantined.
• New --role driver|navigator option on task update/ttask done so interactively-run navigator work isn't miscounted as driver telemetry, and plan estimate now reports whether each estimate came from config, calibration, or a default.

v2.32.0 — Safer timeouts, honest audits, tighter project-management guards

• Drivers get more room, and safer interventions. The default engage task timeout rises from 30 to 90 minutes, and a stuck driver is now nudged with a graceful SIGTERM — after two consecutive stuck check-ins — before any hard kill, so long-running work is no longer discarded prematurely. An explicit repo config value still wins.
• The pre-PR security audit gate matches the merge bar. P0/P1 findings block the PR; P2-only findings post as a non-blocking comment instead of false-blocking the release.
• Bypass audits speak the real vocabulary. audit bypasses --type now filters on the actual per-flag bypass values (no_strict, local_only, force_local, allow_dirty, and the rest); the old catch-all user_override type is kept only for historical entries.
• Project-management sync got more honest. A read-only reverse sync reports a distinct FETCHED action instead of a misleading UPDATED, an acceptance check for a work item that has vanished from the board now fails closed instead of auto-completing, and a custom workflow with an unknown terminal target now errors on load instead of passing silently.
• Token estimates default to live calibration. New projects no longer ship a live token_estimates: section — delete any stale one left by an older template to restore calibration-driven estimates.

v2.31.0 — Smarter routing, honest telemetry, benchmark-calibrated estimates

• Model routing can now explore. Opt-in routing.exploration.epsilon occasionally samples an equally-qualified model from the routing band so your calibration data learns which models actually perform best on your tasks — off by default, deterministic when off, and every assignment is logged for analysis.
• Telemetry tells the truth. Task records now capture whether acceptance criteria actually passed (ac_verified), real per-session token baselines, what changed (lines/files), and which model really ran — the data your calibration report learns from is now correctness-based, not survival-based.
• Benchmarks that know their place. benchmark matrix-run runs natively (faster, no co-install), prices local models at $0, validates provider keys up front, and its seeds act as decaying cold-start priors — real production data automatically outweighs synthetic seeds as it accumulates.
• Architecture checks, calibrated. Role-aware caps are now opt-in (architecture.role_defaults: true), count only code lines when configured, and grandfathered debt lives in reviewable baseline files instead of blocking unrelated work.
• First-run polish. New projects show a real date and their branch name from the first status, before the first commit.

v2.30.1 — Review noise fix (patch)

• The code-review wiring guard now honors the .wiring-baseline.json allowlist correctly — reviews flag only NEW unwired code instead of re-reporting pre-existing debt on every pull request.
• Internal reliability and test-stability fixes.

v2.30.0 — Sprints that finish what they start

• Sprints can no longer end silently incomplete. Every completed sprint ends with a PR (the run refuses to exit without one), merged branches are cleaned up automatically, and issues referenced by the work are closed with an evidence comment.

• bpsai-pair fleet audit --branches --issues — one command reports leftover branches and unclosed-but-fixed issues across every repo in your workspace.

• review sprint <id> audits multi-repo sprints as a whole — one review pass over every repo the sprint touched, catching integration issues per-repo reviews miss.

• Review findings become data you can analyze. Every review — including clean passes — records per-finding data (agent, file, line range, defect class) locally for your own quality analytics.

• Fixes. Engage PR creation no longer fails on very long descriptions; fable model alias recognized in model config.

• Cross-repo engage runs no longer false-fail a healthy task when a diff check errors, and a task's completion verdict and sibling-repo commit both land in the actual target repo instead of the run repo.

• engage --dry-run now shows each task's resolved target repo, and preflight warns (or, with --strict-targets, refuses) when a task's description implies a sibling-repo target that failed to resolve — catching the authoring mistake before dispatch.

v2.29.0 — Full model routing for the latest Claude models

• Route every task to the model built for it. Full model-routing support across the current Claude lineup (Fable 5, Sonnet 5, Opus, Haiku): /pc-plan and /draft-backlog assign a model: to every task, and one unified router applies the same explicit > calibration > complexity precedence everywhere a model decision is made — engage dispatch, advisory hooks, and --dry-run previews always agree.
• More output from every token. Plan-time routing keeps frontier models on the reasoning-heavy work and fast models on the high-volume driver work — increasing throughput while maximizing token efficiency across a whole fleet of agents.
• Routing that improves itself. Telemetry records routed_model, routing_tier, and session_role per task; bpsai-pair calibration report recomputes calibration and flags drift between what was routed and what actually ran — so routing gets sharper with every task you complete.
• Engage reliability. Completion no longer false-blocks on already-landed work; cross-repo runs push sibling-repo branches at kickoff and after every task gate for crash durability; pushes always target the intended branch.
• Code review reliability. review pr/review branch run their checks against an isolated copy of the reviewed code — no more false failures from a busy checkout.

v2.28.2 — Latest-model support + engage durability (patch)

• Claude Sonnet 5 and Fable 5 selectable in the wizard/config; current-gen context limits corrected to 1M for accurate budgets.
• Engage pushes its branch at kickoff and after every task — crash durability + mid-run visibility.
• Fixes: engage on Windows, support create/list scope, upgrade artifact hygiene, fail-closed review pr, engage auto-PR --head.

v2.28.0 — Cross-repo engage, provider-agnostic PM, plan-time arch headroom (minor)

• Cross-repo engage. A sprint can target sibling repos — engage commits, branches, opens PRs, and verifies in the right repo per task; backlogs declare a Target repo: (backlog-level or per-task), and QA/security/review fan out across every touched repo.
• Provider-agnostic project management. pm.provider defaults to none — tasks are local files completed with bpsai-pair task update <id> --status done; Trello is opt-in. New bpsai-pair pm command group; backlog cards with status rollup.
• bpsai-pair arch headroom — reports files approaching their architecture caps so you can plan an extraction before a change is forced to "trim to fit"; surfaced automatically when engage starts.
• Engage completion-gate unification (--engage-mode) plus a race-immune per-task start record, ending a class of flaky completion gates.

v2.27.1 — Patch

• Fixed a CLAUDE.md upgrade that could duplicate the Slash Commands / CLI Reference sections. Upgrade now keeps only your ## Project-Specific Notes section and refreshes the rest from the canonical template.

v2.27.0 — Multi-provider groundwork, engage hardening, new lints

A minor release: groundwork for alternate model backends, engage-lifecycle hardening, and two author-time architecture lints.

• engage lifecycle hardening. A gate error printed to stdout could be misread as a transient API failure and retried with the wrong cause; the retry now reads both output channels and fails fast with the real reason. The dirty-tree gate is churn-aware (no longer trips on engage's own bookkeeping), the planning artifact is reconciled to a single id, lifecycle hooks resolve regardless of PATH, and a fast task-cycle "PR storm" is fixed.
• bpsai-pair arch check-encoding — flags text-mode file I/O missing an explicit encoding= (the Windows cp1252 crash class) at authorship time.
• bpsai-pair arch check-wiring — advisory lint catching code that's written and unit-tested but never wired into the live flow.
• upgrade preserves your CLAUDE.md notes. Upgrade refreshes CLAUDE.md to the canonical template while keeping your ## Project-Specific Notes section.
• Harness-adapter groundwork. Experimental scaffolding (config provider presets for OpenRouter, Ollama, Azure, and more) toward alternate model backends; Claude Code remains the harness.

v2.26.1 — Cross-platform & telemetry robustness (patch)

• Fixed a Windows UnicodeEncodeError crash when engage diffs contained non-cp1252 characters (tempfiles now written as UTF-8).
• telemetry aggregate now reads the correct source instead of discarding records, and tolerates a missing telemetry file.

v2.26.0 — Engage Workspace Pre-flight + Liveness

• Cross-repo engage runs are gated by a pre-flight check: a covering .paircoder-workspace.yaml must list every target repo, or dispatch is refused with guidance.
• Long-running tasks emit a liveness heartbeat and honor a configurable per-task timeout. Adds bpsai-pair workspace validate.
• Review agents get an explicit turn budget (fixes empty/partial reviews) and large PR diffs are no longer truncated. Tasks can declare structured metadata (target_repo, depends_on) in a YAML block.

v2.25.7 — Bootstrap correctness + auto-upgrade discipline

• The remote-session bootstrap now fires only in Claude Code cloud sessions (CLAUDE_CODE_REMOTE=true); local and headless sessions are untouched (force with PAIRCODER_BOOTSTRAP_FORCE=1).
• Auto-upgrade no longer silently commits — it stages the re-templated .paircoder/ files for review and notifies on stderr (restore the old behavior with BPSAI_UPGRADE_COMMIT=1).

v2.25.6 — Hotfix: remote-session bootstrap tracks the release

• The remote-session bootstrap pin and its dependency set are corrected so fresh remote/CI/engage sessions install the current CLI.

v2.25.5 — Engage hardening (round 2) + spend visibility

• Stricter backlog dependency parsing, transient-failure retries on lifecycle/planning dispatch, cross-repo dispatch via a **Target repo:** declaration, a --preserve-failed-branch recovery flag, and transactional backlog materialization.
• New bpsai-pair budget programmatic reports month-to-date API spend against your configured tier cap, with an optional monthly cap that can gate dispatch.

v2.25.4 — Engage reliability + provider env-var presets

• Documentation/content tasks are recognized as completed work; running engage against a plan file points you to /draft-backlog; **Acceptance criteria:** is accepted as a synonym for **AC:**.
• New bpsai-pair config provider <name> prints environment-variable presets for the major Anthropic-API-compatible providers (Anthropic, OpenRouter, Ollama, LM Studio, Azure), plus a providers guide.

v2.25.3 — CLI hardening + test parallelization

• Test suite parallelized for a ~10× speedup; license machine-binding enforced; a UTF-8-safe subprocess wrapper closes the Windows cp1252 crash class; new bpsai-pair arch check-subprocess lint.

v2.25.2 — Engage stability + Windows UTF-8 fix

• Windows engage made usable (UTF-8 sweep); quieter hook chain; workspace scope-leak fix; more precise task-file matching.

v2.25.1 — Engage hook-failure hotfix

• Hook failures propagate correctly instead of being swallowed; security findings are visible when engage blocks a PR.

v2.25.0 — Engage driver intelligence + pipeline reliability

• Skip already-completed tasks on retry; recognize driver self-commits; bpsai-pair preflight runs CI-matching tests before pushing.

v2.24.0 — Sweep: diff-aware dead-code cleanup

• bpsai-pair sweep finds dead imports, orphaned tests, and stale helpers after changes, with --fix for high-confidence removals.

v2.23.x — Engage reliability, resume, and lifecycle hardening

• engage --resume skips completed tasks on retry; human-gated tasks via requires: human in backlog frontmatter; branch lifecycle flags; more reliable automated task completion.

v2.22.0 — Agent identity + Vaivora review agent

• Named review agents (Nayru, Laverna, Bellona, Vaivora, Divona); a third review agent engages automatically for large diffs.

v2.21.x — Review command, enforcement, and observability

• bpsai-pair review pr/branch/task; targeted per-task tests; intent recognition and an approval gate for autonomous dispatch; protected-branch guard.

v2.20.0 — Engage pipeline

• bpsai-pair engage runs full sprints autonomously (branch, tasks, PR, review); /make-it-so (intent to shipped PR); bpsai-pair doctor health checks with --fix.

Documentation

• Website & Docs
• Quick Start Guide

Requirements

• Python 3.10 or higher
• Git (for project management features)

Support

• Email: support@paircoder.ai