npx claudepluginhub siliconeinstein/gaia --plugin gaiaThis skill uses the workspace's default tool permissions.
Complete reference for the `gaia` command-line tool. Covers the full lifecycle: scaffold a package, author knowledge, compile to IR, validate, review, run inference, and publish.
Bootstraps repo-local wiki knowledge system with YAML pages, raw manifests, Python scripts for validation/ingest/provenance, auto-updates, and configs for Claude Code/Cursor/Windsurf. For durable project context and wiki-first rules.
Invokes Google Gemini CLI for complex reasoning, research, and AI tasks in headless mode. Supports preview models, fallbacks, and session continuation.
Share bugs, ideas, or general feedback.
Complete reference for the gaia command-line tool. Covers the full lifecycle: scaffold a package, author knowledge, compile to IR, validate, review, run inference, and publish.
pip install gaia-lang # or: uv pip install gaia-lang
gaia --help # verify installation
Requires Python 3.12+.
gaia init <name>
The name must end with -gaia (e.g., galileo-falling-bodies-gaia).
| Surface | Convention | Example |
|---|---|---|
| Git repo | any name (convention: kebab-case-gaia) | galileo-falling-bodies-gaia |
| PyPI / package name | kebab-case-gaia | galileo-falling-bodies-gaia |
| Python import | snake_case (no -gaia suffix) | galileo_falling_bodies |
pyproject.toml with [tool.gaia] section (auto-generated type and uuid)src/<import_name>/__init__.py with a starter template.gitignoreuv add gaia-lang to pin the dependencymy-package-gaia/
├── pyproject.toml # [tool.gaia] type + uuid
├── references.json # Optional: bibliography in CSL-JSON format (for [@key] citations)
├── src/
│ └── my_package/
│ ├── __init__.py # DSL declarations, re-exports
│ ├── motivation.py # Optional: organize by chapter/section
│ └── priors.py # Optional: prior assignments via reason+prior pairing
├── artifacts/ # Source material (PDF, markdown)
├── .gaia/ # Created by gaia compile (git tracked)
│ ├── ir.json
│ ├── ir_hash
│ └── beliefs.json # Created by gaia infer
└── .gitignore
[project]
name = "my-package-gaia"
version = "1.0.0"
requires-python = ">=3.12"
[tool.gaia]
type = "knowledge-package"
uuid = "..." # Auto-generated by gaia init
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
gaia compile .
Imports the top-level package, collects all DSL declarations, and writes:
.gaia/ir.json — the compiled Gaia IR.gaia/ir_hash — content hash for integrity checksgaia render . --target docs
Generates docs/detailed-reasoning.md with per-module Mermaid reasoning graphs and full claim details.
Note: --target docs works without beliefs (enriches with posteriors when available). --target github requires beliefs on disk — run gaia infer first.
gaia render . --target github
Generates .github-output/ with wiki pages, README skeleton, React Pages template, graph.json, and manifest.
After generation, use /gaia:publish to fill narrative content.
gaia check .
gaia check --brief .
gaia check --show <module|label> .
gaia check --brief --show <module|label> .
gaia check --hole .
Validates package structure and IR consistency. Used by registry CI during publishing.
Options:
--brief / -b — Show per-module warrant structure overview (claims with roles, strategies with priors, operators)--show / -s — Expand a specific module name or claim/strategy label with full warrant trees--hole — Show detailed prior review report for all independent claims (holes without priors + covered with priors)Common errors:
[tool.gaia].type in pyproject.toml.gaia/ir_hash mismatch)gaia check also reports informational diagnostics (not errors) useful for completeness checking during formalization:
prior=X if set, or ⚠ no prior (defaults to 0.5) if missing.background=, not as premises--hole outputDetailed report for prior review. Lists all independent claims split into two groups:
NOT SET (defaults to 0.5) statusprior=X and justification reasonUse --hole during prior review to:
priors.py--brief outputPer-module overview showing:
--show outputWhen given a module name (e.g., --show motivation): expands all claims with full content and strategies with recursive warrant trees, including composite sub-strategy expansion.
When given a claim label (e.g., --show hypothesis): shows the claim's full content and all strategies that conclude to it, with all premises listed.
Priors are set directly in DSL source via reason+prior pairing and priors.py, then baked into claim metadata at compile time. No separate review sidecar is needed.
Strategies accept a prior= keyword that pairs with their reason=:
H = claim("Hypothesis X", label="hypothesis")
E = claim("Evidence Y", label="evidence")
deduction(E, concludes=H, prior=0.85, reason="Strong experimental support")
For leaf claims (independent premises) without a concluding strategy, assign priors in src/<package>/priors.py:
from . import some_claim, another_claim
PRIORS = {
some_claim: (0.9, "Justification for high prior."),
another_claim: (0.3, "Justification for low prior."),
}
These are applied at load time before compilation. gaia check --brief shows which claims are independent (need priors) vs derived (get beliefs from BP).
For complete prior assignment guide and BP interpretation, see the review skill.
gaia infer [PATH] [--depth N]
Compiles IR into a factor graph, runs belief propagation, and writes posterior beliefs to .gaia/beliefs.json.
uv sync --quiet before loading the package to ensure dependencies are installed.priors.py + DSL reason+prior pairing), baked in at compile time. No review sidecar is needed..gaia/beliefs.json| Flag | Behavior |
|---|---|
--depth 0 (default) | Uses flat priors for foreign nodes; optionally reads dep_beliefs/ for upstream beliefs |
--depth 1 | Merges direct dependency factor graphs for joint cross-package inference |
--depth -1 | Merges all transitive dependency factor graphs |
# Local inference only (default)
gaia infer .
# Joint inference with direct dependencies
gaia infer . --depth 1
# Joint inference with all transitive dependencies
gaia infer . --depth -1
With --depth 0, foreign nodes (references to claims in other packages) get flat priors unless a dep_beliefs/ directory provides upstream belief files. With --depth 1 or -1, the dependency packages' full factor graphs are merged into a single graph for joint inference, replacing flat prior injection with structural reasoning.
Publishes a package to the Gaia registry. Requires a git tag pushed to GitHub.
gaia register . --registry-dir ../gaia-registry --create-pr
Registry CI validates:
gaia compile succeeds and hash matches .gaia/ir_hashgaia check passesNote: gaia register --create-pr creates the registry branch locally but does not automatically push it to your fork. After running the command, you must manually push and create the PR:
cd <registry-dir>
git push origin register/<name>-<version>
gh pr create --repo SiliconEinstein/gaia-registry --base main \
--head <your-user>:register/<name>-<version> --title "register: <name> <version>" --body "..."
Install a registered package from the official registry.
gaia add <package>
gaia add <package> --version 1.0.0 # pin version
Resolves packages from https://github.com/SiliconEinstein/gaia-registry.
gaia init
→ write DSL declarations + priors
→ gaia compile .
→ gaia check .
→ gaia infer .
→ gaia render . --target github
→ /gaia:publish
→ gaia render . --target docs
→ gaia register . --registry-dir ../gaia-registry --create-pr
gaia init my-package-gaiasrc/<package>/, set priors via reason+prior pairing and priors.pygaia compile . to produce IRgaia check . to catch structural errors earlygaia infer . to compute posterior beliefs (optionally --depth 1 for cross-package)gaia render . --target github to generate GitHub presentation skeleton, then /gaia:publish to fill narrative contentgaia render . --target docs to generate per-module reasoning graphsgaia register to submit to the registry