README
¶
Mulgae
Mulgae is a local, multi-provider AI code review CLI. It captures an immutable
review target, asks role-specific reviewers to inspect it, validates their
structured output, verifies evidence against the captured target, and publishes
durable artifacts under .mulgae/.
Mulgae is advisory. It reports findings and recommendations; it does not grant merge, release, waiver, or organizational approval.
Platform and providers
The initial release supports macOS on Apple silicon (darwin/arm64) and these
provider families:
- Kimi CLI
- ZCode
- AGY
Install and authenticate at least one supported provider before initializing a project. Mulgae records provider identity and capabilities at runtime and fails closed when a required capability is unavailable. Other operating systems, architectures, and provider families are not supported by the initial release.
Install
Mulgae requires Go 1.26 or newer.
go install github.com/irootkernel/mulgae@latest
Make sure $(go env GOPATH)/bin is on your PATH, then verify the installation:
mulgae version
mulgae --help
No asset archive is installed beside the binary. Schemas, prompts, roles, examples, and help text are embedded in the executable.
Quick start
Run Mulgae from the root of the Git repository you want to review:
cd /path/to/repository
mulgae init
mulgae config
mulgae providers --include-unverified
mulgae review --diff origin/main...HEAD \
--objective "Review this change before merge."
mulgae init creates the only configuration authority:
.mulgae/config.yaml. It never overwrites an existing configuration.
Every review command requires exactly one target:
--workspace tracked files at the current workspace state
--stage staged changes
--dirty staged and unstaged changes
--diff REVISION_RANGE a Git revision range, such as origin/main...HEAD
--patch RELATIVE_PATH a patch file in the project
--stdin a patch read from standard input
Use --output json on commands when integrating Mulgae with another tool.
Review results
A successful publication creates a run beneath:
.mulgae/{session_id}/{run_id}/
The directory contains a manifest, provider attempts, validation records,
runtime diagnostics, and at most one final review_*.json artifact. Provider
output is never treated as a final artifact until Mulgae has normalized,
validated, and committed it.
Inspect a run with its exact ID:
mulgae status --run r_...
mulgae findings --run r_... --severity high
mulgae report --run r_... --output-path reports/review.md
Create a focused follow-up after changing the code:
mulgae followup --run latest --finding F001 --dirty \
--objective "Check whether the original finding is resolved."
Help
The binary includes focused help topics:
mulgae help workflows
mulgae help config
mulgae help providers
mulgae help artifacts
mulgae help security
Available topics are quickstart, config, providers, lanes, prompts,
workflows, artifacts, validation, ci, exit-codes, and security.
Documentation
Contributor documentation lives in docs/:
License
Mulgae is available under the MIT License.
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
adapters/cli
Package cli exposes the fixed Mulgae command registry and its dispatcher.
|
Package cli exposes the fixed Mulgae command registry and its dispatcher. |
|
adapters/fakeprovider
Package fakeprovider provides a deterministic scripted ReviewProvider for tests.
|
Package fakeprovider provides a deterministic scripted ReviewProvider for tests. |
|
adapters/filesystem
Package filesystem provides Darwin filesystem adapters for ports.
|
Package filesystem provides Darwin filesystem adapters for ports. |
|
adapters/jsonschema
Package jsonschema adapts immutable contract-catalog JSON assets to the JSON Schema validator without exposing the JSON Schema library to domain code.
|
Package jsonschema adapts immutable contract-catalog JSON assets to the JSON Schema validator without exposing the JSON Schema library to domain code. |
|
adapters/lanelock
Package lanelock provides authoritative Darwin cross-process lane locking.
|
Package lanelock provides authoritative Darwin cross-process lane locking. |
|
adapters/providercli
Package providercli implements opt-in direct CLI review providers.
|
Package providercli implements opt-in direct CLI review providers. |
|
adapters/reviewinput
Package reviewinput composes the immutable root-review input boundary.
|
Package reviewinput composes the immutable root-review input boundary. |
|
app/childrun
Package childrun executes and publishes supplied child review runs.
|
Package childrun executes and publishes supplied child review runs. |
|
app/clean
Package clean builds deterministic, side-effect-free retention plans.
|
Package clean builds deterministic, side-effect-free retention plans. |
|
app/config
Package config admits one project-local configuration and projects the fixed runtime policy consumed by review composition.
|
Package config admits one project-local configuration and projects the fixed runtime policy consumed by review composition. |
|
app/delta
Package delta starts immutable A-to-B child review runs.
|
Package delta starts immutable A-to-B child review runs. |
|
app/doctor
Package doctor reports redacted, evidence-backed environment readiness.
|
Package doctor reports redacted, evidence-backed environment readiness. |
|
app/evidence
Package evidence verifies provider current-evidence claims against caller-owned immutable target bytes.
|
Package evidence verifies provider current-evidence claims against caller-owned immutable target bytes. |
|
app/export
Package export builds deterministic, redacted export packages from verified P2 projections.
|
Package export builds deterministic, redacted export packages from verified P2 projections. |
|
app/followup
Package followup starts one immutable, finding-scoped child workflow.
|
Package followup starts one immutable, finding-scoped child workflow. |
|
app/help
Package help exposes exact embedded help assets through the application layer.
|
Package help exposes exact embedded help assets through the application layer. |
|
app/init
Package init implements create-once project-local configuration discovery and crash-truthful installation.
|
Package init implements create-once project-local configuration discovery and crash-truthful installation. |
|
app/prompt
Package prompt compiles the byte-exact provider stdin packet.
|
Package prompt compiles the byte-exact provider stdin packet. |
|
app/providers
Package providers lists the fixed, trusted provider profiles without invoking them.
|
Package providers lists the fixed, trusted provider profiles without invoking them. |
|
app/publication
Package publication builds deterministic, schema-validated publication records.
|
Package publication builds deterministic, schema-validated publication records. |
|
app/query
Package query exposes committed publication data to status, findings, excerpt, and report consumers.
|
Package query exposes committed publication data to status, findings, excerpt, and report consumers. |
|
app/report
Package report renders a human-readable projection of a committed query snapshot.
|
Package report renders a human-readable projection of a committed query snapshot. |
|
app/rerun
Package rerun starts immutable child runs that replay a verified source attempt.
|
Package rerun starts immutable child runs that replay a verified source attempt. |
|
app/review
Package review coordinates one deterministic, in-memory review run.
|
Package review coordinates one deterministic, in-memory review run. |
|
app/reviewrun
Package reviewrun contains provider-independent review-run admission policy.
|
Package reviewrun contains provider-independent review-run admission policy. |
|
app/roles
Package roles exposes the fixed build-owned review role inventory.
|
Package roles exposes the fixed build-owned review role inventory. |
|
app/schema
Package schema exposes the embedded schema catalog through application ports.
|
Package schema exposes the embedded schema catalog through application ports. |
|
app/validation
Package validation validates untrusted provider review output before it enters the domain model.
|
Package validation validates untrusted provider review output before it enters the domain model. |
|
entrypoint/mulgae
Package mulgae parses the fixed Mulgae command line into immutable invocations.
|
Package mulgae parses the fixed Mulgae command line into immutable invocations. |
|
roles
Package roles parses and validates the build-owned role catalog.
|
Package roles parses and validates the build-owned role catalog. |