Buddhi AI CLI

Buddhi AI CLI turns a codebase into two things an AI coding agent actually needs: a code graph (files, directories, classes, functions/methods, and their containment/import/call relationships, via tree-sitter) and a scaffolded Google Antigravity agent harness that's grounded in that graph instead of generic advice.

The idea: point Buddhi AI CLI at a project, and it gives Antigravity a /plan workflow with domain specialist agents (frontend, backend, database, testing, security, deployment, git), a /document-codebase workflow that generates real per-symbol documentation, and /verify, /debug, /remember, and /status workflows for evidence-backed testing, systematic debugging, explicit memory capture, and a harness state dashboard — all reading from Buddhi AI CLI's graph and docs instead of re-deriving understanding from raw source every time.

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

Installation

Requires Python 3.10+.

pip install buddhi-ai

Or, if you prefer an isolated tool install:

pipx install buddhi-ai
# or
uv tool install buddhi-ai

This installs the buddhi command.

Usage

buddhi init — full setup (recommended)

buddhi init [path]

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

• .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/ — the Antigravity agent harness (agents, workflows, rules, skills, 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 and run /document-codebase, then /plan.

buddhi generate — graph only

buddhi generate [path]

Scans path and writes just the three graph artifacts under .buddhi/graphs/, without touching .buddhi/docs-plan.json or .agents/. Useful for refreshing the graph on its own, or in contexts that don't need the Antigravity harness.

buddhi docs plan — refresh the doc plan only

buddhi docs plan [path]

Recomputes .buddhi/docs-plan.json against the current source tree without touching .agents/. This is what the /document-codebase and /plan Antigravity workflows call before doing anything else, so the plan always reflects the current source.

The Antigravity agent harness

buddhi init scaffolds .agents/ with:

• workflows/ — /document-codebase (generate or refresh docs), /plan (turn a request into an implementation plan grounded in the real codebase, without writing any code), /verify (run the project's real build/lint/test commands and report genuine pass/fail evidence), /debug (systematic investigation producing a confirmed root-cause and fix plan, plan-only like /plan), /remember (explicit, user-invocable capture of a preference/convention/decision into memory), and /status (a dashboard of the harness's own docs/graph staleness, open plans, and memory size — not live agent sessions or a preview server)
• agents/ — read-only specialist subagents (backend-specialist, frontend-specialist, database-specialist, testing-specialist, security-specialist, deployment-specialist, git-specialist) dispatched in parallel by /plan, plus terminal-runner for delegated shell/build/test execution
• rules/ — always-on conventions: consult .buddhi/docs/ and the code graph before raw source, require confirmation before destructive commands, read/append to the memory index for durable decisions
• hooks.json / hooks/guard_destructive.py — a real PreToolUse hook that mechanically denies destructive commands (force-push, reset --hard, DROP/TRUNCATE, disk-format commands, etc.) as a backstop to the rule above, not just an advisory — though Antigravity's hook-firing reliability is reportedly better in the CLI than in the IDE (per community reports), so treat this as a backstop, not a guarantee, in every environment
• skills/ — okf-context (how to read the generated docs), repoagent-doc-generation (how to write them), system-design (an architecture/trade-off decision framework used by /plan), and a slot for tech-stack-specific skills you drop in yourself (see .agents/skills/README.md)
• memory/MEMORY.md — a pure index into four topic files under .agents/memory/ (user-preferences.md, project-conventions.md, tech-decisions.md, feedback-history.md), populated passively across /plan runs or explicitly via /remember. Since template sync never overwrites existing files, a project that already had a flat MEMORY.md before upgrading buddhi will keep it as-is on re-running init — only a fresh buddhi init gets the new topic-file split.

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.