Greybeard

        .  .
       .|  |.
       ||  ||
      .+====+.
      | .''. |
      |/ () \|    "Would I be okay getting paged
     (_`.__.'_)    about this at 3am six months
     //|    |\\    from now?"
    || |    | ||
    `--'    '--`
   ~~~~~~~~~~~~~~~~~

A CLI-first thinking tool that channels the calm, battle-tested wisdom of a Staff / Principal engineer — helping you review decisions, systems, and tradeoffs before you ship them.

The greybeard has been paged at 3am. They've watched confident decisions become production incidents. They've seen "we'll clean it up later" last five years. They're not here to block you — they're here to make sure you've thought it through.

CI codecov Documentation PyPI Python Version License Code style: ruff

---

---

Philosophy

This is not a linter. It won't yell at your variable names or enforce opinionated formatting.

This is a thinking partner. It models how Staff and Principal engineers reason about systems: failure modes, ownership, long-term cost, and the human impact of decisions. It asks the uncomfortable questions so your reviewer doesn't have to.

---

Features

Core Reviews

• Architecture Decisions — Sanity-check design docs and proposals
• Code Diffs — Review changes through a Staff-engineer lens
• Tradeoff Analysis — Surface operational risks, ownership gaps, maintenance burden
• Mentorship — Learn how experienced engineers think through problems
• Communication Coaching — Phrase feedback for specific audiences

Modes

Mode	Purpose
review	Fast, direct Staff-level assessment (default)
mentor	Explain reasoning and thought process behind concerns
coach	Help phrase constructive feedback for a specific audience
self-check	Review your own thinking before sharing with others

Interactive Mode

After running an analysis, ask follow-up questions, refine with additional context, and explore alternatives—all in a single conversation.

git diff main | greybeard analyze --interactive

> What happens if this fails in production?
> refine We're doing a 6-month rollout
> explore What if we used event sourcing instead?

See the Interactive Mode Guide for workflows, tips, and examples.

Content Packs

10+ built-in perspectives (staff engineer, on-call, security, platform engineering, startup pragmatist, etc.). Write custom YAML packs for your team's values.

IDE & Tool Integration

Runs as an MCP server compatible with Claude Desktop, Cursor, Zed, and any MCP-compatible tool. Bring greybeard into your IDE.

Multi-Backend LLM Support

Works with OpenAI, Anthropic, Ollama, or LM Studio. Configure once, use anywhere.

---

Quick Start

1. Install

# Using uv (recommended - faster)
uv pip install greybeard

# Or using pip
pip install greybeard

With optional extras:

uv pip install "greybeard[anthropic]"     # Add Claude/Anthropic support
uv pip install "greybeard[all]"           # Everything

2. Configure

greybeard init          # Interactive setup wizard
greybeard config show   # See what's configured

This creates ~/.greybeard/config.yaml with your LLM backend choice.

3. Run Your First Review

# Review a code diff
git diff main | greybeard analyze

# Review with a specific mode and pack
git diff main | greybeard analyze --mode mentor --pack oncall-future-you

# Run a self-check on a design decision
greybeard self-check --context "We're migrating auth mid-sprint"

# Get coaching on how to phrase feedback
greybeard coach --audience leadership --context "I think we're moving too fast"

4. Try Interactive Mode

# Start an interactive REPL after initial analysis
cat design-doc.md | greybeard analyze --interactive

# Then ask follow-up questions, refine with context, explore alternatives
> What's the biggest operational risk?
> refine We have strong on-call practices with Datadog everywhere
> explore What if we kept the monolith for auth?

📚 Full Documentation — docs and readthedocs

---

Usage Examples

Review a Git Diff

The simplest way to get feedback:

# Use default mode (review) and default pack from config
git diff main | greybeard analyze

# Or specify both
git diff main | greybeard analyze --mode mentor --pack staff-core

# Save output to a file
git diff main | greybeard analyze --output review.md

Interactive Iteration

Ask follow-up questions and refine your thinking:

cat my-design.md | greybeard analyze --interactive --pack oncall-future-you

Running initial analysis...

[Initial analysis output]

Interactive Review Session. Type 'help' for commands or 'quit' to exit.

> What about failure recovery?
[greybeard responds with recovery implications]

> refine We're rolling out gradually over 6 months
[greybeard adjusts analysis based on timeline]

> explore What if we used event sourcing?
[greybeard compares to original approach]

> quit

Self-Check Before Sharing

Review your own decision privately before presenting:

greybeard self-check --context "We're caching heavily with Redis"

# Returns thoughtful review of your assumptions and risks

Coach Mode for Leadership Conversations

Get help phrasing a concern constructively:

greybeard coach --audience leadership --interactive \
  --context "I'm worried we're shipping without enough integration testing"

# Initial response frames the concern clearly
# Then ask follow-ups to refine your message
> What if we added a kill switch?
> How do I explain this to non-technical stakeholders?

Include Repo Context

For better analysis, give greybeard your project structure:

git diff main | greybeard analyze --repo . --context "microservices migration"

# Greybeard has access to README, git history, structure
# Responses are more grounded in your actual setup

Review with a Custom Pack

Create a .yaml file for your team's values and review with it:

cat design-doc.md | greybeard analyze --pack ./my-team-pack.yaml

See Custom Packs below and Pack Schema for format.

---

Content Packs

Content packs define the perspective, tone, and heuristics used during review. They're plain YAML—human-editable, version-controllable, shareable.

Built-in Packs

Pack	Perspective	Focus
staff-core	Staff Engineer	Ops, ownership, long-term cost
oncall-future-you	On-call engineer, 3am	Failure modes, pager noise, recovery
mentor-mode	Experienced mentor	Teaching, reasoning, growth
solutions-architect	Solutions Architect	Entity modeling, boundaries, fit-for-purpose
platform-eng	Platform Engineer	DX, abstractions, tool maturity, scaling
security-reviewer	AppSec Engineer	Auth, injection, secrets, overprivileged access
startup-pragmatist	Pragmatic Engineer	Complexity vs stage, reversibility, scope
incident-postmortem	SRE / On-call	Blameless analysis, root cause, action items
idp-readiness	Platform Engineering	IDP maturity, automation vs process
data-migrations	Migration Expert	Lock safety, zero-downtime, rollback, performance

Testing Packs

Each built-in pack includes an example file to test with:

# Test a pack against its example
cat packs/staff-core/STAFF-CORE-EXAMPLE.md | greybeard analyze --pack staff-core

# Try different modes
cat packs/mentor-mode/MENTOR-MODE-EXAMPLE.md | greybeard analyze --pack mentor-mode --mode mentor

# See all examples
ls packs/*-EXAMPLE.md

Custom Packs

Create a .yaml file with your own perspective:

name: my-team-pack
perspective: "Platform engineer at a Series B startup"
tone: "pragmatic, balancing shipping speed with sustainability"
focus_areas:
  - "team capacity vs scope"
  - "infrastructure complexity"
  - "operational readiness"
heuristics:
  - "ask: can we do this in 2 weeks?"
  - "what's the blast radius if this breaks?"
  - "does the team have context?"
communication_style: "clear, direct, assume good intent"
description: "Reviews for our team's operating philosophy"

Then use it:

cat design-doc.md | greybeard analyze --pack ./my-team-pack.yaml

Install External Packs

Share and install packs from GitHub repos:

# Install all packs from a public repo
greybeard pack install github:someone/their-packs

# Install a single pack
greybeard pack install github:owner/repo/packs/my-pack.yaml

# List installed packs
greybeard pack list

# Remove a source
greybeard pack remove owner__repo

Installed packs are cached in ~/.greybeard/packs/ and work exactly like built-ins.

Publishing a Pack

Create a public GitHub repo with a packs/ folder containing .yaml files. Anyone can install it:

greybeard pack install github:your-handle/your-pack-repo

See Packs Guide for detailed pack creation and best practices.

---

LLM Backends

greybeard works with any LLM backend. Configure once with greybeard init:

Backend	How	What You Need
openai	OpenAI API	OPENAI_API_KEY
anthropic	Anthropic API	ANTHROPIC_API_KEY + greybeard[anthropic] extra
ollama	Local (free)	Ollama running locally
lmstudio	Local (free)	LM Studio server running

Configure Your Backend

# Interactive setup
greybeard init

# Or set directly
greybeard config set llm.backend anthropic
greybeard config set llm.model claude-3-5-sonnet

greybeard config show   # Verify

Config lives at ~/.greybeard/config.yaml.

See Backends Guide for detailed setup for each backend.

---

IDE & Tool Integration (MCP)

Run greybeard as an MCP server in Claude Desktop, Cursor, Zed, or other MCP-compatible tools.

Claude Desktop

1. Install greybeard:

uv pip install greybeard

2. Get the greybeard path:

which greybeard

3. Edit Claude config:
   • macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

Add:

{
  "mcpServers": {
    "greybeard": {
      "command": "/path/to/greybeard",
      "args": ["mcp"]
    }
  }
}

4. Restart Claude Desktop. Now you can:

You: I drafted an architecture decision. Can you review it?

Claude: I'll review this with greybeard.
[calls greybeard review tool]
[returns analysis with risks, tradeoffs, questions]

Other Tools

Cursor, Zed, and any MCP-compatible tool work the same way. Point them at greybeard mcp (or use the full path from which greybeard).

See MCP Integration Guide for detailed setup and workflow examples.

---

GitHub Actions Integration

Automatically review pull requests with greybeard using GitHub Actions. Get Staff-engineer-level feedback on demand — triggered by a label so you control when (and what) it costs.

Quick Start

1. Add the workflow file to your repo:

mkdir -p .github/workflows
curl -L https://raw.githubusercontent.com/btotharye/greybeard/main/.github/workflows/greybeard-review.yml \
  -o .github/workflows/greybeard-review.yml

2. Set up GitHub Secrets:

   • ANTHROPIC_API_KEY — your Anthropic API key (get one at console.anthropic.com)
   • GITHUB_TOKEN — auto-provided by GitHub Actions, no setup needed

3. Create the greybeard-review label in your repo:

   • Go to your repo → Issues → Labels → New label
   • Name: greybeard-review, color: #6f42c1 (purple) 🟣

4. To trigger a review: add the greybeard-review label to any PR.

Manual trigger: You can also run it on demand from Actions → Greybeard Code Review → Run workflow.

How It Works

The workflow runs three parallel review perspectives when triggered:

Pack	Focus	Icon
staff-core	Overall engineering quality, architecture, readability	🧙
oncall-future-you	Operational risk, runbooks, alerting, rollback	📟
security-reviewer	Security vulnerabilities, auth, data exposure	🔒

Each pack posts its own PR comment. Comments are updated (not duplicated) on re-runs.

Workflow Features

• ✅ Label-triggered — only runs when you explicitly ask for it (saves cost)
• ✅ Manual dispatch — run from the Actions tab any time
• ✅ Three parallel perspectives — staff, oncall, security in one run
• ✅ PR comments with findings — updated on re-run, not duplicated
• ✅ GitHub Check status for branch protection rules
• ✅ Diff truncation — automatically stays within LLM token limits
• ✅ Blocking issue detection — marks the check as failed if critical patterns found

Cost Management

The workflow uses Claude Haiku by default — the fastest and cheapest Anthropic model (~$0.05–0.20 per full 3-pack review vs ~$1+ for Sonnet).

Label-based triggering is the main cost control — reviews only run when you add the label. No surprise charges from every commit push.

Model	Cost (input/output per MTok)	Best for
claude-haiku-4-5-20251001 ✅ default	$1 / $5	Most PRs — fast, cheap, solid
claude-sonnet-4-6	$3 / $15	High-stakes PRs needing deeper analysis
claude-opus-4-6	$5 / $25	Architecture reviews, complex migrations

To use a more powerful model for a specific repo, update the workflow step:

- name: Configure Anthropic backend
  run: |
    greybeard config set llm.backend anthropic
    greybeard config set llm.model claude-sonnet-4-6   # or claude-opus-4-6

Required Permissions

The workflow requires these permissions (already set in the bundled workflow file):

permissions:
  contents: read
  pull-requests: write # post PR comments
  checks: write # set check status for branch protection

Configuration

Optional GitHub Variables (set in repo Settings → Variables):

Variable	Default	Description
GREYBEARD_RISK_THRESHOLD	high	Block threshold: none, low, medium, high

Troubleshooting

Q: The workflow isn't triggering when I add the label

• Confirm the label name is exactly greybeard-review (case-sensitive)
• Check that the workflow file is on your default branch (label events only trigger from there)

Q: 404 - model not found error

• The Anthropic model name is wrong. Check Anthropic's model docs for current names.

Q: Review comments aren't appearing

• Verify ANTHROPIC_API_KEY is set in repo Secrets
• Check the Actions log for API errors

Q: Want to run for every PR automatically?

• Change the trigger in the workflow to types: [opened, synchronize, reopened, ready_for_review]
• Be aware this will charge your API key on every push to an open PR

See GitHub Actions Integration Guide for more examples and troubleshooting.

---

Pre-commit Hook Integration

Run greybeard checks before committing—fail on risk gates, require approvals on sensitive changes.

Quick Start

1. Install pre-commit:

pip install pre-commit

2. Add to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/btotharye/greybeard
    rev: main
    hooks:
      - id: greybeard
        stages: [commit]

3. Install hooks:

pre-commit install

Risk Gates

Fail commits on sensitive paths:

# .greybeard-precommit.yaml
enabled: true
default_pack: staff-core
fail_on_concerns: critical

risk_gates:
  - name: "infra-changes"
    patterns: ["infra/*", "terraform/*"]
    fail_on_concerns: critical
    required_packs: ["platform-eng"]
    skip_if_branch: ["hotfix/*"] # Skip on urgent branches

  - name: "auth-changes"
    patterns: ["auth/*", "security/*"]
    fail_on_concerns: high
    required_packs: ["security-reviewer"]

Then commit normally—greybeard will check before the commit goes through.

See Pre-commit Integration Guide for full configuration and examples.

---

Advanced Topics

Building Custom Agents

Use the greybeard agent framework to build specialized decision-making tools:

from greybeard.common import BaseAgent

class MyAgent(BaseAgent):
    def __init__(self):
        super().__init__(name="my-agent", description="...")

    def run(self, user_input: str) -> dict:
        # Use research, interview, documentation capabilities
        context = self.research.gather_file_context("file.txt")
        response = self.llm.call(...)
        return {"result": response}

Available Capabilities:

• research — Gather context from files, directories, git history
• interview — Multi-turn conversations with users
• llm — Unified interface to all LLM backends
• documentation — Format output as Markdown, JSON, YAML

See Creating Agents Guide and the template.

Planned Specialized Agents:

• Architecture Agent (v1.1) — Document architectural decisions (ADRs)
• SLO Agent (v1.2) — Analyze systems and recommend SLOs
• Tech Debt Agent (v1.3) — Scan code and prioritize technical debt

Output Formatting

All output is structured Markdown:

## Summary

Your decision summary...

## Key Risks

- Risk 1
- Risk 2

## Tradeoffs

...

## Questions to Answer Before Proceeding

...

## Suggested Communication Language

...

_Assumptions made: ..._

Save with --output filename.md. See Output Guide.

---

Development & Contributing

Quick Dev Setup

git clone https://github.com/btotharye/greybeard.git
cd greybeard

# Using Makefile (easiest)
make install-dev
make test
make help                      # see all commands

# Or using uv directly
uv pip install -e ".[dev]"
uv run pytest

Ways to Contribute

Content Packs (easiest, high value)

• Create a perspective your team or community needs
• See Packs Guide

Custom Agents

• Build specialized tools on top of the framework
• See Creating Agents Guide

Bug Reports & Features

• Report a bug
• Suggest a feature

Code Contributions

• See CONTRIBUTING.md for setup, testing, style
• Follow Code of Conduct

Community Packs

• Build a pack repo and share it
• Open an issue linking to it—we'll feature it

---

Design Philosophy

• Multi-backend — OpenAI, Anthropic, Ollama, LM Studio. Choose your tool.
• CLI-first — No web UI. Pipe in, pipe out. Unix philosophy.
• Stateless — No conversation history by default. Add --context for prior context, or use --interactive for stateful REPL.
• Pack format — YAML for human editability and version control.
• MCP stdio — Simplest, most compatible tool integration.
• Minimal dependencies — click, pyyaml, rich, python-dotenv, optional openai / anthropic.

---

Documentation

• Getting Started — Installation, setup, first steps
• Guides — Interactive mode, packs, agents, backends, MCP, output
• Reference — CLI, config, pack schema
• Contributing — How to contribute
• Full Docs — Hosted documentation

---

License

MIT License — Use freely, modify, and distribute.

---

Questions?

• 📚 Check the docs
• 💬 GitHub Discussions
• 🐛 Open an issue

---

"The greybeard isn't here to block you. They're here to make sure you've thought it through."