gxkit

Agent-native review loops for creative artifacts. Its job is simple: let an AI check its own work before you have to. Write the artifact as code, inspect it, get problems with stable codes and an exit code, fix them, and ship — with a storyboard image as the evidence.

Set up with a prompt. Paste into Claude Code, Codex, or Cursor — the agent installs and runs it:

Follow https://raw.githubusercontent.com/nekomario28/gxkit/main/llms.txt. Install gxkit, then inspect .

One core, sixteen domains. The 3D is rendered with ManimGX — the renderer gxkit’s framegx inspects.

Start with one tool

Most people have one kind of artifact, and most of these tools read a file you already have — a chart script, a rendered video, a published API spec — with no declaration to write. Install the one tool you need (from the repository until the first release; afterwards the same commands are uvx chartgx …):

uv tool install "git+https://github.com/nekomario28/gxkit#subdirectory=packages/chartgx"
chartgx inspect my_chart.py

Then point it at what you already have:

None of these needs a gxkit-specific declaration: chartgx runs the script and reads the figure it builds, apigx and schemagx and flowgx convert the document and apply the same codes as a declaration, and framegx probes the encoded file.

Want all sixteen? Install the family instead — the contract is identical:

uvx --from "git+https://github.com/nekomario28/gxkit#subdirectory=packages/gxkit" gxkit tools

The loop

Every tool has the same contract, so an agent learns it once:

 inspect artifact.py     # report + storyboard; exit 1 on any error
 inspect artifact.py --json
 render  artifact.py -o out.png

• Exit 1 on any error; warn and info never fail the build.
• Stable codes — truncated-baseline, soft-lock, escalation, … — so an agent branches on the code, never on prose.
• A storyboard image with each located problem boxed and numbered, so the text report and the picture agree.

Keep history. Compare a run to an accepted state, so CI fails only on new errors and old debt is visible as it shrinks:

 inspect artifact.py --write-baseline .gxkit-baseline.json   # accept today
 inspect artifact.py --baseline .gxkit-baseline.json         # new / fixed / unchanged

The baseline is plain JSON — commit it. Format 2 preserves repeated findings and explicit relationship identities. Older baselines are rejected: review the current findings, then deliberately recreate accepted debt with --write-baseline. Without a baseline, any error fails. An input that cannot be inspected exits 2.

One entry point. With the family installed you don’t have to know which tool fits — it reads the artifact and routes:

uv run gxkit tools              # what can be inspected
uv run gxkit inspect chart.py   # detect the artifact and route it
uv run gxkit codes              # every problem code and its severity

A document that is not a Python artifact (an openapi.json) needs its tool named once: gxkit inspect apigx openapi.json.

Tools

Each tool also ships README.md, AGENTS.md, llms.txt and SKILL.md; the repository root has SKILL.md, the family skill that routes to them all. docs/TRACE.md maps each tool to its module, its codes and its examples (generated, so it cannot drift).

Pairs with ManimGX. A renderer makes the 3D animation; gxkit checks the result. ManimGX’s inspect reads the scene before rendering; framegx reads the encoded file after — black, frozen, wrong length, silent. So manimgx render scene.py && framegx inspect clip.py closes the loop. gxkit is an independent project, not affiliated with ManimGX or Academa.

See it catch something

Here is a level an agent wrote. Every cell is reachable, so a naive check passes — but a one-way tile drops the player into a dead end. levelgx walks the directed graph and finds it (the picture below is generated from the same data):

$ levelgx inspect softlock.py
inspect: 1 problem (1 error)
  [1] error cell r2c3  soft-lock: 2 reachable cells cannot get back to the goal
                        (e.g. cell r2c3) — a one-way tile makes a dead end
$ echo $?
1

The text says which cell; the storyboard image boxes it. That is the whole idea, repeated for sixteen domains.

One core, thin tools

The expensive part of a review loop is the contract, not the checks. gxcore owns it — model, report, cli, storyboard, testing — plus the analysis the tools share:

• graph — reachability, reverse reachability, traps (soft-locks), cycles.
• layout — text too small, clipped, or overlapping.
• diagram — a deterministic node-link renderer.
• loading and toolkit — load an artifact from a file; build a tool from three callables.

A new tool is a loader, a checks module and a renderer; its tool.py is about twenty lines. See docs/BUILDING.md.

Install

# run without installing
uvx --from "git+https://github.com/nekomario28/gxkit#subdirectory=packages/chartgx" chartgx inspect chart.py
# or put it on PATH
uv tool install "git+https://github.com/nekomario28/gxkit#subdirectory=packages/chartgx"
# or install the whole family behind one `gxkit` command
uv tool install "git+https://github.com/nekomario28/gxkit#subdirectory=packages/gxkit"

Replace chartgx with any tool above. Needs Python 3.10+; chartgx also needs matplotlib, and shadergx needs a GL context (Mesa/EGL or a GPU).

Use in CI

A reusable action runs gxkit inspect and fails the job on an error:

permissions:
  contents: read          # the action only needs to read
jobs:
  inspect:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: nekomario28/[email protected]
        with:
          path: artifacts/          # a file, or a directory of *.py artifacts
          args: --json              # optional extra flags
          # tool: chartgx           # optional: install just one tool

The action runs the artifact to inspect it (see SECURITY.md), so run it on an ephemeral runner with no secrets, and not on files you do not trust.

Configure

A .gxkit.toml anywhere up the tree from the artifact is read by every tool:

ignore = ["no-units"]           # drop a note everywhere
[severity]
dual-axis = "error"             # promote a warning to a failure
[chartgx]
ignore = ["red-green"]          # ...or only for one tool

Pass --no-config to ignore it.

Develop

uv sync --all-packages
uv run pytest
uv run chartgx inspect packages/chartgx/examples/bad_chart.py   # exit 1
uv run framegx  inspect packages/framegx/examples/frozen_clip.py   # exit 1
python scripts/prepublish_check.py      # no credentials or machine paths
python scripts/make_readme_figure.py    # regenerate the architecture figure
# the 3D hero is made with ManimGX (scene in docs/hero/), then converted:
uvx --python 3.14 manimgx render docs/hero/gxkit_hero.py -r 720x720 --fps 24
ffmpeg -i docs/hero/GxkitHero.mp4 -vf "fps=12,scale=560:-1:flags=lanczos,split[a][b];[a]palettegen[p];[b][p]paletteuse" -loop 0 docs/assets/hero.gif
# then update docs/assets/hero.json; a test refuses a scene that was edited
# without being drawn again, and the cube count comes from packages/

Documentation

• SKILL.md — the family agent skill; routes to each tool’s skill.
• docs/BUILDING.md — how to add a tool: the checklist, the contract, the extraction rule, the pitfalls.
• docs/CONTRACT.md — what an integrator may rely on: codes, exit codes, the JSON report, the baseline, and what is explicitly not promised.
• docs/PLAN.md — goals and roadmap.
• docs/SKILL-EVAL.md — the skill run by an independent agent in a clean context: the two tasks, the grades, and the documentation gaps that pass found.
• docs/SEMANTICS.md — what each check’s claim was measured against: the adversarial probes, the defects they found, and what is left unprobed with the reason.
• docs/LICENSING.md — why MIT, and acknowledgements.
• docs/agent-native-landscape.md — which domains are still empty.

Security

inspect reads the artifact by importing and running the Python file you give it — only run it on files you trust. shadergx additionally runs GLSL on your GPU. No tool makes network requests. Before publishing, run python scripts/prepublish_check.py.

License

MIT. Every package declares an SPDX License-Expression and ships its LICENSE in the wheel; see docs/LICENSING.md.