Mini Runner is an LLM-driven game agent for Lode Runner Total Recall, an HTML5 remake of the classic 1983 game Lode Runner. The project preserves the original game as the authoritative executor while adding a candidate agent, recording and replay tools, an agent evaluator, and a trace dashboard for decision-level debugging.
- Legacy game engine:
public/game/*owns physics, guard behavior, digging, death, level completion, rendering, demo recording, and demo playback. - Wrapper frontend:
src/*provides Vite bootstrapping, AI controls, stored-run playback, trace-aligned stepping, and the debug overlay. - Python backend:
app.pyexposes Flask APIs for planning, recordings, traces, model profiles, and local JSON stores. - Candidate agent:
agent/*analyzes each snapshot, generates and scores legal actions, asks the LLM to choose a candidate ID, validates the choice, and translates it into legacy key/tick input. - Trace tooling:
trace-dash.pyprovides a read-only Streamlit and pandas view of retained runs, individual decisions, outcomes, loop events, and candidate selection.
public/game/* Legacy Lode Runner runtime, levels, rendering, and demos
src/* Vite wrapper, recording/playback UI, and browser agent loop
agent/* Analysis, candidate generation, prompting, validation, and traces
app.py Flask APIs for planning, tracing, and recordings
trace-dash.py Streamlit and pandas agent-trace dashboard
scripts/* Sanity checks, evaluator, and offline trace analytics
__data1/ Local recordings, traces, evaluation reports, and debug logs
- Node.js
- Python 3.11+
- An API key for one supported LLM provider
git clone https://github.com/tombay3/mini-runner.git
cd mini-runner
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
npm installCreate .env.local with one model profile. For example:
AGENT_MODEL_PROFILE=openai
OPENAI_MODEL=gpt-5-nano
OPENAI_API_KEY=your_openai_api_keySupported profiles are openai, minimax, and gemini. Secrets belong in .env or
.env.local; non-secret experiment controls belong in public/agent-config.json.
The browser URL can override the configured profile for runs started from that page:
http://localhost:8283/?profile=minimax
Start the backend and frontend in separate terminals:
npm run apinpm run devOpen http://localhost:8283. Click AI to start or cancel an agent
run. Use Play, Prev, Next, and Delete to inspect retained recordings.
Use the read-only trace dashboard to compare runs and inspect each decision: state, candidates, model request, backend selection, issued input, and observed result. It reads existing stores without requiring the frontend or backend.
Start it in another terminal with the Python environment activated:
npm run dashOpen http://localhost:8601. It reads __data1 by default; use
AGENT_DATA_DIR or the sidebar path to choose another folder. Press Reload data after the
JSON changes. See Trace dashboard.
The wrapper stores replayable demos in __data1/recordings.json. Agent recordings link to
decision traces in __data1/agent-traces.json through traceId. See
Trace API and store for stored data.
Set AGENT_DEBUG_LOG=1 to write the latest 10 raw model I/O turns to
__data1/agent-debug.log. Raw prompts and model responses are excluded from normal traces.
For aggregate offline analysis, trace-analytics.ipynb reads recordings, runs, steps,
candidates, outcomes, loop events, and fallbacks without changing them.
To launch the trace notebook interface, run npm run notebook and open http://127.0.0.1:8081/.
Run the backend and frontend quick checks with:
npm testThese smoke checks use small fixtures and the Flask test client. They make no model calls.
| Command | Purpose |
|---|---|
npm test |
Fast code smoke checks |
npm run test:regression |
Focused Python and JavaScript regressions |
npm run data:check |
Read-only checks of local recordings, traces, cohorts, and debug log |
npm run cohorts:check |
Check cohort links and uncataloged traces |
See Testing for coverage and limitations.
Run repeatable attempts against the real browser game and configured model:
npm run eval -- --runs 5Use npm run eval -- --smoke to verify the browser, wrapper, backend, and legacy runtime
without calling the model. See Agent evaluator.
- Codebase overview: architecture, boot flow, and module map.
- LLM agent: snapshot flow, prompt, candidate selection, and loop filtering.
- Candidate design: scoring, action coverage, and validation.
- Backend spec: Flask APIs, JSON stores, model profiles, and logging.
- Trace dashboard: run signals, stepping debugger, and candidate analysis.
- Recording and playback: wrapper UI buttons, and run selection.
- Testing: smoke, regressions, data checks, and planner validation.
- Agent evaluator: repeatable real-runtime trials and reports.
- Puzzle game: Lode Runner rules and puzzle-solving concepts.
- Legacy runtime: original CreateJS architecture and features.
The game runtime is based on SimonHung/LodeRunner_TotalRecall.

