maxitor

Your system's model, built from its code: kept with every change, checked in CI, and drawn as live diagrams.

Maxitor is one package with parts you choose at install time:

pip install "maxitor[all]" installs everything. The base install brings only jsonschema and jsonschema-rs — nothing of AOA, no server — so it is all a CI job needs. A command whose part is not installed says which extra to add.

Get started

The fastest way: one prompt to your coding agent

Install and run this skill for the current project:
https://raw.githubusercontent.com/bystrovmaxim/aoa/main/packages/maxitor/skills/aoa-graph-builder-setup/SKILL.md

Walk me through the wizard in my language. Ask one question at a time and wait for my answer. For each decision, explain in plain words: what you found, what you propose to change, why you recommend this option, and what happens if I choose another. Explain each technical term the first time you use it.

First check whether the current project fits. If it is empty or has no source of graphs, explain the situation and stop without creating any configuration or checks. If some services are already connected, keep the settings that work, and discuss the new services one at a time.

If I do not understand a question, give a concrete example and come back to the same decision. Before applying anything, show the summary: my decisions, which files will change, and what will remain to do by hand. Apply changes only after I confirm. Do not create commits or pull requests.

The agent follows a four-stage wizard in your language: discover the project, settle each service's choices, choose updating and checking, then review the proposed changes. Each question explains one decision, a recommendation and the consequences of the alternatives. You can ask for an example, go back, change an answer or pause. Nothing is applied to the target project until the proposed changes are reviewed and authorized. Asking to review or edit the skill itself does not start setup.

The wizard proves exports in a temporary folder, then applies the accepted exporters, graph files and integrations. A deferred optional integration remains explicitly manual; mandatory release versioning cannot be deferred. It leaves the result for you to review and commit; serving graph history from the main branch requires those files to reach that branch.

Already have the package? graph-builder skill > .claude/skills/aoa-graph-builder-setup/SKILL.md (or .cursor/skills/…), then ask the agent to run aoa-graph-builder-setup. Run it again any time: on a configured project it is an audit.

What the wizard asks you to decide

The wizard sets up two independent parts, version checks and saved graphs; you may choose either, both or neither. Every run audits the project and proposes only the difference. Version decisions stay in [setup] of the root version.toml, graph decisions in [setup] of graph-builder.toml. It never raises a version number for you, and release tags stay optional. See the setup guide.

It finishes one service before moving to the next. First decide whether to connect a newly discovered service (including its exporter if needed), then where to save its map if that is not already established. After the services, choose how to refresh their maps and how to detect a forgotten refresh. Existing working arrangements are retained, not turned into repeat questions. Technical commands and proof accompany the final review rather than crowding each question.

An illustrative question, with fictional project paths:

2/4 · Services · game-back — save a map of this service?

game-back contains the game's model, but no command saves its map. A small exporter has been proven in a temporary folder. Connecting it lets you review model changes alongside code changes.

1. Connect it (recommended): add packages/game-back/game_back/build_graph.py, the program that produces the map. You will review the saved map when the model changes; its location comes next.
2. Leave it out for now: add nothing for this service; this setup will not track its model changes.

If you answer “leave it out”, the wizard acknowledges that consequence and skips that service's file-location question. If you answer “I do not understand”, it explains a concrete case: “Adding an entity changes the model. The saved map lets the same code review show that new entity. Leaving this service out means this setup will not save that map.” It then returns to the same decision, without treating the explanation request as acceptance. This is an illustrative dialogue, not a recorded agent run.

Updating and checking are different: graph-builder write refreshes files; graph-builder check detects stale files without rewriting them. A failing CI check blocks merging only when repository rules require it. The wizard does not change those rules. A local update step runs only after the other checks pass.

Before applying, you see the before/after table, affected files, prepared changes, commands, proof and any manual work left. You can apply, revise a choice or stop. The skill remains a single file, so graph-builder skill delivers the whole wizard. A live conversation is still needed to judge how clearly a particular agent follows these instructions; package tests alone do not establish that.

By hand, in four steps

1. Export each service's model — a command, in any language, that prints the service's graph by the protocol's schema and nothing else. Only the project knows its model, so the project writes this command; graph-builder runs it, checks what it prints, and keeps the file.

An AOA service (Python) — the framework builds the graph:

# my_service/build_graph.py
import importlib
import sys

from aoa.action_machine.graph.node_graph_coordinator_factory import create_node_graph_coordinator


def main() -> None:
    importlib.import_module("my_service.app")  # registers the service's actions, entities and resources
    sys.stdout.write(create_node_graph_coordinator().to_json())


if __name__ == "__main__":
    main()

A Node service — the project's own code describes its model:

// scripts/export-graph.mjs
import { buildModelGraph } from "../src/model/graph.js";
process.stdout.write(JSON.stringify(buildModelGraph()));

Any other stack works the same way: a Java task, a 1C export, or cat build/graph.json when another step already wrote the file.

2. List the graphs in graph-builder.toml at the repository root:

graph_builder = "1.0"

[[graph]]
name  = "my-service"
build = "uv run python -m my_service.build_graph"    # or: node scripts/export-graph.mjs
file  = "my_service/graph.json"

3. Write them — graph-builder write — and commit graph-builder.toml with the graph files. Without installing anything but uv: uvx --from maxitor graph-builder write (uv fetches its own Python; the project needs none).

4. Check them in CI: prepare the project's environment the way its other jobs do, then one step:

- uses: actions/checkout@v4
- uses: actions/setup-node@v4          # or setup-java, or setup-uv + uv sync — whatever the builds need
- run: npm ci
- uses: bystrovmaxim/aoa/packages/maxitor/tools/graph-builder@maxitor-v3.0.0

The step runs graph-builder check: every build again, every graph checked against the protocol's schema, every file compared with what its build prints.

From then on, a pull request that changes the model without its graph file fails, naming each difference by id — and graph-builder write with one more commit fixes it.

See the system

pip install "maxitor[web]"
maxitor

Open http://127.0.0.1:8000 and point it at an AOA service's graph.

Learn more

• The graph-builder command — commands, configuration, how graphs are kept in a repository, the CI check, use from Python
• The web part — the diagrams, the API, running it, its architecture
• repo-graph-port — a graph's history from its repository: versions, keys, public links, webhooks
• aoa-graph-builder-setup — the skill an agent follows
• Open Gnomon Protocol — the graph's language, which any language can follow
• Changelog · Source · Issues

maxitor 3.0.0 replaces two earlier packages, the app's and the command's; the changelog says what to change in an install or an import.

Apache License 2.0.