Metadata-Version: 2.4
Name: buddhi-ai
Version: 1.0.0b10
Summary: Turn a codebase into a code graph and a grounded AI coding agent harness.
Keywords: ai,agent,cli,code-graph,codebase-analysis,static-analysis,tree-sitter,antigravity,developer-tools,documentation-generator
Author: Buddhi Kavindra
Author-email: Buddhi Kavindra <info@buddhilive.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Utilities
Requires-Dist: igraph>=1.0.0
Requires-Dist: pathspec>=1.1.1
Requires-Dist: rich>=15.0.0
Requires-Dist: tree-sitter>=0.26.0
Requires-Dist: tree-sitter-c-sharp>=0.23.5
Requires-Dist: tree-sitter-go>=0.25.0
Requires-Dist: tree-sitter-java>=0.23.5
Requires-Dist: tree-sitter-javascript>=0.25.0
Requires-Dist: tree-sitter-kotlin>=1.1.0
Requires-Dist: tree-sitter-python>=0.25.0
Requires-Dist: tree-sitter-rust>=0.24.2
Requires-Dist: tree-sitter-swift>=0.7.3
Requires-Dist: tree-sitter-typescript>=0.23.2
Requires-Dist: typer>=0.27.1
Requires-Dist: mcp[cli]>=1.2.0,<2.0.0 ; extra == 'mcp'
Requires-Python: >=3.10
Project-URL: Homepage, https://www.buddhilive.com
Project-URL: Issues, https://github.com/Buddhilive/buddhi-cli/issues
Project-URL: Repository, https://github.com/Buddhilive/buddhi-cli
Provides-Extra: mcp
Description-Content-Type: text/markdown

# Buddhi AI CLI

<p align="center">
  <a href="https://pypi.org/project/buddhi-ai/">
    <img src="https://img.shields.io/pypi/v/buddhi-ai?style=flat-square&logo=pypi" alt="PyPI Version" />
  </a>
  <a href="https://pypi.org/project/buddhi-ai/">
    <img src="https://img.shields.io/pypi/dm/buddhi-ai?style=flat-square" alt="PyPI Downloads" />
  </a>
  <a href="LICENSE">
    <img src="https://img.shields.io/github/license/Buddhilive/buddhi-cli?style=flat-square" alt="License" />
  </a>
</p>

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](https://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.
- 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+.

```sh
pip install "buddhi-ai[mcp]"
```

Or, if you prefer an isolated tool install:

```sh
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)

```sh
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
- `.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

```sh
buddhi mcp [--db-path <path>]
# or run the dedicated entrypoint directly:
buddhi-mcp [--db-path <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.

The MCP server auto-detects `.buddhi/graphs/tree-graph.db` in the workspace root or parent directories and is scoped per-workspace with zero port conflicts.

### `buddhi generate` — update / refresh code graph

```sh
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

```sh
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

```sh
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/`**
  - **`/specify`** — Initialize a new feature branch, 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.
  - **`/document-codebase`** — Generate or refresh OKF symbol documentation bottom-up.
  - **`/debug`** — Systematic bug investigation 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](https://okf.org/) (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](https://arxiv.org/abs/2402.16667) 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

```sh
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

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

### Publishing

Releases to PyPI are handled by the [`publish.yml`](.github/workflows/publish.yml)
GitHub Actions workflow. It builds the package with `uv build` and publishes it
using [PyPI trusted publishing](https://docs.pypi.org/trusted-publishers/) (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`](pyproject.toml).
2. Commit the change and tag it to match, e.g.:
   ```sh
   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.
