Quarterback

Read the field. Call the play.

Strategic task prioritization and agent orchestration for multi-project operators.

PyPI Python License: MIT CI bobbyrgoldsmith/quarterback MCP server

---

Every other AI task manager breaks down one project into subtasks. Quarterback helps you decide which of your ten projects to prioritize right now — using a 5-factor weighted scoring engine, organizational context, and time-aware planning. It runs locally, costs nothing, and works as both a standalone CLI and an MCP server for Claude.

What Makes Quarterback Different

Feature	Quarterback	TaskMaster AI	Shrimp Task Manager
Multi-project prioritization	5-factor weighted engine	Single-project breakdown	Single-project
Advisory document system	Analyze articles against your goals	No	No
Agent orchestration	Autonomy levels + webhooks	No	No
Time-aware planning	Working hours, lunch, buffer time	No	No
Organizational context	Goals, constraints, workflows	No	No
Knowledge wiki (Playbook)	LLM-maintained wiki for cross-session consistency	No	No
Conflict detection	Cross-project scheduling conflicts	No	No
Standalone CLI	Full CLI without AI runtime	Requires AI	Requires AI
Cost	Free (MIT)	Free	Free

Quick Start

# Install
pip install quarterback

# Initialize (creates ~/.quarterback/)
quarterback init

# Interactive setup wizard — walks you through org, goals, workflows, projects, constraints
quarterback setup

# Add your first project and tasks
quarterback add "Launch landing page" --project "My Startup" --priority 4 --effort 3 --impact 5
quarterback add "Write blog post" --project "Content" --priority 3 --effort 2 --impact 3

# See what to work on
quarterback priorities

# Find quick wins
quarterback quick-wins

# Plan your day with time awareness
quarterback plan-day

LLM-Powered Setup (via MCP)

When using Quarterback as an MCP server, ask your LLM: "Set up Quarterback for me" — it will call the setup_quarterback tool, interview you conversationally about your business, goals, workflows, projects, constraints, and knowledge base (Playbook), then write all config files and database records in one shot. No manual YAML editing required.

MCP Server

Quarterback works with any MCP-compatible client — Claude Desktop, Claude Code, Cursor, Windsurf, Cline, OpenAI agents, and others. All 23 tools use standard MCP protocol (JSON-RPC over stdio) with no LLM-specific dependencies.

# Install with MCP support
pip install quarterback[mcp]

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "quarterback": {
      "command": "quarterback-server"
    }
  }
}

Or for Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "quarterback": {
      "command": "quarterback-server"
    }
  }
}

The same quarterback-server command works with any MCP client — just add it to your client's server configuration.

Then ask your LLM: "What should I work on today?" — it will use all 23 Quarterback tools to analyze your priorities.

Features

5-Factor Prioritization Engine

Every task is scored across five dimensions:

Factor	Weight	What it measures
Impact	30%	Task impact + project revenue/strategic value
Urgency	25%	Due date proximity + blocking status
Strategic	25%	Project priority + milestone status
Effort	15%	Inverted effort score (quick tasks score higher)
Quick Win	5%	High impact + low effort bonus

Advisory Document System

Analyze external articles, books, and advice against your organizational context:

# Import and auto-analyze an article
quarterback advisory-add --title "Growth Strategy" --url https://example.com/article

# Review the analysis
quarterback advisory-view --id 1

# Approve recommendations (optionally create tasks)
quarterback advisory-approve --id 1 --approve 1,3,5 --create-tasks

The analyzer checks every recommendation against your goals and constraints, flagging conflicts and synergies.

Agent Orchestration

Mark tasks for autonomous agent execution with configurable autonomy:

• Draft: Agent creates a draft for your review
• Checkpoint: Agent pauses at key decisions for approval
• Autonomous: Agent runs to completion

Webhooks notify your automation layer (n8n, Zapier, custom) when tasks are ready.

Playbook — Knowledge Wiki

Playbook is Quarterback's compiled knowledge layer. It's an LLM-maintained markdown wiki that gives every session — local CLI, MCP, or autonomous agent — the same canonical context about your projects, decisions, and strategies.

The problem it solves: Without Playbook, each AI session starts fresh and re-derives your organizational context from sparse signals. Two sessions running the same query can produce different results because they reconstruct understanding independently. Playbook provides accumulated knowledge that all sessions read from.

How it works:

~/playbook/                          (or ~/.quarterback/playbook/)
├── CLAUDE.md                        # Schema — how the LLM reads/writes pages
├── raw/                             # Drop zone for source material
└── wiki/
    ├── index.md                     # Master catalog — read this first
    ├── entities/                    # Companies, products, clients, tools
    ├── concepts/                    # Patterns, strategies, recurring themes
    ├── decisions/                   # Decisions with rationale and alternatives
    ├── compiled/                    # QB-compatible files for task scoring
    │   ├── goals.md                 # Read by QB's prioritization engine
    │   └── constraints.md           # Read by QB's conflict detection
    └── log.md                       # Append-only operations record

Setup: Playbook is created automatically during quarterback setup (or the MCP setup wizard). The interview asks about your key entities, concepts, and decisions, then seeds initial wiki pages.

Without Playbook: Quarterback works exactly as before — reading goals and constraints from ~/.quarterback/org-context/ files. Playbook is opt-in.

With Playbook: Quarterback reads compiled/goals.md and compiled/constraints.md from Playbook first, falling back to org-context/ files if Playbook isn't initialized. Your LLM reads wiki/index.md for full organizational context.

# Check Playbook status
quarterback playbook status

# Browse the index
quarterback playbook index

# List pages by category
quarterback playbook list --category entities

# Read a specific page
quarterback playbook read entities/my-product.md

# Search across all pages
quarterback playbook search "budget"

Obsidian integration (optional): During setup, you can opt to configure Playbook as an Obsidian vault. Open the Playbook folder in Obsidian for graph visualization and visual editing. Install an Obsidian MCP server for programmatic access. No Obsidian dependency required — Playbook works as plain markdown files.

CI/CD Pipeline Integration

Quarterback's CLI and webhook system make it a natural fit for automated pipelines — update task status, log deliverables, and trigger downstream work without a human in the loop.

Direct CLI in pipelines

Add Quarterback commands to any CI/CD step. The CLI is stateless and scriptable:

# GitHub Actions example: auto-update task on deploy
- name: Mark deploy task complete
  run: |
    pip install quarterback
    export QUARTERBACK_HOME=${{ runner.temp }}/.quarterback
    quarterback update 42 --status completed --notes "Deployed via CI, SHA: ${{ github.sha }}"

# After test suite passes, log results to a task
- name: Report test results
  run: |
    quarterback update 38 --notes "Tests passed: 106/106, coverage 87%. Build #${{ github.run_number }}"

# Nightly: check for overdue deliverables and alert
- name: Nightly priority check
  run: |
    quarterback alert-check
    quarterback priorities today --limit 5

Agentic CI/CD with webhooks

Register a webhook and let your automation layer react to task events in real time:

# Register a webhook pointing at your n8n/Zapier/custom endpoint
quarterback-server  # MCP tools available, or use CLI:

# In your automation script: mark a task agent-ready after PR merge
import subprocess
subprocess.run([
    "quarterback", "update", "55",
    "--status", "completed",
    "--notes", f"PR #{pr_number} merged. Deployed to staging."
])

Use cases:

Pipeline event	Quarterback action	What happens
PR merged	update_task status=completed	Task marked done, webhook fires to Slack
Deploy succeeds	update_task with SHA + environment notes	Deliverable tracked with audit trail
Nightly cron	get_priorities + alert-check	Team gets daily summary of what's overdue
Test suite fails	add_task with failure details	Bug auto-filed, linked to project
Sprint starts	get_priorities + detect_conflicts	Surface scheduling conflicts before work begins
Agent completes work	update_agent_status status=completed	Webhook notifies orchestrator, next task dispatched
Release tagged	advisory-add with release notes	Changelog analyzed against project goals

Shared database across environments

Point multiple environments at the same Quarterback instance:

# All CI runners share one database via mounted volume or network path
export QUARTERBACK_HOME=/shared/quarterback

# Or per-environment with migration
quarterback migrate /path/to/source

This lets your local CLI, CI pipelines, and MCP-connected agents all read and write to the same task graph — giving you a single source of truth across manual and automated workflows.

Time-Aware Planning

quarterback plan-day

Considers your working hours, lunch break, buffer time for meetings, and current time to suggest tasks that actually fit in your remaining day.

Configuration

Organizational Context

After quarterback init, run quarterback setup for an interactive wizard, or ask Claude to run the setup wizard via MCP. You can also manually configure your context in ~/.quarterback/org-context/:

~/.quarterback/org-context/
├── goals.md          # Your strategic, workflow, and project goals
├── projects.yaml     # Active projects with metadata
├── workflows.yaml    # Groups of related projects
└── constraints.md    # Time, budget, and strategic boundaries

Example templates are included — copy from .example files and customize.

If you enable Playbook during setup, goals.md and constraints.md are auto-maintained from the wiki's compiled/ directory. You can still manually edit the org-context files — Playbook is additive, not required.

Alert Configuration

Configure notifications in ~/.quarterback/config/alerts.yaml:

• Quiet hours (no notifications at night)
• Priority thresholds (only notify for P4+ tasks)
• Time-sensitive projects (always notify for Bills, Tax, etc.)
• Working hours and lunch break settings

CLI Commands

Command	Description
quarterback init	Initialize Quarterback
quarterback setup	Interactive setup wizard
quarterback migrate <dir>	Migrate from task-manager
quarterback priorities [today|week|all]	Prioritized task list
quarterback add "task" [options]	Add a task
quarterback update <id> [options]	Update a task
quarterback list [-s status]	List tasks
quarterback quick-wins	Find quick wins
quarterback conflicts	Detect priority conflicts
quarterback projects	List projects
quarterback summary	Organizational summary
quarterback plan-day	Time-aware daily plan
quarterback advisory-add	Add advisory document
quarterback advisory-list	List advisory documents
quarterback advisory-view --id N	View document details
quarterback advisory-analyze --id N	Analyze document
quarterback advisory-approve --id N	Approve/reject recommendations
quarterback alert-check	Check for alerts
quarterback alert-summary	Send daily summary
quarterback playbook status	Playbook initialization status
quarterback playbook index	Show Playbook master catalog
quarterback playbook list	List wiki pages (with --category filter)
quarterback playbook read <path>	Read a wiki page
quarterback playbook search <query>	Full-text search across pages

MCP Tools (27 total)

When used as an MCP server, Quarterback exposes these tools to Claude:

Task Management: get_priorities, add_task, update_task, get_quick_wins, detect_conflicts, assess_task_value, get_blocking_tasks

Project Management: add_project, list_projects, update_project, get_organizational_summary

Advisory System: add_advisory_document, list_advisory_documents, get_advisory_document, analyze_advisory_document, discuss_advisory_recommendations, adopt_advisory_recommendations

Playbook: playbook_read, playbook_write, playbook_search, playbook_ingest

Webhooks: register_webhook, list_webhooks, update_webhook, delete_webhook

Agent Orchestration: mark_task_agent_ready, get_agent_ready_tasks, update_agent_status

Setup: setup_quarterback

Environment Variables

Variable	Default	Description
QUARTERBACK_HOME	~/.quarterback	Data directory
PLAYBOOK_PATH	~/.quarterback/playbook	Playbook wiki location (or set in config/playbook.yaml)
QUARTERBACK_API_URL	None	Reserved for Pro features

Contributing

See CONTRIBUTING.md for development setup, code style, and PR process.

License

MIT - see LICENSE

---

Built by NodeBridge Automation Solutions | GitHub Sponsors