# Whimbox: the Python backend behind an AI assistant for Infinity Nikki

> Whimbox is a GPL-3.0 Python 3.12 backend that drives Infinity Nikki through screen capture and simulated input, with an LLM agent deciding which task scripts to run. The app UI lives in a separate repository, which changes who can realistically adopt it.

**nikkigallery/Whimbox** — Whimbox AI . ~~ ~~ Whimbox Whimbox AI \ 2.0 app app UI rpc 1.

- Repository: https://github.com/nikkigallery/Whimbox
- Website: https://nikkigallery.vip/whimbox/intro
- Stars: 397 · Forks: 38
- Language: Python
- License: GPL-3.0
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/nikkigallery-whimbox

## What Whimbox automates in Infinity Nikki, and for whom

Whimbox is a backend for an AI agent that plays parts of Infinity Nikki for you. The README lists the covered ground: daily tasks (美鸭梨挖掘, 素材激化幻境, 闪光祝福幻境, 魔物试炼幻境, weekly bosses, 朝夕心愿, 星海拾光, star crystal collection, the monthly card claim, and 奇迹之冠巅峰赛), automatic small actions such as dialogue skipping, gathering, fishing and cleaning, route recording and playback for the open world and 星海, macro recording and playback, MIDI-to-script conversion for the in-game piano, and natural-language control through an LLM. The audience is narrow by design. The README states the project is a backend only, with no UI, and that the app lives in a separate repository (nikkigallery/whimbox_app). It also states that image recognition costs extra performance on top of what the game already consumes, so only mid-to-high-end PCs are supported for now, with a cloud version listed as future work. If you want a tool you install and click, this is not that. If you want a Python service you can drive over RPC and extend with your own task scripts, the repository is laid out for exactly that.

## The agent loop: LangGraph, OCR, YOLO and simulated input

The architecture is visible in the directory tree rather than in prose. whimbox/interaction/ handles the core loop of screenshotting and operating the machine, whimbox/api/ wraps third-party models for OCR and YOLO, whimbox/map/ does minimap recognition and big-map operation, whimbox/task/ holds the feature scripts the agent calls, and whimbox/agent_workspace/ manages the large-model context. The dependency list confirms the shape of the stack: langchain, langgraph, langgraph-prebuilt and provider packages for OpenAI, Anthropic, DeepSeek and Google GenAI on the agent side, and onnxruntime plus rapidocr on the perception side, with pynput for input and mss for screen capture on macOS. So the data flow the README implies is: capture the screen, run detection and OCR to get game state, let the LLM choose among registered task scripts, execute them through simulated mouse and keyboard events, then feed the result back into the agent context. Two design details are worth flagging. First, the README states Whimbox does not modify game files or read game memory, only screenshots and simulated input, which is why it claims a theoretical lower ban risk, while also stating that the game's terms are broad enough to cover everything and that consequences are the user's. Second, the project acknowledges openclaw and nanobot as the source of its AI layer, and cites GIA and BetterGI as prior art in the same genre. That lineage matters when you evaluate the agent: it is an orchestration layer over existing automation scripts, not a learned controller.

## Installing Whimbox and running one real task

The README is explicit that the supported path is the app, and that the backend no longer ships a UI. It also states the project supports Python 3.12 only, and pyproject.toml pins requires-python to ==3.12.8, so a 3.12.9 interpreter will not satisfy the metadata. The package declares a console entry point named whimbox, so a source install exposes a `whimbox` command.

```bash
python3.12 -m venv .venv
source .venv/bin/activate
pip install .
whimbox
```

On Windows the activate step is `.venv\Scripts\activate`. What you should see after `whimbox` is the backend starting; the README does not document its console output, so treat any startup banner as unverified. The README's recommended workflow is to get a run working through the app first, then use the command line for headless runs.

The documented command-line flow for a full daily run is a three-step configuration, not a flag. First, confirm the run works in the app. Then, in the run configuration, enable the option the README calls "启动奇想盒时，自动运行一条龙" (start the daily run automatically when Whimbox starts). Then launch the app executable:

```bash
whimbox_app.exe
```

If you also want the game and Whimbox to close when the run finishes, the README points to a second checkbox in the same configuration, "一条龙结束后，关闭游戏和奇想盒". Both are UI settings inside the app, and the README does not give a config file path or environment variable for either, so there is no documented way to set them from the command line alone.

## Where Whimbox breaks: resolution, hardware and the missing UI

The constraints in the README are the honest part of the project. Whimbox only supports games running at a standard 16:9 resolution. If you play windowed at an unusual aspect ratio, ultrawide, or on a laptop panel with a different ratio, the screen-capture and coordinate logic has no documented fallback. The project also states that only mid-to-high-end PCs are supported because image recognition competes with the game for resources, and that a cloud version is planned rather than available. Macro recording has a stated gap too: it records and plays back operations but does not support camera rotation, which limits what recorded macros can reproduce in a 3D world. Auto route playback is limited to the open world and 星海, not every mode. The largest practical limitation is structural. Because the UI is a separate repository, a backend-only install gives you RPC services, model calls and tool calls, and nothing to click. Anyone who clones nikkigallery/whimbox expecting the app described on the homepage will be confused until they find the app repository. Finally, the README's development section says "等我梳理项目框架..." (waiting for me to organize the project framework), which is a direct statement that contributor documentation is not finished. The repository has tests/ and .github/ directories, but the README does not describe how to run the tests, so a new contributor has no documented verification path.

## Whimbox compared with BetterGI and GIA

The README itself names the closest alternatives: 原神小助手·GIA and 更好的原神·BetterGI, both open source automation projects for Genshin Impact, cited as prior art Whimbox learned from. The difference in approach is the target game and the control layer. BetterGI and GIA automate a different title with their own vision pipelines and their own task sets, and neither is a drop-in for Infinity Nikki. Within the same genre, the more interesting comparison is against script-only macro tools. A conventional macro replays a fixed sequence of inputs and fails the moment the game state diverges. Whimbox adds an LLM agent on top of its task scripts, with the README listing natural-language execution of the listed features, partial SKILL support, and remote control through WeChat as current capabilities, plus a future plan for the model to take over and correct errors when a script fails. That is a real architectural difference, and it is also where the project is least proven: the error-correction behavior is listed under 未来计划, not under 已有功能. If you need deterministic, auditable automation today, a plain macro recorder is easier to reason about. If you want the agent to pick and sequence tasks from a sentence, Whimbox is the one in this space that documents that intent.

## Licence, maintenance and what an upgrade costs you

Whimbox is GPL-3.0, declared through license-files in pyproject.toml with the LICENSE file at the repository root. For end users this changes nothing about running it. For anyone who wants to ship a modified Whimbox, bundle it into another product, or link it into a closed-source tool, the copyleft terms apply to the distributed work, and that is a decision to take to a lawyer rather than to a README. The maintenance picture is active: the last push was on 2026-08-28, and the 3.0.x release notes show a steady cadence, with 3.0.1 on 2026-08-21 (map overlay optimization, 械控 ability support, bug fixes), 3.0.2 on 2026-08-27 (treasure chests and 奇想星 now shown on the minimap), and 3.0.3 on 2026-08-28 (fixing a bug where the map overlay could not log in to the b服 and international servers). Note that pyproject.toml declares version 3.0.5 while the newest listed release is 3.0.3, so the packaged version and the release tag are not in lockstep. Upgrading is not free in either direction: the dependency set pins exact versions across the LangChain stack (langchain==1.3.15, langgraph==1.2.11, langchain-core==1.5.6 and provider packages), and requires-python is an exact 3.12.8, so a Python minor bump or a LangChain major bump is a coordinated change rather than a routine one. The release notes being written in Chinese also means non-Chinese readers depend on translation for bug-fix detail.

## Conclusion

Whimbox is for players willing to run a Python 3.12 backend on a mid-to-high-end Windows PC and accept that the UI is a separate download from nikkigallery/whimbox_app. It is not for anyone on a 16:9-excluded resolution, a low-spec machine, or a non-Windows host who wants the feature set the README describes, since the dependency markers only cover macOS capture and the project has no documented CI or test instructions. Before installing, confirm which Python build you have (pyproject.toml pins ==3.12.8), check the release notes for the current 3.0.x build, and read the game's terms of service yourself, because the README puts all consequences on the user.

## FAQ

### Does Whimbox have a user interface?

The backend repository does not. The README states that Whimbox is the backend, no longer provides a UI, and only handles RPC services, large-model calls and tool calls; the app is in the separate nikkigallery/whimbox_app repository.

### Which Python version does Whimbox require?

The README says the project supports Python 3.12 only, and pyproject.toml pins requires-python to ==3.12.8. A newer 3.12 patch release will not satisfy that exact pin.

### Can I run Whimbox on a low-end PC?

The README states that only mid-to-high-end PCs are supported, because the game already consumes significant performance and image recognition adds more. A cloud version is listed as future work, not as an available option.

### How do I start the daily run from the command line?

The README's method is to first confirm the run works through the app, then enable "启动奇想盒时，自动运行一条龙" in the run configuration, then launch whimbox_app.exe. The README does not document a command-line flag that starts the daily run directly.

## Sources

- [Official documentation](https://nikkigallery.vip/whimbox/intro)
- [Official README](https://github.com/nikkigallery/Whimbox#readme)
- [Project repository](https://github.com/nikkigallery/Whimbox)
- [Release notes](https://github.com/nikkigallery/Whimbox/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nikkigallery-whimbox