Beevibe AI CTO

The decision layer your coding agents are missing.

The full loop, from architecture decision through PR review:

The brain + adr drift close the rest of the loop; upcoming.

Install

Three ways in. All share the same kernel.

Claude Code plugin — recommended

claude plugin marketplace add beevibe-ai/architecture-deep-research
claude plugin install adr

Then in any Claude Code session:

MCP server — Cursor, Codex, any MCP host

npm install -g github:beevibe-ai/architecture-deep-research
adr-doctor setup

Add to your host's MCP config:

{ "mcpServers": { "adr": { "command": "adr-mcp" } } }

Five tools become available: adr_discover, adr_deep_research, adr_read_handoff, adr_principles, adr_review.

CLI — terminal, CI, GitHub Action

npm install -g github:beevibe-ai/architecture-deep-research
adr-doctor                       # audit env, exit non-zero if anything missing

Run your first decision

adr deep-research --discover-first --include-peers --open \
  --repo . \
  --domain "your product domain" \
  --decision "vector store for agent memory" \
  --out .adr-runs/vector-store

What this does:

1. Discover scans your repo for stack signals, patterns the team follows, and antipatterns the team has explicitly rejected.
2. Peer-finder names 3-5 similar products. Open-source peers (Neo4j, Onyx) get read through their repos and engineering blogs. Closed-source peers (Notion, Obsidian, Mem.ai) get read through Reddit, HN, Twitter — what users actually report.
3. Research collects live evidence, builds a comparison matrix, runs adversarial probes against every candidate.
4. Synthesis writes the research report. Citation + claim audits run automatically.
5. --open renders ADR.md as HTML (mermaid diagrams as SVG, tables, dark/light mode) and opens it in your default browser.

A typical run takes 3-6 minutes and costs $0.10-$0.30 in API spend. Use --dry-run to see the plan + cost estimate without spending tokens.

After the report

# Open the report later — or after a run that didn't use --open
adr open .adr-runs/vector-store

# Pick an option from the report and generate its implementation contract
adr handoff .adr-runs/vector-store --option pgvector

# Resume a crashed or interrupted run (reuses cached evidence.json — the expensive part)
adr resume .adr-runs/vector-store

The report at <out_dir>/ADR.md has:

• Executive Summary + Option Space table
• One section per candidate: evidence depth (thick / medium / thin), what the evidence shows, what it doesn't, pick-when / avoid-when reading aids, citations
• Cross-Cutting Tradeoffs across matrix axes
• Open Questions the evidence pool didn't resolve
• Where to Dig Deeper — pre-filled adr deep-research commands for the next iteration

The decision becomes a tree of ADR runs. Each one drills into the highest-uncertainty axis from the prior run.

Keep the implementation honest — principles, review, guard

Decisions don't survive contact with the codebase. The senior engineer who knows what your team standardized on becomes the only memory — repeating the same review comment to 10 different juniors, every week.

Three commands close that loop:

# Step 1: discover what the team's conventions actually are (run once per repo)
adr principles init                    # scans the repo, interviews you, writes .adr/principles.{md,json}

# Step 2: check a PR against those principles
adr review 42                          # GitHub PR
adr review --staged                    # pre-commit local
adr review --branch main               # current branch vs base

# Step 3: wire the principles into your workflow so they fire automatically
adr guard install                      # PreToolUse hook + git pre-commit

adr principles init uses the LLM end-to-end — no hardcoded lens taxonomy. It samples real source files from your repo, asks the model to surface the code-review angles a senior would catch (state boundaries, schema-validate-before-write, CLI patterns, test-fixture discipline, ownership routing…), extracts positive patterns + antipatterns + ambiguities with file:line citations, then walks you through an interactive interview to confirm. A cite-or-die filter drops any path the model invented — only principles backed by real lines on disk survive.

adr review loads the principles + a unified diff (PR / staged / branch / arbitrary diff file / stdin), groups hunks by file, runs one LLM call per file to detect violations, ranks by severity, and walks you through accept/edit/skip one at a time. Approved comments post via gh pr review with the team's own example cited as "follow this".

adr guard install wires two hooks:

• Claude Code PreToolUse — every Edit/Write/MultiEdit, the hook filters principles to ones relevant to the file's top-level dir (no LLM call on the hot path) and injects them into the agent's context. The agent sees the team's conventions before it generates the violation.
• Git pre-commit — runs adr review --staged --top-n 5. HIGH-severity violations block the commit; medium/low are advisory.

All three operate on the same .adr/principles.json artifact. Re-run adr principles init whenever the team's posture shifts; review and guard pick up the new rules automatically.

API keys

adr-doctor setup walks you through these interactively and stores them in ~/.adr/config.json (mode 0600). Process env always overrides the file.

Required (at least one of each):

If no dedicated search key is set, ADR falls back to OpenAI's hosted web_search — one key powers both research and synthesis.

Optional:

• GITHUB_TOKEN — strongly recommended. Lifts the GitHub API limit from 60/hr to 5000/hr.
• ADR_MODEL — override the default model (gpt-4.1-mini).
• ADR_OPENAI_BASE_URL — point at a local OpenAI-compatible server (vLLM, LM Studio, llamafile, Ollama).
• ADR_SEARCH_INCLUDE_DOMAINS / ADR_SEARCH_EXCLUDE_DOMAINS — bias the evidence pool toward / away from specific domains.
• ADR_MCP_SERVER_URL + ADR_PRIVATE_MCP_ONLY — search a read-only private MCP corpus instead of the public web.

What ADR produces

A run's <out_dir>/ contains:

After adr handoff --option <name>:

Verify your install

npm test

Six suites run locally — kernel regression, search provider, schema check, framework + web + MCP smoke. No network calls; green here means the wiring is intact.

To exercise the live loop:

adr-doctor                       # confirm READY
adr deep-research --discover-first --open \
  --repo . --domain "test" --decision "retrieval topology" \
  --out .adr-runs/self-test

Status

Shipped:

• ADR flagship — adr decide, adr discover, adr open, adr handoff, adr resume, adr supersede. Live agentic research kernel, peer discovery, community sources, citation + claim audits, Mermaid diagrams, HTML report, crash-aware state.
• adr principles init — LLM-discovered code-review lenses, per-lens patterns + antipatterns, interactive interview, cite-or-die filter. Writes .adr/principles.{md,json}.
• adr review — PR / staged / branch / file modes. Walks the user through violations one at a time, posts inline comments via gh pr review citing the team's own file:line as the example to follow.
• adr guard — Claude Code PreToolUse hook (write-time principle injection) + git pre-commit (blocks high-severity violations). Pure file-based filter on the hot path; idempotent install.
• Adapters + UI — LangGraph and Google ADK (same kernel, same artifacts). Web UI (adr-web) for live operator / developer views.
• Claude Code plugin — six slash commands: /adr:doctor, /adr:decide, /adr:discover, /adr:principles, /adr:review, /adr:guard.

In development:

• The brain — always-on knowledge graph that watches voices, trending OSS, competitor architecture, and papers. Personalized to your stack via your PRD + past ADR runs + discovered principles. Markdown-in-git source of truth (Obsidian-compatible) + derived Postgres+pgvector indexes; LLM maintains the wiki, watchers ingest sources continuously.
• adr drift <out_dir> — periodic scan against the saved spec, reports drift by file:line.

Open-source core under Apache-2.0. The commercial Beevibe surface layers curated corpora, managed researcher agents, org-level memory, and team governance on top.

Learn more

• See an example report — real run on a Beevibe decision, rendered the same way adr open would render yours.
• ADR introduction — the layer before the coding agent.
• Questions teams keep asking — Q&A on the design.
• The dogfooding journey — what made us pivot from a decision engine to a research-report engine.
• docs/ — framework adapters, web UI, schemas, mesh integration, full flag reference.