greybeard (Btotharye)

🧙 老手

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

一个CLI优先的思维工具，可以引导员工/首席工程师冷静、久经考验的智慧，帮助您在发货前审查决策、系统和权衡。 灰胡子在凌晨3点被寻呼。他们看到自信的决定变成了生产事故。过去五年，他们看到了“我们稍后会清理”。他们不是来阻止你的——他们是来确保你已经想清楚了。

______________________________________________________________________

______________________________________________________________________

哲学

这是 不 门楣。它不会对你的变量名大喊大叫，也不会强制执行固执己见的格式。

这是一个 思考伙伴它模拟了员工和首席工程师如何对系统进行推理：故障模式、所有权、长期成本和决策的人为影响。它会问一些不舒服的问题，这样你的审稿人就不必问了。

______________________________________________________________________

特性

核心评论

• 架构决策 --卫生检查设计文件和建议
• 代码差异 --通过员工工程师的视角审查变更
• 权衡分析 --表面操作风险、所有权缺口、维护负担
• 导师制 --了解经验丰富的工程师如何思考问题
• 沟通辅导 --针对特定受众的短语反馈

模式

交互模式

在运行分析后，提出后续问题，根据其他背景进行细化，并探索替代方案——所有这些都在一次对话中完成。

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?

看 互动模式指南 有关工作流程、提示和示例。

内容包

10+内置视角（员工工程师、随叫随到、安全、平台工程、创业实用主义者等）。为团队的值编写自定义的YAML包。

IDE和工具集成

作为与Claude Desktop、Cursor、Zed和任何MCP兼容工具兼容的MCP服务器运行。将灰胡子带到IDE中。

多后端LLM支持

与OpenAI、Anthropic、Ollama或LM Studio合作。配置一次，随时随地使用。

______________________________________________________________________

快速开始

1.安装

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

# Or using pip
pip install greybeard

带有可选附加功能：

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

2.配置

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

这创造了 ~/.greybeard/config.yaml 您可以选择LLM后端。

3.运行你的第一个评论

# 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.尝试互动模式

# 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?

📚 全部文件 — 文档 和 已阅读文档

______________________________________________________________________

使用示例

查看Git差异

获得反馈的最简单方法：

# 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

交互迭代

提出后续问题并完善你的想法：

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

分享前自我检查

在演示之前，请私下审查您自己的决定：

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

# Returns thoughtful review of your assumptions and risks

领导力对话的教练模式

获得建设性地表达担忧的帮助：

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?

包括回购背景

为了更好的分析，给灰胡子你的项目结构：

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

使用自定义包进行审核

创建一个 .yaml 将团队的价值观归档并进行审查：

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

看 自定义包 下面和 包架构 对于格式。

______________________________________________________________________

内容包

内容包定义了复习过程中使用的视角、语调和启发式方法。它们是简单的YAML——人类可编辑、版本可控、可共享。

内置包

测试包

每个内置包都包含一个示例文件进行测试：

# 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

自定义包

创建一个 .yaml 使用您自己的视角创建文件：

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"

然后使用它：

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

安装外部包

从GitHub仓库共享和安装包：

# 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

已安装的包缓存在 ~/.greybeard/packs/ 和内置的一样工作。

发布包

创建一个公共GitHub仓库 packs/ 文件夹包含 .yaml 文件夹。任何人都可以安装它：

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

看 包装指南 了解详细的包创建和最佳实践。

______________________________________________________________________

LLM后端

greybear适用于任何LLM后端。配置一次 greybeard init:

配置您的后端

# 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住在 ~/.greybeard/config.yaml.

看 后端指南 了解每个后端的详细设置。

______________________________________________________________________

IDE和工具集成（MCP）

在Claude Desktop、Cursor、Zed或其他MCP兼容工具中以MCP服务器的身份运行灰胡子。

克劳德桌面版

1. 安装灰胡子：

uv pip install greybeard

1. 获取灰胡子路径：

which greybeard

1. 编辑Claude配置：

- macOS： ~/Library/Application\ Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json - Linux： ~/.config/Claude/claude_desktop_config.json

添加：

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

1. 重新启动克劳德桌面。现在您可以：

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]

其他工具

Cursor、Zed和任何兼容MCP的工具的工作方式都是一样的。指向他们 greybeard mcp （或使用来自的完整路径 which greybeard).

看 MCP集成指南 查看详细的设置和工作流程示例。

______________________________________________________________________

GitHub操作集成

使用GitHub Actions自动查看灰胡子拉取请求。按需获取员工工程师级别的反馈——由标签触发，以便您控制何时（以及成本）。

快速开始

1. 将工作流文件添加到您的仓库：

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

1. 设置GitHub秘密：

- ANTHROPIC_API_KEY -您的Anthropic API密钥（在 console.anthropic.com) - GITHUB_TOKEN --由GitHub Actions自动提供，无需设置

1. 创建 greybeard-review repo中的标签：

- 转到您的仓库→ 问题 → 标签 → 新标签 - 姓名： greybeard-review，颜色： #6f42c1 （紫色）🟣

1. 要触发审核：添加 greybeard-review 标签到任何PR。

手动触发： 您还可以按需运行它 行动→ 灰胡子代码审查→ 运行工作流.

运作原理

触发时，工作流会运行三个并行的审查视角：

每个包都会发布自己的公关评论。评论会在重新运行时更新（不重复）。

工作流功能

• ✅ 标签已触发 --仅在您明确要求时运行（节省成本）
• ✅ 人工调度 --随时从“操作”选项卡运行
• ✅ 三个平行视角 --员工、全体员工、安保人员一次到位
• ✅ 公关评论 研究结果——重新运行时更新，不重复
• ✅ GitHub检查状态 用于分支保护规则
• ✅ 差分截断 --自动保持在LLM令牌限制内
• ✅ 阻塞问题检测 --如果发现关键模式，则将检查标记为失败

成本管理

工作流使用 克劳德·海库 默认情况下，这是最快、最便宜的Anthropic型号（每份完整的3包评论约0.05-0.20美元，Sonnet约1美元以上）。

基于标签的触发是主要的成本控制 --评论仅在添加标签时运行。每一次提交都会带来意想不到的指控。

要为特定的仓库使用更强大的模型，请更新工作流步骤：

- 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

必需的权限

工作流需要以下权限（已在捆绑的工作流文件中设置）：

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

配置

可选GitHub变量（在仓库设置中设置→ 变量）：

故障排除

Q： 添加标签时未触发工作流

• 确认标签名称准确无误 greybeard-review （区分大小写）
• 检查工作流文件是否位于默认分支上（标签事件仅从那里触发）

Q 404 - model not found 错误

• Anthropic模型名称错误。检查 Anthropic的模型文档 对于当前名称。

Q： 未显示评论

• 验证 ANTHROPIC_API_KEY 在repo Secrets中设置
• 检查操作日志中的API错误

Q： 想要自动运行每个PR吗？

• 将工作流中的触发器更改为 types: [opened, synchronize, reopened, ready_for_review]
• 请注意，这将在每次向开放PR推送时向您的API密钥收费

看 了解更多示例和故障排除。

______________________________________________________________________

预提交钩子集成

在提交之前进行灰胡子检查——在风险门上失败，需要对敏感变更进行批准。

快速开始

1. 安装预提交：

pip install pre-commit

1. 添加 .pre-commit-config.yaml:

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

1. 安装挂钩：

pre-commit install

风险闸门

敏感路径上的失败提交：

# .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"]

然后正常提交——灰胡子会在提交之前进行检查。

看 预提交集成指南 查看完整配置和示例。

______________________________________________________________________

高级主题

建筑定制代理

使用灰胡子代理框架构建专门的决策工具：

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}

可用功能：

• research --从文件、目录、git历史记录中收集上下文
• interview --与用户进行多轮对话
• llm --所有LLM后端的统一接口
• documentation --输出格式为Markdown、JSON、YAML

看 创建代理指南 和那个 模板.

计划中的专业代理：

• 架构代理 （v1.1）——记录架构决策（ADR）
• SLO代理 （v1.2）——分析系统并推荐SLO
• 技术债务代理 （v1.3）--扫描代码并优先处理技术债务

输出格式化

所有输出都是结构化的Markdown：

## Summary

Your decision summary...

## Key Risks

- Risk 1
- Risk 2

## Tradeoffs

...

## Questions to Answer Before Proceeding

...

## Suggested Communication Language

...

_Assumptions made: ..._

节省 --output filename.md。参见 输出指南.

______________________________________________________________________

发展与贡献

快速开发设置

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

贡献方式

内容包 （最简单、价值高）

• 创建您的团队或社区所需的视角
• 看 包装指南

自定义代理

• 在框架之上构建专用工具
• 看 创建代理指南

Bug报告和功能

• 报告错误
• 建议一个功能

代码贡献

• 看 贡献.md 用于设置、测试、样式
• 跟随 行为准则

社区包

• 构建一个包仓库并共享
• 打开一个链接到它的问题——我们将重点介绍它

______________________________________________________________________

设计理念

• 多后端 --OpenAI、Anthropic、Ollama、LM工作室。选择你的工具。
• CLI优先 --没有web UI。管进来，管出去。Unix哲学。
• 无状态 --默认情况下没有对话历史记录。添加 --context 用于先前上下文或使用 --interactive 用于有状态的REPL。
• 包装格式 --YAML用于人类可编辑性和版本控制。
• MCP 标准 --最简单、最兼容的工具集成。
• 最小依赖性 — click, pyyaml, rich, python-dotenv，可选 openai / anthropic.

______________________________________________________________________

文档

• 入门指南 --安装、设置、第一步
• 指南 --交互模式、包、代理、后端、MCP、输出
• 参考 --CLI、配置、包模式
• 贡献 --如何做出贡献
• 完整文档 --托管文档

______________________________________________________________________

许可证

MIT许可证 --自由使用、修改和分发。

______________________________________________________________________

问题？

• 📚 检查 文档
• 💬
• 🐛 打开一个问题

______________________________________________________________________

_“灰胡子不是来阻止你的。他们是来确保你想清楚的。”_