Impact agent

uigraph-agents impact [options]

Alias: uigraph-agents analyze.

The impact agent reads a range of commits and reports what the change actually affects — which services, APIs, schemas, and artifacts sit downstream of it. It answers the question a diff cannot: who else cares about this?

By default it writes nothing. All you get back is a report, printed to your terminal or saved with --report. Add --artifacts and it also updates the artifacts it found to be wrong, the same way the artifacts agent does.

It reasons over your architecture graph, not just your repository, so it needs a live connection to UIGraph MCP and will not start without one. Setup covers connecting it.

Choosing what to analyse

Flag	Use it when
--previous commit	You want the impact of the latest commit alone.
--previous tag	You want everything that changed since the last release.
--target <ref>	You want to compare against a specific commit or tag yourself — this is what you want on a pull request.

Pass one or the other, not both. With no flag at all, the agent analyses uncommitted work.

For a pull request, compare against the merge base with your default branch:

uigraph-agents impact --target "$(git merge-base origin/main HEAD)"

Options

Flag	Description
--cwd [path]	Directory to run in. Defaults to the current directory.
--config [path]	Agent config file. Defaults to the standard lookup.
--uigraphConfig [path]	Path to .uigraph.yaml. Defaults to .uigraph.yaml.
--model [id]	Model identifier. Same as AI_PROVIDER_MODEL.
--npm [pkg]	Provider package. Same as AI_PROVIDER_NPM.
--apiUrl [url]	Provider base URL.
--mcpUrl [url]	UIGraph MCP server URL. Same as UIGRAPH_MCP_URL.
--enterprise [DEV]	Use hosted UIGraph for both the MCP server and the run record, instead of setting UIGRAPH_MCP_URL and UIGRAPH_API_URL. Add DEV for the development environment. Cannot be combined with --mcpUrl.
--orgId [id]	UIGraph organization id. Same as UIGRAPH_ORG_ID.
--target [ref]	Git commit or tag to compare against.
--previous [commit|tag]	Compare against the previous commit or tag.
--artifacts	Also update the artifacts the change made wrong. Same as UIGRAPH_IMPACT_ARTIFACTS.
--report [path]	Write the report to a file instead of stdout. Relative to --cwd.
--verbose	Show what the agent is doing as it works.

Updating artifacts as well

Add --artifacts when you want the agent to fix what it found rather than only report it:

uigraph-agents impact --target "$(git merge-base origin/main HEAD)" --artifacts

It can then edit the artifacts declared in .uigraph.yaml, and nothing else. Your source code stays off limits. An artifact that still describes reality is left alone.

Leave the flag off in a pull-request job where you only want a review comment.

Example

export UIGRAPH_MCP_URL="https://mcp.your-org.com"
export UIGRAPH_API_URL="https://uigraph.your-org.com"
export UIGRAPH_TOKEN="uig_…"

uigraph-agents impact \
  --target "$(git merge-base origin/main HEAD)" \
  --report impact-report.md

The same run against hosted UIGraph needs only the token:

export UIGRAPH_TOKEN="uig_…"

uigraph-agents impact \
  --enterprise \
  --target "$(git merge-base origin/main HEAD)" \
  --report impact-report.md

To post that report as a pull-request comment, see CI/CD.

Troubleshooting

What you see	What to do
It cannot reach UIGraph	Check the URL resolves from wherever you are running the agent — a server behind a VPN will not answer a hosted CI runner — and that your token has not expired.
It says no UIGraph server is configured	Set UIGRAPH_MCP_URL, or pass --mcpUrl or --enterprise. See Setup.
It says to pass either --mcpUrl or --enterprise, not both	Those two set the same thing. Keep --enterprise for hosted UIGraph, --mcpUrl for your own server.
It says --enterprise must be passed with no value or as DEV	The only accepted value is DEV, in capitals. Pass the flag on its own for the production environment.
It says no access token is configured	Set UIGRAPH_TOKEN.
It says no UIGraph API URL or token is configured	Set UIGRAPH_API_URL and UIGRAPH_TOKEN. Every run is recorded in UIGraph and stops without them. See Setup.
It asks for an organization	You are signing in as a user rather than a service account. Set UIGRAPH_ORG_ID, or switch to a service-account token.
It says the repository has no artifacts	There is no .uigraph.yaml. Onboard the repository with UIGraph CLI first.
It says no model is configured	Set AI_PROVIDER_MODEL, or pass --model.