An AI-guided, Persona 5-inspired HUD for gamified life management.
Important
Arcana is designed to work best as an AI-assisted life management tool: the AI agent helps interpret updates, propose missions, and keep local JSON data coherent. For the intended visual experience, install the required fonts locally from legitimate sources; font files are not bundled with this repository or release builds. See Font Requirements.
Arcana is an AI-guided desktop HUD for turning real-life progress into structured game-like systems: status dimensions, missions, achievements, skills, inventory, and media history. It stores your data locally as JSON and uses an AI agent to help interpret updates, propose missions, track progress, and keep the system coherent over time.
Arcana is not a streak-based habit tracker or a toy stat sheet. It borrows the visual language and motivation loops of games, but the underlying data is real: personal milestones, ongoing goals, owned items, consumed media, and measurable status signals. The goal is not to pretend life is a game, but to give real life a sharper interface.
| Main Menu |
|---|
 |
| Status | Missions |
|---|---|
 |
 |
| Achievements | Skills |
 |
 |
| Items | Gallery |
 |
 |
Multi-dimensional life radar computed from real metrics.
- Status uses a three-layer model: raw metrics, scored dimensions, and Persona-style level titles.
- Dimension scores are calculated from weighted metric contributions, targets, ranges, or scoring brackets.
- System metrics (
sys_prefix) are derived automatically from other modules, such as gallery counts, skill levels, achievement stats, BMI, and game days. - Radar chart overview with drill-down into each dimension's contributing metrics.
Milestone tracking with content pack support.
- Record life milestones with unlock timestamps and difficulty grades (
beginnerthroughlegendary). - Achievements can have prerequisites, forming validated DAGs of dependencies.
- Content packs load achievement sets tailored to different interests, disciplines, and life domains.
- Pack navigation, difficulty filters, unlock sorting, and locked/unlocked visual states.
- AI agent can track partial progress, append progress notes, and mark completions.
Honeycomb-style skill progression tightly coupled with achievements.
- Each skill node maps to an achievement; unlocking achievements lights up the corresponding tree nodes.
- Skill levels are computed from accumulated node points and required key achievements.
- Interactive skill overview and honeycomb node map with achievement details, prerequisite status, and progress history.
- Loaded via content packs alongside achievements, so new packs can add both milestones and skill progression.
AI-driven quest system for current goals and next actions.
- Missions are proposed by the AI agent based on current goals and context, styled as Persona 5 "Phan-Site" requests.
- Lifecycle:
proposed→active→completed/archived/rejected. - AI-maintained 0–100 progress, deadlines, and completion timestamps.
- Main menu integration for countdowns, progress prompts, and rotating mission hints.
- Missions can link to achievements for cross-system progression.
Personal inventory with cost-over-time awareness.
- Track clothing, shoes, electronics, furniture, books, collectibles, and other possessions.
- Record purchase dates, prices, purchase channels, categories, images, and notes from local item files.
- Sort and compare by name, days owned, purchase price, and daily cost.
- Category summaries and item detail views turn ownership into a more mindful data surface.
Aggregated media consumption and play history hub.
- Unified view of anime, games, TV, movies, and books.
- Waterfall cover wall with category filters, rating/date/playtime sorting, and detail views.
- Tracks community ratings, personal ratings, tags, dates, episodes, playtime, and Steam achievement metadata where available.
- Import scripts for external sources:
- Bangumi (anime)
- Steam (games)
- Douban (movies/TV/books)
Arcana includes a built-in AI agent that acts as a personal life assistant. There are three ways to interact with it:
| Channel | Description |
|---|---|
| External AI harness | The primary interface — Claude Code, Codex, OpenCode, OpenClaw, Hermes Agent, or any agent that supports slash commands. Run /velvet-room or /phan-site directly in your AI coding tool. |
| Telegram | Optional bot adapter for mobile / remote access (agent-telegram). Compile and run only when needed. More IM channels may be added in the future. |
| Data CLI | Structured data operations used by AI skills and scripts (arcana-data). |
All paths share a common services layer (src-tauri/src/services/) and data format, so updates from any channel are immediately visible everywhere.
agent-cliis a minimal debug harness for testing the agent loop without Tauri. It is not needed for normal use.
The agent can:
- Read current status, missions, achievements, and memory context
- Update mission progress and status
- Track and mark achievements
- Propose new missions based on your goals
- Maintain cross-session memory for continuity
- Framework: Tauri v2 (Rust backend + webview frontend)
- Frontend: Svelte 5 + SvelteKit v2 + TypeScript + Tailwind CSS v4 + Three.js
- Backend: Rust (IPC commands, AI agent, JSON data layer)
- Data: Local JSON files (
data/, gitignored) — no database - AI: Direct Anthropic API integration with tool-calling loop
src/ # SvelteKit frontend
├── routes/ # Single-page app (main menu + sub-screens)
└── lib/
├── screens/ # Screen components (Status, Achievements, Skills, Items, Gallery, Missions)
├── components/ # Shared UI components (RadarChart, SkillNebula, etc.)
├── types/ # TypeScript type definitions
├── stores/ # Svelte stores
└── utils/ # Frontend utilities
src-tauri/src/ # Rust backend
├── commands/ # Tauri IPC commands (status, achievements, skills, missions, items, gallery, weather)
├── models/ # Serde data structures
├── storage/ # JSON read/write & validation
├── services/ # Shared business logic (used by agent, arcana-data CLI, and Tauri commands)
├── agent/ # AI agent subsystem (runner, LLM, tools, prompt, config, session)
└── bin/ # Standalone binaries: agent_cli, agent_telegram, arcana_data
data/ # Runtime JSON data (gitignored)
├── packs/<pack_id>/ # Content packs (manifest.json, achievements.json, skills.json)
├── sessions/ # Agent JSONL session history
└── *.json # missions, status, achievement_progress, mission_memory, etc.
docs/ # Architecture docs, schema specs, UI design guides
└── schema/ # JSON schema definitions
scripts/ # Python tooling (data import, schema validation)
static/ # Static assets (icons, images)
# 1. Install dependencies
npm install
# 2. Build the data CLI
cargo build --manifest-path src-tauri/Cargo.toml --bin arcana-data
# 3. Initialize your data directory
./src-tauri/target/debug/arcana-data init
# 4. Run the app
npm run tauri devAfter the app opens, the onboarding missions will already be active in the Missions screen. Run /velvet-room in any AI coding agent that supports slash commands (Claude Code, OpenCode, Codex, OpenClaw, Hermes Agent, etc.) to let the AI guide you through the rest of the setup.
Note
If you want to use the agent binaries — primarily agent-telegram, which starts a listener service for controlling your local assistant remotely via Telegram — you will need to configure an LLM provider. Set your API key via environment variable (ANTHROPIC_API_KEY) or config file (~/.arcana/agent_config.json). See AI Agent for details.
- Rust: stable toolchain
- Node.js: v18+
- Platform: Windows / macOS / Linux
Arcana's visual style depends on a few system fonts. These font files are not bundled with this repository or release builds; users need to install them locally for the intended Persona 5-inspired look:
p5hatty— primary display font for menus, labels, cards, and collage-style textSource Han Sans SC— Chinese UI and card-title textBebas Neue— key hint badges
If these fonts are missing, the app will still run, but the UI will fall back to system fonts such as Arial, Microsoft YaHei, or generic sans-serif, and some title/card layouts may look different.
The current UI was primarily developed on Windows at 4K resolution with 100% display scaling. It has also received light compatibility checks on Windows 4K at 125% scaling, Windows 2K at 100% scaling, and a MacBook Air 13-inch scaled desktop around 1710x1112.
Support for other resolutions, display scaling settings, and macOS/Retina scaled modes may still have layout issues. A more unified cross-resolution layout strategy is planned for follow-up work.
# Install frontend dependencies
npm install
# Run full desktop app in dev mode
npm run tauri dev
# Or run only the frontend dev server
npm run dev# Build desktop release
npm run tauri build
# Build the data CLI (required for AI skills and onboarding)
cargo build --manifest-path src-tauri/Cargo.toml --bin arcana-data
# Build agent binaries (optional / on-demand)
cargo build --manifest-path src-tauri/Cargo.toml --bin agent-telegram # Telegram bot; build when needed
cargo build --manifest-path src-tauri/Cargo.toml --bin agent-cli # Debug harness; not needed for normal use# TypeScript / Svelte type checking
npm run check
# Rust tests
cargo test --manifest-path src-tauri/Cargo.toml
# Rust formatting
cargo fmt --manifest-path src-tauri/Cargo.toml --checkArcana includes Python scripts for importing personal data, generating content packs, processing UI assets, and validating local JSON files.
Some data import scripts read credentials or user IDs from scripts/config.json. Use scripts/config.example.json as the template and keep real values local.
| Script | Purpose |
|---|---|
scripts/fetch_bangumi.py |
Fetch watched anime from Bangumi and write Gallery data. |
scripts/fetch_steam.py |
Fetch owned Steam games; --detailed also fetches achievements and store metadata. |
scripts/fetch_douban.py |
Fetch Douban movies, TV, and books; supports --status all. |
scripts/dev/process_assets.py |
Resize and prepare UI assets under static/ui/. |
scripts/dev/remove_bg.py |
Remove backgrounds from image files or folders. |
scripts/validate_data.py |
Validate runtime JSON data and content pack schema rules. |
python scripts/fetch_bangumi.py
python scripts/fetch_steam.py --detailed
python scripts/fetch_douban.py --status all
python scripts/validate_data.py data/missions.json- Architecture — Tauri, data layer, frontend, and agent architecture.
- Directory Structure — project layout and historical structure notes.
- Schema Reference — detailed JSON schemas for missions, achievements, skills, status, items, gallery, changelog, memory, and UI events.
- Visual Style Guide — Persona 5-inspired design principles, palette, typography, and interaction rules.
- UI Design Spec — main menu and sub-screen layout/interaction spec.
- AI Agent Integration — MCP/Nanobot integration proposal and agent platform research notes.
- Tauri + JSON over Electron + SQLite: Smaller binary, better performance, human-readable and version-controllable data files.
- Content Pack system: Achievements and skills are loaded via pluggable packs, supporting community extension.
- Agent decoupled from UI: The AI agent runs independently of the desktop GUI (CLI / Telegram), sharing the same data layer.
- Prerequisite-driven progression: Achievement prerequisites remain a validated DAG in the data model, while skills present that progression as a compact honeycomb-style node map rather than a traditional edge graph.
- Shared services layer:
services/contains all business logic, consumed by Tauri commands, arcana-data CLI, and the Rust agent alike.
- Onboarding wizard for first-time setup
- Sound effects across the interface
- Data-change reveal animations — show what changed since last session on first open
- Cinematic animations for mission acceptance and completion
- Skill tarot card generator — auto-generate a Persona-style card for each tracked skill (possibly with a generative model)
- Music tracking in Gallery (alongside books, anime, movies, games)
- AI navigator companion — a persistent on-screen assistant inspired by Futaba / Morgana from P5 (default look: Kurisu from Steins;Gate)
- User-facing changelog viewer — surface
ai_changelog.jsonin the UI so users can review, approve, and roll back AI-driven data changes - Diff view for AI modifications with one-click revert
- Support more IM channels (e.g. Discord, WeChat) and LLM providers beyond Anthropic
- More data source importers for Gallery and Status
- Deeper integration with external AI knowledge management systems
- Mobile read-only dashboard — a lightweight web view for checking Status radar and Mission progress on the go
- Health data auto-import — sync from Apple Health / Google Fit / Garmin to keep Status metrics up-to-date automatically
- Community content pack repository — let others publish and share achievement packs
- Mive82/Persona-5-Calendar — calendar component reference
- sjpiper145/MakerSkillTree — grid-based skill tree layout inspiration
- NERvGear/SAO-Utils — game-styled desktop app inspiration
- aliubo/persona-text-gen — collage-style (calling card) text generation reference
MIT