Buddhi AI CLI

Buddhi AI CLI turns a codebase into what an AI coding agent actually needs: a code graph (files, directories, classes, functions/methods, and their containment/import/call relationships, via tree-sitter), a Model Context Protocol (MCP) server for topology-aware code search and compressed reading, a scaffolded Google Antigravity agent harness grounded in that graph, and a full Spec-Driven Development (SDD) lifecycle based on open standards like AGENTS.md.

The idea: point Buddhi AI CLI at a project, and it gives Antigravity:

• A workspace MCP Server (buddhi-mcp) exposing:
  • buddhi_search — Community-aware, topology-driven code graph search across lexical anchors and bridge nodes.
  • buddhi_read — AST-pruned, entropy-filtered, token-budget-aware file reading (auto, signatures, map, entropy, full).
• A full Spec-Driven Development (SDD) workflow:
  1. /specify — Scaffold feature branch and refine spec.md with prioritized, testable user stories.
  2. /plan — Synthesize architectural design into plan.md via domain specialists and AGENTS.md compliance checks.
  3. /tasks — Generate a phased, story-oriented task breakdown into tasks.md with [P] parallelism markers.
  4. /implement — Execute tasks with prerequisite validation and live progress tracking in tasks.md.
  5. /verify — Evidence-based test execution mapping results to specification acceptance criteria (SDD convergence mode).
• A /quick-plan workflow for lightweight, non-SDD multi-specialist planning.
• An /ask workflow for interactive codebase comprehension and architectural Q&A grounded in the code graph.
• A /document-codebase workflow that generates dependency-aware OKF symbol documentation.
• Specialized /debug, /remember, and /status workflows for systematic root-cause investigation, persistent memory capture, and harness dashboarding.
• Domain specialist agents (frontend, backend, database, testing, security, deployment, git) and terminal-runner for delegated command execution.

Supported languages: Python, JavaScript, TypeScript/TSX, Go, Rust, C#, Java, Kotlin, Swift.

Installation

Requires Python 3.10+.

pip install "buddhi-ai[mcp]"

Or, if you prefer an isolated tool install:

pipx install "buddhi-ai[mcp]"
# or
uv tool install "buddhi-ai[mcp]"

This installs both the buddhi CLI command and the buddhi-mcp Stdio server entrypoint.

Usage

buddhi init — full setup (recommended)

buddhi init [path]

Scans path (defaults to the current directory), builds the code graph, computes a documentation plan, scaffolds the root AGENTS.md, and prepares the Antigravity agent harness. Writes:

• AGENTS.md — standard project instructions, dev commands, and architecture rules at the project root (created if not already present)
• .buddhi/graphs/tree-graph.json — the graph in Cytoscape.js elements format
• .buddhi/graphs/tree-graph.db — a SQLite database (nodes/edges tables, indexed for recursive CTE traversal — ancestor/descendant lookups, call-graph walks)
• .buddhi/graphs/tree-graph.html — an interactive Cytoscape.js visualization (loads Cytoscape.js from a CDN; open in a browser with internet access)
• .buddhi/docs-plan.json — a bottom-up, staleness-aware plan of what needs documenting
• .agents/mcp_config.json — workspace MCP server configuration registering buddhi-mcp with Antigravity IDE, pre-configured with the workspace root directory (--root) so agents only need to pass query
• .agents/ — the Antigravity agent harness (agents, workflows, rules, skills, templates, memory index — see below). Idempotent: rerunning init never overwrites a harness file you've already edited under .agents/, it only fills in what's missing.

A .buddhi/.gitignore (ignoring graphs/ and docs/) is created on first run so generated artifacts don't get committed to your project's own repo.

Next step printed at the end: open the project in Antigravity, run /document-codebase, and start a feature with /specify.

buddhi mcp — Model Context Protocol server

buddhi mcp [--db-path <path>] [--root <path>]
# or run the dedicated entrypoint directly:
buddhi-mcp [--db-path <path>] [--root <path>]

Runs the Buddhi Model Context Protocol (MCP) server over StdIO, allowing AI coding agents to dynamically query the code graph and read compressed files:

• buddhi_search: Topology-aware codebase search. Uses lexical anchors, expands into community neighborhoods, filters boilerplate using Shannon entropy, and sorts results using a U-curve positional layout within a token/character budget.
• buddhi_read: Dynamic, AST-pruned file reading with multiple compression modes (auto, signatures, map, entropy, full) and token-budget awareness to prevent context window saturation.

Passing --root <path> anchors SQLite database resolution (<root>/.buddhi/graphs/tree-graph.db), fallback relative filepaths, and native grep lookups to the specified repository root. The MCP server is scoped per-workspace with zero port conflicts.

buddhi generate — update / refresh code graph

buddhi generate [path]

Scans path and rebuilds all three graph artifacts under .buddhi/graphs/ (tree-graph.json, tree-graph.db, tree-graph.html) without modifying .buddhi/docs-plan.json or .agents/. Use this whenever the codebase grows or changes to update the SQLite graph database queried by the Buddhi MCP server (buddhi_search and buddhi_read).

buddhi docs plan — refresh documentation plan

buddhi docs plan [path]

Recomputes .buddhi/docs-plan.json against the current source tree without touching .agents/ or overwriting existing graph files. This detects newly added or modified source files and marks stale OKF docs for (re)generation. This is what /document-codebase and /plan Antigravity workflows call automatically before planning.

[!TIP] Rerunning buddhi init: You can also rerun buddhi init at any time to refresh both the graph and the documentation plan in one step. buddhi init is fully idempotent: it never overwrites your existing or customized files in .agents/ or AGENTS.md.

buddhi sdd — Spec-Driven Development CLI helpers

buddhi sdd <command> [options]

Underlying helper commands used by the SDD workflows:

• buddhi sdd create <description> — Create a new feature directory under .buddhi/specs/<branch>/, create branch name, and instantiate spec.md from template.
• buddhi sdd setup-plan — Set up plan.md for the active feature branch from plan-template.md.
• buddhi sdd setup-tasks — Verify prerequisites and output task resolution context for tasks.md.
• buddhi sdd check — Consolidated prerequisite checker supporting --require-tasks, --include-tasks, --paths-only, and --json.
• buddhi sdd resolve-template <name> — Resolve and compose templates across .agents/templates/ and built-in defaults.

The Antigravity agent harness

buddhi init scaffolds .agents/ with:

• workflows/
  • /ask — Conversational codebase Q&A workflow: runs buddhi generate via terminal-runner to update the code graph, then queries buddhi_search and buddhi_read to explain architecture, symbols, and dependencies with exact file:line citations without modifying files.
  • /specify — Initialize a new feature branch (refreshes graph via buddhi generate first), scaffold .buddhi/specs/<branch>/spec.md, and iteratively refine requirements into prioritized, independently testable user stories (P1, P2...).
  • /plan — Spec-Driven Development architecture workflow: verifies spec.md, resolves plan-template.md, dispatches domain specialists in parallel, checks AGENTS.md compliance, and synthesizes .buddhi/specs/<branch>/plan.md.
  • /tasks — Break down spec.md and plan.md into actionable, phased tasks organized by user story into tasks.md with [P] parallelism markers.
  • /implement — Enforce prerequisite checks (spec.md + plan.md + tasks.md) and execute tasks story by story, tracking completion directly in tasks.md.
  • /verify — Repurposed verification workflow: runs real build/lint/test commands via terminal-runner and maps evidence to user story acceptance criteria (SDD convergence mode), with fallback to general verification for ad-hoc changes.
  • /quick-plan — Lightweight implementation planning for requests that do not require full SDD branching/spec overhead (refreshes graph via buddhi generate first).
  • /document-codebase — Generate or refresh OKF symbol documentation bottom-up.
  • /debug — Systematic bug investigation (refreshes graph via buddhi generate first) producing a confirmed root cause and concrete fix plan without modifying code.
  • /remember — Capture user preferences, project conventions, and technical decisions into memory.
  • /status — Dashboard of harness state (docs staleness, active plans, memory size, git branch).
• mcp_config.json — Auto-connects Antigravity to the workspace's buddhi-mcp server so agents have direct access to buddhi_search and buddhi_read.
• templates/ — Standard templates for specifications (spec-template.md), implementation plans (plan-template.md), task lists (tasks-template.md), review checklists (checklist-template.md), and agent configurations (agents-template.md).
• agents/ — Read-only specialist subagents (backend-specialist, frontend-specialist, database-specialist, testing-specialist, security-specialist, deployment-specialist, git-specialist) dispatched in parallel by /plan and /quick-plan, plus terminal-runner for delegated shell/build/test execution.
• rules/ — Always-on conventions: consult .buddhi/docs/ and Buddhi MCP code graph tools before raw source, require confirmation before destructive commands, read/append to the memory index for durable decisions.
• hooks.json / hooks/guard_destructive.py — A PreToolUse hook that mechanically denies destructive commands (force-push, reset --hard, DROP/TRUNCATE, disk-format commands, etc.) as a safety backstop.
• skills/ — okf-context (how to read OKF docs and use Buddhi MCP code graph tools buddhi_search and buddhi_read), repoagent-doc-generation (how to write docs), system-design (an architecture/trade-off decision framework used during planning), and custom skill slots (see .agents/skills/README.md).
• memory/MEMORY.md — A structured index into topic files under .agents/memory/ (user-preferences.md, project-conventions.md, tech-decisions.md, feedback-history.md).

Documentation format

Generated docs under .buddhi/docs/ follow the Open Knowledge Format (OKF): one concept file per module/class/function, each carrying frontmatter that names its source file and line range, a content hash for staleness detection, and a status. The bottom-up generation order — document a symbol only after everything it depends on is already documented — is inspired by the RepoAgent paper's approach to whole-repository, dependency-aware documentation.

Notes on accuracy

Import and call resolution is best-effort, not a full semantic analysis: same-project relative imports and same-file/self./this. calls are resolved to real nodes; everything else (external packages, ambiguous cross-file calls, ...) becomes an external placeholder node so the graph stays informative without producing false edges.

Contributing

The sections below are for working on Buddhi AI CLI itself, not for using it.

Setup

uv sync

Once dependencies are installed, run the CLI from source with uv run, e.g. uv run buddhi init [path], instead of the plain buddhi command shown above.

Development

uv run pytest
uv run ruff check src tests
uv run mypy src

Publishing

Releases to PyPI are handled by the publish.yml GitHub Actions workflow. It builds the package with uv build and publishes it using PyPI trusted publishing (OIDC), so no API token is stored in the repository.

The workflow triggers on any pushed tag matching v* (e.g. v0.1.0). To cut a release:

1. Bump version in pyproject.toml.
2. Commit the change and tag it to match, e.g.:

   git commit -am "Bump version to 0.1.1"
   git tag v0.1.1
   git push origin main v0.1.1
   

3. The tag push triggers the workflow, which builds and publishes the package to PyPI automatically.

This requires a trusted publisher to be configured once on PyPI for the buddhi-ai project, pointing at this repository, the publish.yml workflow file, and the pypi environment.