CullAI

Cut the excess. Ship lean.

Audits indie UE5 and Unity codebases for performance debt — dead scripts, oversized assets, near-duplicate code — and hands you a ranked, dry-run fix report.

pip install -e .
cullai analyze ./your-project

Contents

• What it does
• Install
• Usage
  • CLI
  • Web UI
• Checks
• Project structure
• Constraints
• Roadmap
• License

What it does

cullai analyze <project-path> walks a project directory, collecting .py / .cs source files and common game-asset files. It runs three static checks against that set, writes every finding to cullai-report.json in the project root, and prints a styled terminal summary. v0 is dry-run and read-only — nothing in your project is ever modified.

Install

Requires Python 3.9+.

git clone https://github.com/OperaHouse-Ventures/cullai.git
cd cullai
pip install -e .

This registers the cullai command and installs its dependencies (click, rich, fastapi, uvicorn).

Usage

CLI

cullai analyze ./your-project

Example output:

CullAI — Audit Complete
Severity   Count
CRITICAL   0
WARNING    5
INFO       0

Top issues
  Scripts/LegacyPickup.cs — LegacyPickup is not referenced by any other script in the project.
  Assets/Textures/Hero.png — Hero.png is 11.0 MB.

Run `cullai fix --dry-run` to preview changes.

The full ranked list — every issue, not just the top 5 — is written to <project-path>/cullai-report.json:

[
  {
    "severity": "WARNING",
    "file": "Scripts/LegacyPickup.cs",
    "issue_type": "dead_code",
    "description": "LegacyPickup is not referenced by any other script in the project.",
    "suggested_action": "Confirm LegacyPickup.cs is still in use, then remove it if not."
  }
]

A hand-crafted fixture project lives at sample-project/ if you want to try cullai analyze without pointing it at a real codebase.

Web UI

A local FastAPI + vanilla JS chat interface wraps the same pipeline for browser testing — no separate install, it reuses cullai's scan/check/report code directly.

python -m web.backend.app
# open http://127.0.0.1:8000

Point it at a project path to run a real analysis, then follow up in the same conversation:

Message	Result
./your-project or C:\path\to\project	Runs analyze, same pipeline as the CLI
show critical	Filters the last report to CRITICAL issues (no new scan)
show warnings	Filters the last report to WARNING issues
show all	Shows the full last report again
help	Lists what the assistant can do

The web UI doesn't call an LLM — it's a small deterministic command parser over the same real data the CLI produces.

Checks

Check	Trigger	Severity
Dead scripts	.py / .cs files never referenced by name elsewhere in the project	WARNING
Oversized assets	Any asset file over 10 MB	WARNING (CRITICAL over 50 MB)
Near-duplicate code	File pairs with over 80% line overlap	WARNING

Project structure

cullai/
  cli.py          Click entrypoint — cullai analyze <path>
  scanner.py      Directory walker + file collector
  models.py       Issue dataclass
  reporter.py     JSON report writer + Rich CLI summary renderer
  checks/
    dead_code.py  Unreferenced script detector
    asset_size.py Oversized asset flagging
    duplicates.py Line-hash similarity check
web/
  backend/app.py  FastAPI app — reuses cullai/ directly, serves the frontend
  frontend/       Vanilla HTML/CSS/JS chat interface
sample-project/    Fixture project for trying cullai analyze

Constraints

v0 is intentionally narrow:

• Dry-run only. Nothing writes to your project — cullai-report.json is the only file CullAI produces.
• No LLM calls. Both the CLI and the web UI are pure static analysis; the chat interface's "assistant" is a deterministic command parser, not a model.
• No auto-fix yet. analyze is the whole feature. Auto-apply, dry-run fixes, and rollback are future work (see Roadmap).

Roadmap

CullAI's target trust architecture, once fix-application ships:

cullai analyze → cullai fix --dry-run → cullai fix --apply → cullai revert

Every future fix will propose a plain-language explanation, apply dry-run only by default, require an explicit --apply flag for real changes, open a git branch + PR rather than committing directly, and stay revertible via cullai revert. The longer-term MVP is a browser-based web app with OAuth repo connect — the local web UI in web/ is a test harness toward that, not the MVP itself.

License

MIT — see LICENSE.