· A CONEJA-CHIBI PRODUCTION ·
A local studio for portable AI-roleplay content.
From the maker of BunnyMo, TunnelVision, and VectHare.
Create, edit, and keep your work in a studio linked to no platform. Publish it into a platform's format only when you choose.
Hoplight has three structural foundations:
- one canonical model in the middle
- one honest adapter per platform
- one local library of plain JSON files
- What is Hoplight?
- Install
- The format problem
- How it works
- One card, start to finish
- The Studio
- The CLI
- Supported formats
- Safety and privacy
- Project status
- Architecture
- Contributing
Hoplight is a local studio for AI-roleplay work. Characters, lorebooks, personas, presets, regex sets, and sprite packs live together instead of being scattered across the apps that consume them. Its primary surfaces are:
- Library for importing and organizing content
- Workbench for authoring and editing pieces
- Binder for editing lorebooks
- Press for exporting to platform formats
The Studio copy is authoritative. Platforms are export targets.
When you import something, Hoplight maps it into a canonical piece and keeps the original source and unmapped platform fields in escrow. When you export, an adapter writes the target format and reports what was exported, what was retained locally, and what the target cannot represent.
Download the latest build from Releases.
| Platform | Download | Run |
|---|---|---|
| Windows | Hoplight.exe |
Double-click it |
| macOS | hoplight-cli-darwin-arm64 or hoplight-cli-darwin-x64 |
chmod +x, run it with ui, open the printed address |
| Linux | hoplight-cli-linux-x64 or hoplight-cli-linux-arm64 |
chmod +x, run it with ui, open the printed address |
Windows may show a SmartScreen warning because the binary is unsigned. Releases include
SHA256SUMS if you want to verify the download. If the app starts without opening a window, install
Microsoft WebView2.
Your pieces live in Documents/Hoplight Studio. Updating or replacing the app does not replace
that folder.
You need Bun 1.3 or newer.
git clone https://github.com/Coneja-Chibi/Hoplight
cd Hoplight
bun install
bun run devThe Studio binds to loopback. Open the local address it prints.
Hoplight does not update itself. Use Settings > About > Check for updates, then replace your downloaded binary with the new release.
For a source checkout:
git pull
bun installRestart Hoplight afterward. Your Studio library stays where it is.
Drop a card, book, preset, or archive into the Library. Hoplight detects the format, imports every piece it can identify, and gives you a plain-language receipt.
Example commands:
bun run hoplight formats
bun run hoplight inspect samples/sillytavern/characters/Seraphina.png
bun run hoplight convert samples/sillytavern/characters/v3-full.json out.charx --to risuThe ecosystem does not have one card format with different file extensions. It has related and unrelated formats with different capabilities:
- SillyTavern uses raw JSON, embedded PNG data, and charx containers.
- RisuAI builds on CCv3 with its own modules and archive behavior.
- RoleCall and Agnai have native fields with no direct CCv3 slot.
- Lumiverse, Marinara, and Chub use different extension bags.
- Backyard has both legacy JSON and its own archive.
- NovelAI lorebooks are a separate family entirely.
A file opening in two apps does not mean those apps read the same fields. Copies also drift as soon as you edit them independently.
Hoplight keeps one canonical piece and translates at the boundary:
| Platform-bound workflow | Hoplight |
|---|---|
| One copy per app | One master with many publish targets |
| Embedded lorebook welded into a card | Linked, separately editable pieces |
| Export losses discovered afterward | Coverage and readiness shown before export |
| Platform-owned storage | Plain files in a folder you control |
| Imported scripts trusted by default | Sealed data with explicit test benches |
Platform editors are built to make content work inside that platform. That is their job. They cannot reliably show another platform's view of the same piece.
Hoplight's editor lens can:
- dim or hide fields the selected target does not carry
- show native platform fields without turning the editor into a JSON dump
- use the same coverage declarations as export readiness
- keep linked characters, lorebooks, and media synchronized at publish time
If a platform disappears, you lose a publish target, not your source library.
Every format maps to and from one canonical model. Adapters never convert directly into one another.
SillyTavern ──┐ ┌── RisuAI
Backyard ─────┤ ├── RoleCall
Agnai ────────┤ canonical ├── Chub
Pygmalion ────┤ model ├── Lumiverse
NovelAI ──────┤ ├── Marinara
CCv3 ─────────┘ └── your Studio JSON
Direct format-to-format conversion grows toward N². A canonical hub needs one adapter per format.
Adding a platform is a folder under src/formats/; the registry, CLI, Studio, and Press discover it.
Real fixtures and round-trip tests verify the adapter's claims.
Import does not discard data just because the canonical model lacks a first-class field for it. Hoplight stores:
- the parsed source snapshot
- unmapped platform fields
- links to extracted pieces such as embedded lorebooks
Same-format exports obey the semantic Round-Trip Law. Formats with an explicit byte-level tier must prove that stronger guarantee with fixtures. Cross-format exports report uncovered fields instead of pretending every concept has an equivalent.
Cards can carry Lua, macros, and regex rules. Hoplight treats them as data during import, conversion, storage, and export.
Execution is user-invoked only inside the isolated Lua or regex test bench. There is no second execution path hidden in an adapter or import hook.
Drop Seraphina.png into the Library
↓
Detection identifies a SillyTavern character card
↓
The receipt names the character, portrait, greeting, and embedded lorebook
↓
The original source and unmapped fields enter escrow
↓
The embedded lorebook becomes a linked, editable piece
↓
Open the character on the Workbench with the RisuAI lens
↓
Fields Risu cannot carry are visible before export
↓
Stage the character and include the linked lorebook
↓
The Press writes a charx bundle and an honest result report
The Studio copy remains the source of truth throughout.
The Studio surfaces share one engine, one Studio folder, and one set of canonical entities.
The Library handles import, organization, and batch selection.
- Decks separate characters, lorebooks, personas, packs, presets, and regex sets.
- Grid, showcase, list, and gallery views suit different kinds of work.
- Import receipts explain what arrived and where linked pieces came from.
- Multi-select can stage a batch for the Press.
- Shelf operations expose relevant verbs such as duplicate, merge, split, attach, and combine.
- Right-click menus come from one shared system rather than one-off controls.
The Library reads the disk. Counts and pieces reflect the Studio folder, not a second database.
Library details
Each deck exposes operations relevant to its content type. Lorebooks can split or merge, regex sets can combine, and characters can attach or detach linked books. Operations that would destroy or overwrite content require an explicit choice.
The art dial continuously changes card density instead of forcing a few hardcoded sizes. Open Beside pins two pieces into a split workspace, including two entries from the same lorebook.
The Workbench contains the editors.
- Canonical fields remain the stable center.
- Platform tabs expose native field bags only where the platform owns them.
- The lens shows target coverage while you write.
- Readiness summarizes missing, incompatible, or platform-specific content.
- Media tools manage portraits, sprites, expression maps, and referenced assets.
- Tabs and splits belong to the Studio shell, so open work survives room changes.
The editor does not silently rewrite escrow or flatten unknown platform data.
Character and media details
Character editing covers identity, voice, scenario, greetings, examples, creator metadata, linked knowledge, platform-native extensions, and media. Portrait and sprite ownership remain explicit so an export can say which assets fit the target container.
The guided interview can grow a card from answers without making the form disappear. Every result still lands in normal editable fields.
Regex bench
Regex rules are stored data. The bench can test a selected rule against sample text in a terminable worker with a hard deadline. Importing a regex set never runs it.
The Binder is the lorebook editor.
- A table of contents keeps the whole book visible.
- Entries expose primary and secondary triggers, logic, probability, timing, and placement.
- Budget estimates show which entries fit and why another was evicted.
- Health checks find dead triggers, impossible conditions, duplicate keys, and other repairable problems.
- Write-For lenses show which controls a target format owns.
- The activation simulator explains why an entry fired, slept, or lost the budget.
Linked lorebooks remain independent pieces. Editing a book updates the version available to linked characters at export time.
The Press turns staged pieces into target files.
- Stage single pieces or a mixed batch.
- Linked lorebooks can be included with their character as a bundle.
- Readiness runs before export.
- Filename controls remain visible before files are written.
- Each result row reports success, warnings, and uncovered fields.
- Batch output can become one zip without hiding per-file results.
Formats cannot carry every concept. The Press reports unsupported fields before and after export.
The CSS Workshop edits theme tokens against real Studio components. Settings owns appearance, Studio location, provider configuration, updates, and other global choices.
Detailed surface documentation lives in docs/reference/ui.md, and shared controls are cataloged in docs/reference/components.md.
The CLI is another shell over the same engine.
| Command | Purpose |
|---|---|
hoplight inspect <file> |
Describe a file in plain language |
hoplight validate <file> |
Detect and parse; exit 0 when openable |
hoplight label <file> |
Identify likely format and origin |
hoplight convert <in> <out> [--to id] |
Convert through the canonical model |
hoplight formats |
List installed adapters |
hoplight ui [port] [studioDir] |
Start the visual Studio |
Add --json to validate, formats, or convert for machine-readable output. Inspect currently prints
human-readable detail; the CLI reference records the exact current contract.
Kit, the interactive TUI, is an active-development preview available from a source checkout with
bun run kit. It uses progressively disclosed tools, preview-before-apply changes, and the same
Studio backend rather than a parallel agent filesystem. Kit is not included in the current GitHub
release binaries.
Hoplight currently covers formats from:
- SillyTavern and portable CCv2/CCv3
- RisuAI
- RoleCall
- Backyard
- Agnai
- Pygmalion
- Lumiverse
- Marinara
- Chub
- NovelAI lorebooks
Support varies by content kind, direction, and field. The generated format matrix is the source of truth.
Hoplight is local-first and fail-closed:
- Studio content is plain JSON in a folder you control.
- The local server binds to loopback by default.
- Remote access is an explicit, separately authenticated mode.
- Paths resolve inside the configured Studio root.
- Writes use create-only or atomic replacement behavior.
- Input is schema-validated at the boundary.
- Archives and request bodies have hard size limits.
- Imported scripts remain sealed except in explicit isolated test benches.
- Provider use is opt-in and configured by the user.
Read SECURITY.md for the threat model, implementation detail, and private reporting address.
The default Studio is local and has no account. Provider calls happen only when you configure and use provider-backed features. Remote access must be enabled explicitly.
Hoplight stores the imported source snapshot and unmapped data in escrow. Same-format round trips must meet the adapter's declared fidelity tier. Cross-format output includes a loss report because some concepts genuinely have no destination.
No for importing, editing, inspecting, validating, converting, or deterministic analysis. Provider-backed Kit and generation features are optional and use your configured provider.
Not during import, conversion, storage, or export. Execution exists only in explicit isolated test benches.
Yes. Format adapters are drop-in folders. Start from src/formats/_template/, include real
fixtures, and prove the round trip.
So the community can keep improvements to the Studio available. See LICENSING.md for the plain-language explanation.
Roughly 60/30. The 60 is AI writing code. The 30 is me: drafting, planning, project management, design, and testing. Everything merges through the same gates regardless of who typed it: the test suite, the round-trip law, and the CI guards. Bugs get fixed the same way too.
Hoplight is in active development.
| Area | Status |
|---|---|
| Canonical engine, detection, conversion, escrow | Live |
| Character, lorebook, persona, media, preset, and regex workflows | Live and expanding |
| Local Studio and Press | Live |
| CLI | Core commands live |
| Kit TUI and studio agent | Active development |
| Test Stage, productions, history, and advanced creative tools | Planned or partial |
Milestones are complete only after live verification in a real install. See docs/ROADMAP.md for current exit criteria and sequencing.
Hoplight uses Bun and strict TypeScript. The engine is pure where possible; filesystem, server, provider, and UI effects stay at the edges. The CLI, Studio, and Kit share the same engine.
src/
core/ canonical model, detection, coverage, lore/regex/macro engines
entities/ one canonical schema per content kind
formats/ one drop-in adapter folder per platform
studio/ local storage, path containment, atomic writes
sandbox/ sealed-script analysis and explicit test benches
ui/ loopback server and React Studio
kit/ interactive TUI, tools, provider loop, staged changes
cli.ts argv-shaped shell over the engine
Folders are the schema. Format adapters, apps, settings sections, tours, and other extensible surfaces register by existing rather than by editing a central list.
Start here:
| Document | Purpose |
|---|---|
| Vision | Product boundaries and audience |
| Architecture | Canonical model and system shape |
| Conventions | Code and repository doctrine |
| Reference | Current surfaces and formats |
| Decisions | Consequential choices and reasoning |
Read CONTRIBUTING.md and AGENTS.md before changing code.
Every change needs proof. Bug fixes begin with a failing test; UI behavior needs live verification; format work must preserve escrow and satisfy the round-trip law.
AI-assisted contributions are welcome. Disclose the model used in the pull request.
bun run verify:ciHoplight is licensed under AGPL-3.0. See LICENSING.md.
Your favorite rabbit's favorite rabb perfectly normal woman. ✨