{"id":49492821,"url":"https://github.com/papperrollinggery/lazy-brain","last_synced_at":"2026-05-01T07:06:23.771Z","repository":{"id":352466596,"uuid":"1211505131","full_name":"papperrollinggery/lazy-brain","owner":"papperrollinggery","description":"Semantic skill router / sidecar agent for AI coding assistants — route intent to the right skill, agent, command, or MCP tool","archived":false,"fork":false,"pushed_at":"2026-04-27T12:00:34.000Z","size":847,"stargazers_count":3,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-27T12:08:23.633Z","etag":null,"topics":["ai-tools","claude-code","command-palette","developer-tools","productivity","skill-router"],"latest_commit_sha":null,"homepage":"https://github.com/papperrollinggery/lazy-brain","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/papperrollinggery.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-15T13:10:04.000Z","updated_at":"2026-04-27T12:00:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/papperrollinggery/lazy-brain","commit_stats":null,"previous_names":["papperrollinggery/lazy-brain"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/papperrollinggery/lazy-brain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papperrollinggery%2Flazy-brain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papperrollinggery%2Flazy-brain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papperrollinggery%2Flazy-brain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papperrollinggery%2Flazy-brain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/papperrollinggery","download_url":"https://codeload.github.com/papperrollinggery/lazy-brain/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papperrollinggery%2Flazy-brain/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32487752,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","claude-code","command-palette","developer-tools","productivity","skill-router"],"created_at":"2026-05-01T07:06:23.053Z","updated_at":"2026-05-01T07:06:23.756Z","avatar_url":"https://github.com/papperrollinggery.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🧠 LazyBrain\n\n**Semantic Skill Router / Sidecar Agent for AI Coding Assistants**  \n**面向 AI 编码助手的语义路由器 / 附属性智能体**\n\n[![CI](https://github.com/papperrollinggery/lazy-brain/actions/workflows/ci.yml/badge.svg)](https://github.com/papperrollinggery/lazy-brain/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n[![Node](https://img.shields.io/badge/node-%E2%89%A518-brightgreen.svg)](https://nodejs.org)\n\n\u003e A sidecar agent that turns a fragmented toolbelt into an intent-aware execution layer.  \n\u003e Scan capabilities, compile a graph, route non-trivial work, and stay out of the `Stop` lifecycle.\n\n[English](README.md) | [中文文档](README_CN.md)\n\n---\n\n\u003c/div\u003e\n\n## Current Release\n\nCurrent version: **v1.4.5**\n\nRelease position: **low-intrusion routing beta**. This version hardens `RouteSpec`, adds a read-only MCP server, adds copyable target prompts, and changes the Claude hook into a tiny gate. The hook only reminds the main model to call LazyBrain for non-trivial work; full recommendations stay in `lazybrain route`, `/api/route`, MCP, GUI, or explicit prompt output.\n\n## Overview\n\nModern coding environments accumulate a large number of capabilities:\n\n- local skills\n- project agents\n- CLI commands\n- MCP-backed tools\n- orchestration modes\n\nThe real bottleneck is not capability supply. It is **capability recall and execution routing**.\n\nLazyBrain sits beside the primary coding model as a **sidecar agent**:\n\n- it scans the local capability surface\n- compiles a knowledge graph over those capabilities\n- builds advisory route plans for the main model\n- exposes the same route contract through CLI, HTTP API, MCP, and prompt output\n- avoids competing for `Stop` hooks with memory and notification plugins\n\nThe result is a system where the user says what they want, and the router decides which capability should be brought into context.\n\n## Why It Exists\n\nWithout a routing layer, advanced AI coding setups degrade in predictable ways:\n\n- installed tools go unused because nobody remembers exact names\n- cross-language queries fail (`中文需求` vs English capability names)\n- users over-trigger expensive modes because the surface is too fragmented\n- multiple plugins overlap, but no layer explains which one should act\n\nLazyBrain addresses that by turning a loose toolbelt into a structured capability layer.\n\n```\nYou type: \"帮我审查这个 PR\"\nLazyBrain: → /review-pr (92%) | /critic (78%) | /santa-loop (71%)\n           → Route Plan: use code review + regression checks + test evidence\n```\n\n## Core Properties\n\n- **Intent-first routing**: users describe goals, not command names\n- **Capability-agnostic**: covers skills, agents, commands, modes, and hooks\n- **Bilingual matching**: Chinese and English queries are both first-class\n- **Local-first pipeline**: scan, graph, wiki, and tag layers work from local artifacts\n- **Low-intrusion lifecycle**: project-scoped `UserPromptSubmit` tiny gate only; no `Stop`, no default `SessionStart`\n\n## How It Works / 工作方式\n\nLazyBrain has three phases: **Scan → Compile → Route**. Routing can be tested in Lab first, then installed as a Claude Code hook when you are ready.\n\n```\n  ┌──────────┐     ┌──────────┐     ┌──────────────┐\n  │   scan   │────▶│ compile  │────▶│ route / lab  │\n  │ Discover │     │ LLM tags │     │ preview or   │\n  │ tools    │     │ + graph  │     │ MCP / prompt │\n  └──────────┘     └──────────┘     └──────────────┘\n       │                 │                 │\n  local capability  graph.json      Lab preview\n  surfaces          wiki/           or UserPromptSubmit\n  MCP + built-ins   relations       tiny hook gate\n```\n\n1. **scan** — Discovers all skills, agents, MCP tools, and built-in commands  \n   **scan**：扫描本地 skill、agent、MCP 工具和内置命令\n2. **compile** — Builds the graph offline, or uses an LLM when configured for richer tags and relationships\n   **compile**：离线构建图谱；配置 LLM 后可生成更丰富的标签和关系\n3. **route** — Returns an advisory `RouteSpec`; hook/MCP/prompt are just delivery surfaces\n\n## Public-Safe Workflow\n\nDefault flow for public users:\n\n```bash\nlazybrain scan\nlazybrain compile --offline\nlazybrain ready\nlazybrain ui\nlazybrain route \"review this PR\"\nlazybrain prompt \"review this PR\" --target claude\nlazybrain hook plan\nlazybrain hook install\n```\n\nSafety defaults:\n\n- Lab does not install hooks and does not write `.claude/settings.json`\n- `hook plan` is dry-run only\n- `hook install` defaults to project scope and creates a backup first\n- global install requires `lazybrain hook install --global --yes`\n- LazyBrain does not use `Stop` as a product lifecycle\n- third-party hooks and HUD/statusline entries are preserved by default\n- GUI v1 does not install hooks directly; it shows status, previews, and CLI fallback commands\n- `lazybrain route` is advisory only; it does not execute skills or write target CLI config\n- `lazybrain mcp` is read-only and does not return agent bodies or private transcripts\n- installed hook only injects a short reminder: `Consider calling lazybrain.route for skill routing, context reduction, and verification planning.`\n\n## What Counts as a Skill / Agent / Capability\n\nLazyBrain treats the local AI tool surface as **capabilities**. A capability can be:\n\n- a skill directory with `SKILL.md`\n- a Claude/Agent Agency agent markdown file\n- a command markdown file\n- a mode, hook, or plugin-provided entry that appears in scanned paths\n\nFor skills, LazyBrain reads:\n\n- `name`, `description`, `trigger`, `triggers`, and `origin` from frontmatter when present\n- optional route schema fields: `useWhen`, `avoidWhen`, `inputs`, `workflow`, `verification`, `doneWhen`, `contextNeeded`, and `guardrails`\n- the first useful body paragraph as a fallback description\n- the parent directory name as a fallback skill name\n\nFor agents, the Lab inventory only exposes public metadata:\n\n- `name`\n- `description`\n- `scope`\n- `source`\n- `model`\n- `tools`\n\nIt does not return agent body text, Claude private transcripts, or conversation history. During scan/compile, LazyBrain parses local markdown files to build a capability graph; it does not execute the skill or agent.\n\nRecommended skill shape:\n\n```markdown\n---\nname: code-review\ndescription: Review code for correctness, regressions, maintainability, and missing tests.\ntriggers:\n  - review code\n  - 审查代码\nuseWhen: [\"review code changes\", \"check regression risk\"]\nworkflow: [{\"title\":\"Inspect changed files\"},{\"title\":\"Prioritize behavioral findings\"}]\nverification: [{\"title\":\"Run tests\",\"command\":\"npm test\"}]\ndoneWhen: [\"Findings are grounded in file evidence or tests pass\"]\ncontextNeeded: [\"diff or branch\", \"expected behavior\"]\nguardrails: [{\"title\":\"Lead with bugs and regressions\",\"strength\":\"strict\"}]\n---\n\nUse this skill when the user asks for a focused engineering review.\n```\n\nIf a skill does not appear in results, check that it is under a scanned skill path, has a `SKILL.md`, and includes a clear `name` or `description`.\n\n## Matching Engine / 匹配引擎\n\nWhen you type a prompt, LazyBrain uses the currently implemented routing layers in order:\n\n```\n  Prompt: \"帮我审查这个 PR\"\n       │\n       ▼\n  ┌─────────────────────────────────────────────────┐\n  │  Layer 0: Manual Alias                          │\n  │  Exact match? → Return immediately              │\n  │  e.g. \"review\" → /review-pr                    │\n  └─────────────────┬───────────────────────────────┘\n                    │ No match\n                    ▼\n  ┌─────────────────────────────────────────────────┐\n  │  Layer 1: Tag Matching                          │\n  │  CJK bigram + cross-language bridge              │\n  │  \"审查\" → expanded to [\"review\", \"audit\"]        │\n  │  \u003c1ms, fully offline                            │\n  └─────────────────┬───────────────────────────────┘\n                    │ Low confidence\n                    ▼\n  ┌─────────────────────────────────────────────────┐\n  │  Layer 2: Semantic / Hybrid                     │\n  │  Embedding cache required                       │\n  │  Falls back with warnings when cache is missing │\n  └─────────────────┬───────────────────────────────┘\n                    │ Build route contract\n                    ▼\n  ┌─────────────────────────────────────────────────┐\n  │  RouteSpec                                      │\n  │  route_plan / needs_clarification /             │\n  │  no_route_needed                                │\n  │  token strategy + verification guidance         │\n  └─────────────────────────────────────────────────┘\n```\n\n**Offline capable**: manual aliases and tag matching work without any network connection. `semantic` / `hybrid` requires embedding config plus `graph.embeddings.*` cache; when cache is missing, LazyBrain falls back to the lower layers and reports a warning.\n\nThe default hook does not run Secretary or inject full recommendations. Secretary/API checks are explicit through `lazybrain api test`; route planning stays advisory and compact.\n\n**支持离线**：手工别名和 tag-layer 不需要网络；`semantic` / `hybrid` 需要 embedding 配置和 `graph.embeddings.*` 缓存，缓存缺失时会降级并给出 warning。\n\n## Implemented vs Planned\n\n| Area | Current behavior | Notes |\n|------|------------------|-------|\n| Offline routing | Manual alias + tag/CJK bridge | Works without API keys |\n| Semantic / hybrid | Uses embedding cache when configured | Falls back with warnings when cache is missing |\n| Route plan | `lazybrain route` returns v1.4.5 `RouteSpec` | Includes `route_plan`, `needs_clarification`, and `no_route_needed` |\n| MCP | `lazybrain mcp --stdio` exposes read-only route/search/card/combo tools | Does not write target CLI config or return agent bodies |\n| Manual prompt | `lazybrain prompt` renders target-specific copyable guidance | Useful when MCP is not configured |\n| Combo templates | Built-in high-frequency orchestration templates | `lazybrain combos [category]` is read-only |\n| Hook install | Project scope tiny gate, dry-run plan, backup, rollback | Global install requires `--global --yes`; hook injects only a short reminder |\n| Lab | Built-in fixtures, local agent metadata, team gate, token strategy, hook readiness | Does not read Claude transcripts or install hooks |\n| Team guidance | Advisory model split, runtime adapters, subagent prompts | Main model or user keeps final decision |\n| Auto-alias | Suggest/read-only path today | Fully automatic promotion is still planned |\n\n## Continuous Adaptation\n\nLazyBrain can learn from usage patterns without treating every planned capability as already mature:\n\n```\n  ┌───────────────────────────────────────────────┐\n  │              Usage History                     │\n  │  \"审查代码\" → /code-review (accepted)          │\n  │  \"审查代码\" → /wiki (rejected!)                │\n  │  \"审查代码\" → /code-review (accepted)          │\n  └───────────────┬───────────────────────────────┘\n                  │ distill\n                  ▼\n  ┌───────────────────────────────────────────────┐\n  │  Rejection Learning                           │\n  │  wiki was rejected for \"审查代码\" queries      │\n  │  → auto-deprioritize wiki for similar queries │\n  ├───────────────────────────────────────────────┤\n  │  Auto-Alias Generation (planned)              │\n  │  repeated choices can become shortcuts        │\n  │  this is not treated as mature yet            │\n  ├───────────────────────────────────────────────┤\n  │  Tag Evolution                                │\n  │  Users search \"审查代码\" but tag is only       │\n  │  \"review\" → evolve adds \"审查\" as a new tag   │\n  ├───────────────────────────────────────────────┤\n  │  Task Chain Prediction                        │\n  │  After using /review-pr → suggest /refactor   │\n  │  (within current session only)                │\n  └───────────────────────────────────────────────┘\n```\n\n## Wiki and Graph Outputs\n\n`lazybrain compile` generates runtime artifacts under `~/.lazybrain/`. They are local machine outputs, not project-source files committed to this repo.\n\n```\n~/.lazybrain/wiki/\n├── index.md\n├── development.md\n├── operations.md\n├── orchestration.md\n└── ...\n```\n\nImportant details:\n\n- category files are generated from a **fixed category vocabulary** plus dynamic local classification\n- the number of generated category files depends on what actually exists in your local graph\n- counts in examples are **illustrative**, not guaranteed project constants\n- wiki pages cover **capabilities**, not just “tools”; that includes:\n  - skills\n  - agents\n  - commands\n  - other capability kinds that appear in the graph\n\nCurrent wiki output is category-centric:\n\n- `index.md` links to category pages\n- `kinds.md` groups capabilities by kind (`skill / agent / command / mode / hook`)\n- `origins.md` groups capabilities by source/origin (`local / ECC / OMC / plugin / external ...`)\n- each category page groups entries under `Skills`, `Agents`, `Commands`, and `Other`\n\nSo agents and commands are not missing; they are currently surfaced inside category pages rather than separate top-level indices.\n\n## Quick Start / 快速开始\n\n**Prerequisites / 前置条件**: Node.js ≥ 18\n\n```bash\n# Install from GitHub / 从 GitHub 安装\ngit clone https://github.com/papperrollinggery/lazy-brain.git\ncd lazy-brain\nnpm install\nnpm run build\nnpm link        # makes the `lazybrain` / `lb` commands global\n\n# Verify / 验证\nlazybrain --version\n```\n\n```bash\n# Setup / 初始化\nlazybrain scan                        # Scan local tools\nlazybrain compile --offline           # Build tag-layer graph without API key\nlazybrain ready                       # Check graph, hook, HUD, and semantic readiness\n\n# Non-install visual check / 非安装式可视化检查\nlazybrain ui                          # Opens http://127.0.0.1:18450/\nlazybrain route \"review this PR\"      # Advisory execution plan, no writes\n# lazybrain ui --no-open\n# open http://127.0.0.1:18450/lab\n\n# Install only after reviewing the plan / 审查预演后再安装\nlazybrain hook plan                   # Preview settings changes, no writes\nlazybrain hook install                # Install project-scoped Claude Code hook\n\n# Explicit global install / 显式全局安装\n# lazybrain hook install --global --yes\n\n# Roll back latest LazyBrain hook backup / 回滚最近一次 Hook 备份\n# lazybrain hook rollback\n```\n\nAfter hook install, prompts inside the recorded project workspace pass through the tiny gate. Complex, vague, or high-risk prompts get a short reminder to call LazyBrain; full plans are pulled through CLI/API/MCP.\n\n安装 hook 后，当前记录的项目工作区只经过 tiny gate。复杂、模糊或高风险任务会收到短提醒；完整计划由 CLI/API/MCP 拉取。\n\n`lazybrain hook install` writes project `.claude/settings.json` by default and creates a LazyBrain backup first. Global install is refused unless `--global --yes` is present.\n\n## Daily Usage\n\nUse these commands for the normal public flow:\n\n```bash\nlazybrain --version                  # Confirm the installed version\nlazybrain scan                       # Refresh local capabilities\nlazybrain compile --offline          # Build graph without an API key\nlazybrain match \"review this PR\"     # Test recommendation quality in terminal\nlazybrain route \"review this PR\"     # Build advisory RouteSpec plan\nlazybrain prompt \"review this PR\" --target claude\nlazybrain mcp status                 # Check MCP readiness\nlazybrain ready                      # Check graph, hook, HUD, and semantic readiness\nlazybrain ui                         # Open the local GUI\nlazybrain hook plan                  # Preview hook changes\nlazybrain hook install               # Install project-scoped hook\n```\n\nUse the GUI before hook install when you want a visual check:\n\n```bash\nlazybrain ui\nopen http://127.0.0.1:18450/lab\n```\n\nUse rollback when hook behavior is not what you expected:\n\n```bash\nlazybrain hook rollback\nlazybrain hook status\n```\n\n## Configuration / 配置\n\n```bash\n# Optional / 可选：LLM compile（OpenAI-compatible）\nlazybrain config set compileApiBase https://api.siliconflow.cn/v1\nlazybrain config set compileApiKey  \u003cyour-key\u003e\nlazybrain config set compileModel   Qwen/Qwen3-235B-A22B-Instruct-2507\n\n# Optional / 可选：semantic / hybrid matching\nlazybrain config set embeddingApiBase https://api.siliconflow.cn/v1\nlazybrain config set embeddingApiKey  \u003cyour-key\u003e\nlazybrain config set embeddingModel   BAAI/bge-m3\nlazybrain config set engine           hybrid\nlazybrain api test                    # Explicit external API check\nlazybrain embeddings status           # Read-only cache coverage check\nlazybrain embeddings rebuild --yes    # Writes ~/.lazybrain/graph.embeddings.*\n\n# Optional / 可选：Secretary LLM（可回退到 compile key）\nlazybrain config set secretaryApiKey  \u003cyour-key\u003e\nlazybrain config set secretaryModel   Qwen/Qwen2.5-7B-Instruct\n\n# UI mode / 界面模式\nlazybrain config set mode auto        # Auto-inject (silent)\n# lazybrain config set mode ask       # Show selection UI\n```\n\nConfig file / 配置文件：`~/.lazybrain/config.json`\n\n`lazybrain config show` redacts API keys in terminal output.\n\n## Commands / 命令\n\n### Matching / 匹配\n\n```bash\nlazybrain match \"重构这段代码\"       # Find matching tools\nlazybrain find  \"代码审查\"           # Alias for match\nlazybrain route \"把后台改成 CEO dashboard\"\nlazybrain route \"review this PR\" --target codex\nlazybrain route \"review this PR\" --json\nlazybrain route stats\nlazybrain prompt \"review this PR\" --target claude\nlazybrain prompt \"review this PR\" --target codex --copy\nlazybrain mcp status\nlazybrain mcp --stdio\nlazybrain combos frontend\n```\n\n`lazybrain route` upgrades raw matches into an advisory `RouteSpec`: `schemaVersion`, `mode`, scenario, skills, token strategy, context needed, workflow, guardrails, verification, done conditions, and a target-specific prompt style for `generic`, `claude`, `codex`, or `cursor`.\n\nRoute modes:\n\n- `route_plan`: use LazyBrain's top-K compact skill plan.\n- `needs_clarification`: ask clarifying questions before loading skills.\n- `no_route_needed`: handle the task directly; do not spend routing context.\n\n`lazybrain prompt` renders the same plan as a copyable target prompt. `lazybrain mcp --stdio` exposes read-only tools: `lazybrain.route`, `lazybrain.search`, `lazybrain.skill_card`, and `lazybrain.combos`. These surfaces do not execute skills, install hooks, read transcripts, return agent bodies, or write Claude/Codex/Cursor configuration.\n\n### Management / 管理\n\n```bash\nlazybrain scan                       # Re-scan tools\nlazybrain compile                    # Recompile knowledge graph\nlazybrain compile --force            # Force full recompile\nlazybrain compile --offline          # Compile without LLM (tag-based only)\nlazybrain list                       # List all tools\nlazybrain stats                      # Graph statistics\nlazybrain ready                      # Check graph, hook, HUD, and semantic readiness\nlazybrain ui                         # Start local Web GUI\nlazybrain server --daemon            # Start local API server directly\n```\n\n### Local Web GUI / 本地 GUI\n\n```bash\nlazybrain ui\nlazybrain ui --no-open\nlazybrain ui --port 18451\nlazybrain ui status\nlazybrain ui stop\n```\n\nGUI entrypoints:\n\n- `GET /` and `GET /ui` — local status GUI\n- `GET /lab` — non-install recommendation Lab\n- `GET /api/status` — readiness, graph, routing, hook, API, embedding, agent, and server status\n- `POST /api/route` — advisory route plan; no execution and no target CLI config writes\n- `POST /api/test` — explicit API test only after user action\n- `POST /api/embeddings/rebuild` — requires `{ \"confirm\": \"rebuild\" }`\n\nGUI v1 is status-first: it does not read Claude transcripts, return agent body text, install hooks, or write `.claude/settings.json`.\n\n### Lab / Non-install visual testing\n\n```bash\nlazybrain server --daemon\nopen http://127.0.0.1:18450/lab\n```\n\nThe Lab uses built-in fixtures to inspect matching quality, team gating, token strategy, hook readiness, and Claude/Agent Agency subagent mapping without installing hooks or writing Claude settings.\n\nLab endpoints:\n\n- `GET /lab` — self-contained local HTML page\n- `GET /lab/fixtures` — built-in evaluation cases\n- `GET /lab/agents` — local agent metadata only: name, description, scope, source, model, tools\n- `POST /lab/evaluate` — match, team guidance, runtime adapters, token strategy, hook readiness, and warnings\n\nThe agent inventory scanner does not return agent body text and does not read Claude private transcripts.\n\n### Evolution / 演化（从使用中学习）\n\n```bash\nlazybrain suggest-aliases            # Show suggested aliases (read-only)\nlazybrain evolve                     # Learn new tags from usage patterns\nlazybrain evolve --dry-run           # Preview what evolve would do\nlazybrain evolve --rollback          # Undo last evolution\n```\n\n### Hook / Hook 安装\n\n```bash\nlazybrain hook plan                  # Preview hook install, no writes\nlazybrain hook install               # Install Claude Code hook\nlazybrain hook install --global --yes # Explicit confirmed global install\nlazybrain hook rollback              # Restore latest LazyBrain hook backup\nlazybrain hook uninstall             # Uninstall hook\nlazybrain hook status                # Check hook status\nlazybrain hook status --json         # Machine-readable runtime status\nlazybrain hook ps                    # Show active hook runs\nlazybrain hook clean                 # Clean stale hook records\nlazybrain doctor                     # Diagnose LazyBrain runtime state\nlazybrain doctor --fix               # Repair LazyBrain-only state drift\nlazybrain doctor --all               # Report project and global scopes, no fix\n```\n\n### Hook Safety / Hook 安全模型\n\n- `lazybrain hook install` now defaults to **project scope**\n- `lazybrain hook plan` previews the target settings path, lifecycle hooks, third-party hooks, statusline handling, install-state path, and risk conclusion without writing `.claude/settings.json` or `~/.lazybrain/*`\n- `lazybrain hook install` creates a LazyBrain backup before writing settings\n- `lazybrain hook rollback` restores only files that LazyBrain backed up\n- `lazybrain hook install --global` is refused unless `--yes` is also present\n- runtime tiny gate only applies inside the recorded workspace root\n- if a prompt comes from another cwd, LazyBrain returns no-op immediately\n- the default hook does not run Secretary, wiki-card generation, full matching output, or agent/team expansion\n- high load, concurrency limit, breaker, missing graph, and non-`UserPromptSubmit` events fail closed with no user-facing delay\n- `Stop` is still outside the product lifecycle\n- third-party hooks and mixed hook entries are preserved\n- existing third-party HUD/statusline is skipped by default; `--statusline` combines, `--replace-statusline` replaces\n- `doctor --fix` only repairs **LazyBrain's own state**\n  - hook registration normalization\n  - stale runtime record cleanup\n  - breaker reset\n  - install metadata repair when metadata already exists\n- `doctor --fix` does **not** modify third-party plugins or system services\n- `doctor --all --fix` is disabled to avoid cross-scope writes\n\n### Uninstall and Rollback / 卸载与回滚\n\n```bash\nlazybrain hook uninstall              # Remove LazyBrain hook registration\nlazybrain hook rollback               # Restore latest LazyBrain backup\nlazybrain hook rollback --to \u003cid\u003e     # Restore a specific backup timestamp\n```\n\nRollback restores only files that were captured by LazyBrain backups. It does not delete third-party hook files.\n\n### What It Will Not Do / 默认不会做什么\n\n- no global hook install by default\n- no `Stop` lifecycle dependency\n- no third-party hook deletion\n- no third-party HUD overwrite by default\n- no config writes during `hook plan`\n- no silent semantic claim when embedding cache is missing\n- no full skill body injection from the hook\n\n## Troubleshooting\n\n| Symptom | Check | Fix |\n|---------|-------|-----|\n| `lazybrain ready` says graph is missing | `~/.lazybrain/graph.json` does not exist | Run `lazybrain scan \u0026\u0026 lazybrain compile --offline` |\n| GUI or Lab page does not open | Server is not running or port is different | Run `lazybrain ui`, or `lazybrain ui --port 18451` |\n| Lab shows no agents | No readable agent metadata found | Add project agents under `.claude/agents/` or user agents under `~/.claude/agents/`, then refresh Lab |\n| `hook plan` reports `needs_attention` because of LazyBrain in `Stop` | Older LazyBrain hook registration remains | Review the plan; `lazybrain hook install` will clean LazyBrain-owned `Stop` entries |\n| `hook install --global` fails | Global install requires explicit confirmation | Use `lazybrain hook install --global --yes` only if you want every Claude project affected |\n| Hook is installed but no recommendation appears | v1.4.5 hook is a tiny gate, not a full recommender | Run `lazybrain hook status --json`; test the full plan with `lazybrain route \"\u003csame query\u003e\"` |\n| Main model ignores LazyBrain | MCP is not configured or the task looked trivial | Use `lazybrain prompt \"\u003csame query\u003e\" --target claude`, or configure `lazybrain mcp --stdio` in the client |\n| Hook seems stuck or returns no output after a long run | Runtime breaker or stale record may be active | Run `lazybrain hook ps`, then `lazybrain hook clean`, then `lazybrain ready` |\n| Third-party HUD/statusline is present | LazyBrain skips it by default | Use `lazybrain hook install --statusline` to combine, or `--replace-statusline` only when you intentionally want replacement |\n| `lazybrain api test` reports 401 | API key is invalid or not accepted by the configured base/model | Reset the key with `lazybrain config set ...ApiKey \u003ckey\u003e` and rerun `lazybrain api test` |\n| semantic/hybrid does not improve matches | Embedding config or cache is missing/stale/dimension-mismatched | Run `lazybrain embeddings status`; rebuild with `lazybrain embeddings rebuild --yes` after config is correct |\n| A skill is missing from results | The skill path or metadata is incomplete | Ensure the skill has `SKILL.md` with `name` or `description`, then run `lazybrain scan` |\n\nSafe recovery commands:\n\n```bash\nlazybrain ready\nlazybrain hook status\nlazybrain hook status --json\nlazybrain hook ps\nlazybrain hook clean\nlazybrain hook rollback\nlazybrain doctor\nlazybrain api test\nlazybrain embeddings status\nlazybrain route stats\nlazybrain mcp status\n```\n\n`doctor --fix` only repairs LazyBrain-owned state in the current scope. `doctor --all --fix` is intentionally disabled.\n\n### Smoke Test / 冒烟测试\n\nValidates the full install path from fresh clone to hook interception:\n\n```bash\n./scripts/smoke-test.sh\n```\n\nThe smoke test verifies / 这个测试会验证：\n- `npm ci \u0026\u0026 npm run build` succeeds\n- `lazybrain ready` reports the current readiness state\n- `lazybrain hook plan` previews install changes without writing settings\n- `lazybrain hook install` correctly modifies project `.claude/settings.json`\n- `lazybrain scan \u0026\u0026 lazybrain compile` produces `~/.lazybrain/graph.json`\n- Hook returns the tiny route reminder for a complex test prompt\n- `lazybrain hook rollback` restores the latest LazyBrain backup\n\nSee [`scripts/smoke-test.sh`](scripts/smoke-test.sh) for the full test implementation.\n\n### Release and Review Gate\n\nRequired before release PRs:\n\n```bash\nnpm ci\nnpm run build\nnpm test\nnpm run lint\nnpm run audit:public\nnpm pack --dry-run --json\n```\n\nThe stable required GitHub check is `Test`. It runs Node 18/20/22, package dry-run, public privacy scan, version consistency checks, hook-focused tests, and Lab/server smoke.\n\nPublic package contents are limited to `dist`, `README.md`, `README_CN.md`, `CHANGELOG.md`, `LICENSE`, and package metadata. npm publishing is handled by the GitHub Release workflow.\n\nOptional Codex review instructions are in [`docs/REVIEW.md`](docs/REVIEW.md).\n\n#### MCP and Manual Fallback\n\nUse MCP when the primary model should pull structured advice itself:\n\n```bash\nlazybrain mcp status\nlazybrain mcp --stdio\n```\n\nUse prompt output when MCP is not configured:\n\n```bash\nlazybrain prompt \"review this PR\" --target claude\nlazybrain prompt \"debug this stuck hook\" --target codex --copy\n```\n\n`lazybrain hook install` installs `UserPromptSubmit` only and automatically removes stale LazyBrain `Stop` registrations left by older versions. The default hook is a tiny reminder gate; it does not run the old startup dashboard, Secretary path, or full recommendation injection.\n\n### Config\n\n```bash\nlazybrain config show                # Show current redacted config\nlazybrain config set \u003ckey\u003e \u003cval\u003e     # Set config value\n```\n\n## Data Directory\n\n```\n~/.lazybrain/\n├── config.json           # Configuration\n├── graph.json            # Knowledge graph (local capability graph)\n├── graph.embeddings.bin  # Semantic vector cache\n├── graph.embeddings.index.json\n├── hook-install-map.json # Project/global hook install metadata\n├── history.jsonl         # Usage history\n├── profile.json          # Distilled user profile\n├── last-match.json       # Latest match result\n└── wiki/                 # Capability wiki indices and category pages\n```\n\n## Source Structure\n\n```\nsrc/\n├── scanner/          # Tool discovery \u0026 parsers (skill/agent/command)\n├── compiler/         # LLM tag generation \u0026 category classification\n├── graph/            # Graph CRUD \u0026 wiki generation\n├── matcher/          # Matching engine\n│   ├── alias-layer.ts     # Layer 0: manual aliases\n│   ├── tag-layer.ts       # Layer 1: keyword + CJK bigram\n│   ├── embedding-layer.ts # Layer 2: semantic/hybrid cache\n│   └── matcher.ts         # Orchestrator + history boost + corrections\n├── lab/              # Non-install Lab UI, fixtures, agent inventory, evaluator\n├── hook/             # Hook planning, install safety, rollback, readiness\n├── server/           # Local HTTP API and Lab routes\n├── secretary/        # Hook LLM second-pass judgment\n├── history/          # Usage tracking \u0026 profile distillation\n├── evolution/        # Tag evolution engine\n├── config/           # Configuration management\n└── utils/            # CJK bridge, progress, YAML\n```\n\n## Benchmark\n\n| Mode | Top-1 | Top-3 |\n|------|-------|-------|\n| Route pipeline (tag + optional semantic) | varies by local graph | varies by local graph |\n| Tag-only (offline) | baseline local match quality | baseline local match quality |\n\nBenchmark results depend on:\n\n- what capabilities exist on the current machine\n- whether offline or LLM-assisted compile was used\n- whether semantic cache is configured and current\n- which evaluation set is being used\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpapperrollinggery%2Flazy-brain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpapperrollinggery%2Flazy-brain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpapperrollinggery%2Flazy-brain/lists"}