PHPackages                             waaseyaa/bimaaji - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. waaseyaa/bimaaji

ActiveLibrary[Utility & Helpers](/categories/utility)

waaseyaa/bimaaji
================

Bimaaji — application graph introspection and agent-safe mutation for Waaseyaa

v0.1.0-alpha.259(2w ago)02.5k↑298.4%2GPL-2.0-or-laterPHPPHP >=8.5CI passing

Since Apr 10Pushed 1w agoCompare

[ Source](https://github.com/waaseyaa/bimaaji)[ Packagist](https://packagist.org/packages/waaseyaa/bimaaji)[ RSS](/packages/waaseyaa-bimaaji/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (41)Versions (142)Used By (2)

waaseyaa/bimaaji
================

[](#waaseyaabimaaji)

**Bimaaji** is a Waaseyaa package providing **application graph introspection** and an **agent-safe mutation protocol**. The name (Anishinaabemowin: "to give life to") reflects its role: making a booted Waaseyaa application's structure visible and actionable to AI agents.

What it does
------------

[](#what-it-does)

Bimaaji exposes two surfaces:

1. **Read-only introspection.** Six `GraphSectionProvider` implementations (admin, entities, jsonapi, public\_surface, routing, sovereignty) emit versioned `GraphSection` payloads that, taken together, describe what an application contains: registered entity types and their fields, every registered route plus access classification, the JSON:API surface, admin entity groupings, the current sovereignty profile, and the public-surface map.
2. **Validated mutation.** A `MutationRequest` → `MutationValidator` → `PatchSet` pipeline lets an agent propose changes (e.g., "add field X to entity Y"). The validator gates every request through `SovereigntyGuardrails`; the patch generator emits content-hashed, reviewable file patches. **Bimaaji itself never writes to disk** — patches are returned for human (or upstream agent) review.

Quick start
-----------

[](#quick-start)

After installing `waaseyaa/framework` (which depends on this package), the framework's `PackageManifestCompiler` auto-discovers `BimaajiServiceProvider`. The application graph generator is then reachable from the container:

```
use Waaseyaa\Bimaaji\Graph\ApplicationGraphGenerator;

$graph = $container->get(ApplicationGraphGenerator::class)->generate();
foreach ($graph->sections as $key => $section) {
    echo "{$key}: " . count($section->data) . " entries\n";
}
```

The six default section providers are pre-wired:

ProviderSection keyConstructor deps`AdminIntrospectionProvider``admin``EntityTypeManagerInterface``EntityIntrospectionProvider``entities``EntityTypeManagerInterface``JsonApiIntrospectionProvider``jsonapi``RouteCollection``PublicSurfaceProvider``public_surface``RouteCollection``RoutingIntrospectionProvider``routing``RouteCollection``SovereigntyIntrospectionProvider``sovereignty``SovereigntyProfile``SovereigntyProfile` is derived from `SovereigntyConfigInterface::getProfile()` and falls back to `SovereigntyProfile::Local` when no config is bound. `RouteCollection` is looked up directly and falls back to `WaaseyaaRouter::getRouteCollection()`.

Extending: third-party graph sections
-------------------------------------

[](#extending-third-party-graph-sections)

A consuming package can contribute its own section by implementing `GraphSectionProviderInterface` and binding it in its own `ServiceProvider::register()`. The canonical tag is `BimaajiServiceProvider::SECTION_PROVIDER_TAG` (`bimaaji.section_provider`); tag your binding under it for forward-compatibility with future tagged-collection container support.

```
final class FooSectionProvider implements GraphSectionProviderInterface
{
    public function getKey(): string { return 'foo'; }
    public function provide(): GraphSection { /* ... */ }
}
```

Installing guidelines / skills (`bin/waaseyaa bimaaji:install`)
---------------------------------------------------------------

[](#installing-guidelines--skills-binwaaseyaa-bimaajiinstall)

Ship the framework-canonical agent skill pack to a consumer project in per-client formats. Lifted in spirit from Laravel Boost's `php artisan boost:install`; framework-native, no Node runtime.

```
# Install for one client
bin/waaseyaa bimaaji:install --client=claude

# Install for several (comma-separated or repeated)
bin/waaseyaa bimaaji:install --client=claude,cursor --force

# Preview without writing
bin/waaseyaa bimaaji:install --client=cursor --dry-run

# Interactive client selection when omitted on a TTY
bin/waaseyaa bimaaji:install
```

Seven launch clients: `claude`, `cursor`, `codex`, `copilot`, `gemini`, `windsurf`, `junie`. See [`docs/specs/bimaaji-install.md`](../../docs/specs/bimaaji-install.md)for the per-client target paths, flag semantics, interactive UX, exit codes, sandbox guarantees, and the five-step extension guide for adding new clients.

Status
------

[](#status)

Bimaaji is now exposed over MCP via [`packages/mcp/`](../mcp/)'s per-request bridge architecture as of 2026-05-23 (M3 `bimaaji-mcp-bridge-01KS5VS8`). Five `#[AsAgentTool]` adapters live in `packages/ai-agent/src/Tool/Bimaaji/` and surface automatically through the `AgentToolRegistryBridge` with no per-tool MCP code. See [`docs/specs/mcp-endpoint.md`](../../docs/specs/mcp-endpoint.md) § "Bimaaji MCP bridge" for the transport contract and `packages/mcp/README.md`for the operator-facing summary.

The 2026-05-20 "PHP-only" deferral that closed [\#1463](https://github.com/waaseyaa/framework/issues/1463) was formally superseded by M3; the issue stays closed with a supersession comment linking to the M3 PR set.

### Legacy MCP-server cleanup (pre-M3 consumers)

[](#legacy-mcp-server-cleanup-pre-m3-consumers)

Projects (e.g., Minoo) that previously wired the deleted Node-based bimaaji MCP server (`vendor/waaseyaa/bimaaji/mcp/server.js`, removed in #1387/#1464) should:

1. Remove any `mcpServers.bimaaji` entry pointing at the deleted `server.js` from `.claude/settings.json`. The replacement is the framework-native `/mcp` HTTP endpoint shipped by `waaseyaa/mcp`.
2. Drop `composer bimaaji-mcp-install` from post-install hooks or contributor docs — the script body was Minoo-local and has no upstream entry point.
3. Wire the new HTTP `/mcp` endpoint instead. See `packages/mcp/README.md` for the `claude_desktop_config.json`example fragment.

Where to read more
------------------

[](#where-to-read-more)

- **Doctrine spec:** [docs/specs/bimaaji.md](../../docs/specs/bimaaji.md) — design rationale, FRs/NFRs, invariants, file map.
- **Design history:** [docs/history/plans/2026-05-21-ai-ecosystem-beta-tightening.md](../../docs/history/plans/2026-05-21-ai-ecosystem-beta-tightening.md) — the 5-mission cluster that promoted bimaaji from "scaffolding" to "shipped."
- **Roadmap context:** [GitHub Milestone #67](https://github.com/waaseyaa/framework/milestone/67) (Track 2: Bimaaji & agentic).

###  Health Score

50

—

FairBetter than 95% of packages

Maintenance97

Actively maintained with recent releases

Popularity23

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 74.6% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

141

Last Release

14d ago

PHP version history (3 changes)v0.1.0-alpha.117PHP >=8.2

v0.1.0-alpha.140PHP >=8.4

v0.1.0-alpha.176PHP >=8.5

### Community

Maintainers

![](https://www.gravatar.com/avatar/25d0ff572e93e3461e5180a920725d65691fd1e15e2d914b254dbbc2d6c393bd?d=identicon)[jonesrussell](/maintainers/jonesrussell)

---

Top Contributors

[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (85 commits)")[![jonesrussell](https://avatars.githubusercontent.com/u/499552?v=4)](https://github.com/jonesrussell "jonesrussell (29 commits)")

---

Tags

composer-packagephpwaaseyaa

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/waaseyaa-bimaaji/health.svg)

```
[![Health](https://phpackages.com/badges/waaseyaa-bimaaji/health.svg)](https://phpackages.com/packages/waaseyaa-bimaaji)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)