UiGraph Agents

AI agents that keep your UiGraph documentation in step with your code, run from one CLI.

You point an agent at your repository. It reads what changed, and either fixes the documentation that fell behind, or tells you what the change affects.

Documentation

Everything — setup, configuration, and CI — lives in the official UiGraph docs:

• UiGraph Agents — start here
• Artifacts agent — setup, configuration
• Impact agent — setup, configuration

The two agents

| Agent | Command | What it does | Changes files? | |---|---|---|---| | Artifact initialization | uigraph-agents artifacts init | Inspects the whole repository and generates the initial UiGraph configuration and artifacts. --seeded completes an existing minimal config instead. | Yes | | Artifact sync | uigraph-agents artifacts sync | Finds where your code and your UiGraph artifacts no longer match, and updates the artifacts. | Yes | | Artifact repair | uigraph-agents artifacts fix "<context>" | Repairs what a chunk of raw text asks for, and nothing else. | Yes | | Impact | uigraph-agents impact | Reports which services, APIs, and artifacts a change affects. | No |

uigraph-agents artifacts on its own prints this help and exits 1 — pick a subcommand.

The GitHub Actions onboarding workflow starts with a minimal .uigraph.yaml containing service.name, service.repository.provider, service.repository.url, and service.ownership.team, then runs:

uigraph-agents artifacts init --seeded

Initialization preserves those identity values while adding supported artifact declarations and generated files under .uigraph/. If initialization crashes or is interrupted, it restores the seed and removes files created by that run so the workflow can retry safely. Non-seeded uigraph-agents artifacts init remains available for repositories without a config.

The onboarding loop

init and sync validate what they wrote with the same rules uigraph-cli sync applies, and repair themselves until validation is clean. Repairs are uncapped: they end on a clean validation, a shutdown, a model API error, or a stall — a repair turn that changed nothing and returned the same errors. A run that still has errors keeps its files on disk and exits 1, so uigraph-cli can name the next error and fix can repair it:

uigraph-agents artifacts init

PREVIOUS=""
while :; do
  OUTPUT=$(uigraph-cli sync --dry-run 2>&1) && break
  [ "$OUTPUT" = "$PREVIOUS" ] && break
  PREVIOUS="$OUTPUT"
  uigraph-agents artifacts fix "$OUTPUT"
done

fix takes its context as a required argument: one raw chunk of text, used as given. It is not parsed into a list of errors and has no line structure, so anything that describes what is wrong works — a whole dry-run transcript, a single validation error, or a sentence like "the payments dependency should be soft, not hard". When the context describes nothing that is actually wrong, fix changes nothing and says so.

The dry-run is the gate, so fix exits 0 whenever it completes, including when it changed nothing; a non-zero exit means the run itself failed. The loop above ends when the dry-run passes, and ends as stalled when a round produces the same output as the round before it.

Configure the customer AI provider with AI_PROVIDER_MODEL, AI_PROVIDER_API_KEY, and optionally AI_PROVIDER_NPM and AI_PROVIDER_API_URL. Every run is recorded as an agent session, so every command — initialization included — requires UIGRAPH_API_URL and UIGRAPH_TOKEN, and fails before calling the model when the session cannot be created. Once a run is recorded, a step that fails to reach the API is reported and the run continues.

Pass --enterprise to point a command at the UiGraph environment instead of setting UIGRAPH_API_URL (and UIGRAPH_MCP_URL for impact), or --enterprise DEV for the dev environment. UIGRAPH_TOKEN is still required.

The UiGraph authoring skill is pinned to an immutable commit. Set UIGRAPH_SKILL_REF to another full 40-character commit SHA to override it. In init mode, --report writes to stdout by default; a report file must be a new absolute path outside the repository, such as a runner temporary directory.

Install

npx @uigraph/agents --help

Or install it once:

npm i -g @uigraph/agents
uigraph-agents --help

Then follow the setup guide for the agent you want: artifacts or impact.

License

BUSL-1.1. See LICENSE.