🧪 AI Playground

A collection of AI-powered app experiments built with various tools and frameworks.

📁 Projects

meridian

Meridian — an agentic build pipeline that turns a one-line goal (e.g. "create a todo web app") into a working project by looping a small team of specialised LLM agents through Brainstorm → Plan → Write tests → Implement → Review. When a feature passes review, Meridian auto-picks the next feature from its backlog and starts the loop again; when review fails it retries the Implementer; after MERIDIAN_MAX_REVIEW_ATTEMPTS failures the feature is escalated and the run moves on.

• Stack: Python 3.10+, LangGraph (state machine with conditional edges + SQLite checkpointer), LangChain tools, FastAPI + WebSocket, Typer CLI, Rich terminal UI, Pydantic v2 / pydantic-settings, python-dotenv
• Agents (5 roles): Brainstormer (goal → ordered backlog), Planner (markdown plan per feature), TestWriter (writes failing tests using fs/shell tools), Implementer (writes code + iterates until tests pass), Reviewer (independent critique + final test run, deliberately a different model from the Implementer)
• Pluggable LLMs: Anthropic Claude, Google Gemini, OpenAI — with a role→model registry. Default "balanced" assignment uses Claude for build agents and Gemini for brainstormer + reviewer; falls back to a single provider when only one API key is set; per-role override via MERIDIAN_MODELS JSON env var.
• Sandboxed execution: every generated project lives at meridian/workspaces/<slug>/; the Workspace class rejects absolute paths and .. escapes; run_command accepts only an allowlist of binaries (pytest, python, pip, node, npm, npx, pnpm, yarn, git, ls, cat, echo, mkdir, rm, mv, cp, touch).
• Resumability: LangGraph SqliteSaver checkpoints every step to meridian/.meridian/checkpoints.sqlite; meridian resume <run-id> re-enters the graph mid-loop after a crash or Ctrl+C.
• Dashboard: FastAPI app with REST + WebSocket (/ws/runs/{id}) streaming live StepLog events to a single-page UI (web/static/index.html) — backlog with status pills (pending / in_progress / done / escalated), current step indicator, and a live agent log tail. CLI and dashboard share the same start_run() entry point.
• CLI: meridian build "<goal>", meridian resume <run-id>, meridian list, meridian dashboard, meridian models (prints the resolved role→provider/model mapping)
• Tests: 18 passing — workspace sandbox enforcement, state factories, and a full LangGraph smoke test with mocked agents covering happy path, retry-then-pass, and escalation after max_review_attempts. No network or API keys required to run the suite.

Quick start:

cd meridian
python3 -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'
cp .env.example .env
# Add at least one of: ANTHROPIC_API_KEY, GOOGLE_API_KEY, OPENAI_API_KEY
meridian models                                # confirm role assignments
meridian build "create a todo web app with FastAPI and a single HTML page"
# or
meridian dashboard                             # http://127.0.0.1:8765

Notes on free-tier Gemini: the agentic loop fires many requests per minute; Google's free-tier per-minute and per-day caps for gemini-2.0-flash are easy to exhaust. If you see RESOURCE_EXHAUSTED (429), either wait for the per-minute reset (~30s), pin lighter models via MERIDIAN_MODELS='{"...":"gemini:gemini-1.5-flash-8b"}', or add an ANTHROPIC_API_KEY so the registry switches to the balanced Claude + Gemini default.

Documentation: meridian/README.md — architecture diagram, role table, model-routing reference, and safety notes.

---

qt_migration_agent

qmigrate — a hybrid (rules + optional Claude) Qt 5 -> Qt 6 migration agent that scans C++, QML, PySide2, qmake, and CMake source trees, categorizes every deprecated or removed API against a pack of 52 rules, generates unified-diff patch files you can apply with git apply, and writes a MIGRATION.md progress report. Claude reviews low-confidence diffs and narrates the report when an API key is set; the agent runs fully offline without one.

• Stack: Python 3.10+, libcst (Python AST for PySide2->6 transforms), LangChain + Anthropic (optional Claude reviewer + summarizer), Typer CLI, Rich terminal UI, Pydantic v2 / pydantic-settings, Jinja2 (HTML report), stdlib difflib.
• Rule pack (52 rules): C++ — QRegExp, QLinkedList, Qt::MidButton, stream manipulators, qrand(), enterEvent signature, QSignalMapper, QTextCodec, QDesktopWidget, QMouseEvent::pos(), AA_EnableHighDpiScaling, #include reroutes, QMetaType::type, QFontMetrics::width. QML — versionless imports, QtQuick.Controls 1.x removal, Qt.labs.settings move, QtGraphicalEffects. PySide2->6 — from PySide2 rewrite (via libcst), .exec_(), SIGNAL()/SLOT() string syntax, QAction move, shiboken2. Build — find_package(Qt5), Qt5:: targets, qt5_* helpers, CMAKE_CXX_STANDARD < 17, qmake c++14, removed modules.
• Safety model: diffs written under <project>/.qmigrate/patches/ by default; --apply rewrites sources in place, requires a clean git tree (or --force); timestamped backup written before every in-place change. --rule <id> to apply one rule family at a time.
• LLM layer: findings with confidence < threshold (default 75) routed to Claude; without a key, high-confidence identifier swaps are auto-approved and low-confidence ones are escalated to needs_human. Reviewer is advisory only — it annotates, never rewrites unilaterally.
• Tests: 67 passing in ~1s, fully hermetic — scanner, per-rule positive+negative cases, patcher diffs (including git apply --check validation), report golden-section checks, agent mock + graceful-degrade, end-to-end smoke on the bundled mini_qt5_app fixture.

Quick start:

cd qt_migration_agent
python3 -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'
cp .env.example .env
# Optional: add QMIGRATE_ANTHROPIC_API_KEY for LLM review + narrative.

qmigrate run /path/to/your/qt5/project     # scan + diff + MIGRATION.md in one pass
qmigrate rules list                        # browse the full rule taxonomy
qmigrate patch /path/to/project --apply   # rewrite sources (requires clean git tree)

Documentation: qt_migration_agent/README.md

---

gwtbridge

GwtBridge — a GWT → modern stack migration platform that scans legacy Google Web Toolkit Maven projects (client + server), builds an intermediate representation, and emits React (MUI) components, OpenAPI 3, and Spring Boot REST stubs—with optional Claude review for low-confidence mappings.

• Stack: TypeScript monorepo (pnpm), java-parser, fast-xml-parser, commander CLI, optional @anthropic-ai/sdk
• Pipeline: scan → ProjectIR → rules (MUI mappings) → emit → report (+ optional review)
• CLI: gwt-bridge scan, migrate, review, report, config
• Hybrid AI: rules emit deterministically; Claude annotates low-confidence items (GWTBRIDGE_ANTHROPIC_API_KEY, --review); fully offline without a key
• Tests: 11 passing — IR validation, Java/RPC parser, rules, agent offline policy, mini-gwt-app integration

Quick start:

cd gwtbridge
pnpm install && pnpm build && pnpm test
pnpm exec gwt-bridge migrate examples/mini-gwt-app --out ./migrated --no-review

Documentation: gwtbridge/README.md

---

recall

Recall — a RAG Q&A system over selected ai-playground projects. Indexes code and READMEs from heartbot, qt_migration_agent, and gwtbridge, retrieves relevant chunks with Chroma, and answers natural-language questions with file:line citations grounded only in retrieved sources.

• Stack: Python 3.11+, Chroma, FastAPI, Typer, Rich, optional OpenAI embeddings + Anthropic chat (or local Ollama)
• Pipeline: index → chunk → embed → Chroma; ask → retrieve → LLM + sources → citations
• CLI: recall index, ask, serve, eval, stats, config show
• Web UI: React 19 + Vite + Tailwind 4 dark chat (recall/web/)
• Evals: 12 golden retrieval questions in evals/golden.json
• Tests: hermetic pytest suite with mock embed/LLM (no network required)

Quick start:

cd recall
python3 -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'
recall index
recall ask "How does HeartBot handle pause?" --project heartbot
recall eval

Documentation: recall/README.md

---

retriva

Retriva — retrieval-first trivia grounded in Wikipedia. Indexes article sections into Chroma, retrieves relevant chunks, and has an LLM write multiple-choice questions only from source text. A deterministic validator rejects hallucinations; a deterministic grader scores answers without calling the LLM.

• Stack: Python 3.11+, Chroma, FastAPI, Typer, Rich, httpx (Wikipedia REST), optional OpenAI embeddings + Anthropic chat (or local Ollama)
• Pipeline: index → Wikipedia → chunk → embed → Chroma; play → retrieve → LLM (JSON) → validate → grade
• CLI: retriva index, play, generate, serve, eval, stats, config show
• Web UI: React 19 + Vite + Tailwind 4 quiz UI (retriva/web/)
• Evals: 10 golden cases in evals/golden.json (retrieval + validation + generate)
• Tests: hermetic pytest with Wikipedia fixtures (no network required)

Quick start:

cd retriva
python3 -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'
cp .env.example .env
retriva index
retriva play --topic Chess --rounds 5
retriva eval

Documentation: retriva/README.md

---

pantrybound

Pantrybound — pantry-only recipes with no invented ingredients. You list what is at home; an LLM returns structured JSON; a deterministic validator ensures every ingredient is in your pantry or an allowed staples list (salt, oil, …); diet and skill rules are enforced in code; a shopping-list diff shows what you still need to buy.

• Stack: Python 3.11+, FastAPI, Typer, Rich, optional Anthropic or Ollama (mock for offline/tests)
• Pipeline: cook → LLM (JSON) → validate → recipe + shopping_diff
• CLI: pantrybound cook, validate, diff, eval, serve, config show
• Web UI: React 19 + Vite + Tailwind 4 (pantrybound/web/, port 5174)
• Evals: 18 golden cases in evals/golden.json (validate + diff, hermetic)
• Tests: pytest with mock LLM (no API keys required)

Quick start:

cd pantrybound
python3 -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'
cp .env.example .env
PANTRYBOUND_LLM_PROVIDER=mock pantrybound cook --pantry "eggs,rice,lemon" --skill beginner
pantrybound eval

Documentation: pantrybound/README.md

---

stillnote

Stillnote — private journal reflection with empathetic LLM prompts and deterministic safety guardrails (not mental health care). You write a journal entry; an LLM returns structured JSON (patterns, reflection, 1–2 questions, one optional small step); a validator blocks clinical/diagnostic language; crisis phrases short-circuit to fixed support resources without calling the LLM.

• Stack: Python 3.11+, FastAPI, Typer, Rich, optional Anthropic or Ollama (mock for offline/tests)
• Pipeline: reflect → crisis check → LLM (JSON) → validate → reflection + disclaimer
• CLI: stillnote reflect, validate, eval, serve, config show
• Web UI: React 19 + Vite + Tailwind 4 (stillnote/web/, port 5175); entries in localStorage only
• Evals: 15 golden cases in evals/golden.json (reflect, crisis, validate, safety)
• Tests: pytest with mock LLM (no API keys required)

Quick start:

cd stillnote
python3 -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'
cp .env.example .env
STILLNOTE_LLM_PROVIDER=mock stillnote reflect --text "bad day" --mood sad
stillnote eval

Documentation: stillnote/README.md

---

heartbot

HeartBot — a 24/7 WhatsApp caring-messages bot that runs on a Linux VPS and messages your partner on a schedule with warm, AI-generated text. Sends morning (with OpenWeatherMap), afternoon check-in (rotating caring questions — no repeat within 7 days), good night, and random mid-day thoughts; when she replies, the bot answers with context from the last 10 messages and facts stored in SQLite.

• Stack: Node.js 20+ (ESM), Twilio WhatsApp API, OpenAI or Anthropic (AI_PROVIDER env switch), sql.js (SQLite), node-cron, Express (inbound webhooks), Winston file logging, PM2 for production
• Scheduler: cron jobs in TIMEZONE (default Asia/Beirut) for MORNING_TIME / AFTERNOON_TIME / NIGHT_TIME plus configurable RANDOM_THOUGHT_CRON
• Personality: boyfriend-voice system prompt with her name, your name, and recalled facts; tone-matched replies; fallback lines if the AI API fails
• Memory: messages, facts, question_log, and settings tables; post-reply fact extraction; pause/resume flag
• Safety / ops: PAPER_MODE logs instead of sending; Twilio webhook signature validation in production; owner-only WhatsApp commands (status, pause, resume); /health endpoint
• Tests: npm run test:memory (pause toggle + caring-question rotation); npm run test:send -- <slot> for manual scheduled-message smoke tests

Quick start:

cd heartbot
npm install
cp .env.example .env
# Fill in: Twilio SID/token, HER_/OWNER_ WhatsApp numbers, AI key, HER_NAME, YOUR_NAME
# Start with PAPER_MODE=true and SKIP_WEBHOOK_SIGNATURE=true for local testing.

npm run test:memory
npm run test:send -- morning
npm start                                        # dev server on :3000
# Production VPS: Nginx + SSL → PUBLIC_WEBHOOK_URL, then:
pm2 start ecosystem.config.cjs && pm2 save && pm2 startup

Documentation: heartbot/README.md — Twilio sandbox, VPS/Nginx/Certbot, env reference, paper mode, PM2 commands, and transparency note.

---

footballfilter

FootballFilter — a 24/7 WhatsApp auto-decline bot that politely turns down football invitations and “want to play?” messages on your behalf. Uses a two-layer detector (keyword filter, then optional Claude confirmation) and only replies in group chats when you are @mentioned.

• Stack: Node.js 20+ (ESM), whatsapp-web.js (QR login, no Twilio/API key for WhatsApp), Anthropic Claude (intent detection), sql.js (SQLite logging), Winston, PM2 on Ubuntu VPS
• Detection: English + Arabic keywords (football, كرة, مباراة, تعال تلعب, …) → Claude YES/NO prompt; ENABLE_AI_DETECTION=false skips the API and replies on keyword match only
• Safety: per-contact cooldown (default 1h), number whitelist, 20 replies/day cap, dry-run mode, manual-override when you reply yourself (pauses that chat for 24h)
• Ops: /status in WhatsApp Message yourself; full message/reply audit trail in SQLite
• Tests: npm test (keyword matcher; no API key or WhatsApp session required)

Quick start:

cd footballfilter
npm install
cp .env.example .env
# Add ANTHROPIC_API_KEY (or set ENABLE_AI_DETECTION=false)
# Start with DRY_RUN=true to log without sending.

npm test
npm start                                        # scan QR in terminal (Linked devices)
# Production VPS:
pm2 start ecosystem.config.cjs && pm2 save && pm2 startup

Documentation: footballfilter/README.md — detection layers, env reference, Ubuntu 22.04 + Chromium deps, PM2, and troubleshooting.

---

phantom

Phantom — an AI-augmented crypto trading bot that stitches together a classical seven-layer trading stack behind a single async loop: data feed → technical indicators + LLM sentiment → signal aggregator → risk guards → broker → portfolio → monitoring. Paper trading on a live Binance public price feed is the default; Binance testnet and real-money live trading are wired but gated behind explicit env flags and a runtime confirmation prompt.

• Stack: Python 3.10+, CCXT (Binance spot, REST OHLCV), LangChain (Claude sentiment with optional Gemini cross-check), FastAPI + WebSocket dashboard, Typer CLI, Rich terminal UI, Pydantic v2 / pydantic-settings, stdlib sqlite3 for trade history.
• Layers (src/phantom/): data/ (CCXT wrapper, OHLCV feed, CryptoPanic news, CoinGecko market context), brain/ (pandas-native RSI/MACD/EMA/Bollinger + Claude sentiment + regime classifier), decision/ (signal aggregator + position sizing + RiskGuard), execution/ (broker interface + PaperBroker + LiveBroker + Portfolio), monitoring/ (Console + Telegram alerts + PnL/Sharpe/drawdown analytics), backtest/ (OHLCV replay engine), web/ (FastAPI + WS dashboard with Chart.js equity curve, dark UI).
• Three trading modes: paper (in-memory broker, no keys needed), testnet (CCXT against testnet.binance.vision, fake money), live (CCXT against Binance mainnet, real money). Settings.validate_for_mode() refuses to start testnet/live without BINANCE_API_KEY + BINANCE_API_SECRET; the CLI prints a red rich.Panel + confirmation before the first live tick.
• Risk guards run BEFORE every order: per-trade cap (PHANTOM_MAX_TRADE_PCT=5), stop-loss (PHANTOM_STOP_LOSS_PCT=3), take-profit (PHANTOM_TAKE_PROFIT_PCT=6), confidence floor (PHANTOM_MIN_CONFIDENCE=70), and a daily-loss kill-switch (PHANTOM_DAILY_LOSS_LIMIT_PCT=10) that halts the bot for the rest of the UTC day if breached.
• Graceful degradation: sentiment falls back to neutral without ANTHROPIC_API_KEY, Telegram alerts no-op without TELEGRAM_BOT_TOKEN, news fetcher returns empty on network failure. Paper-trading requires zero credentials.
• CLI: phantom run [--mode paper|testnet|live] [--cycles N], phantom backtest --symbol BTC/USDT --days 14 [--min-confidence 30] [--max-trade-pct 1] (per-run overrides without editing .env), phantom dashboard (FastAPI on :8765 with live equity chart, recent signals, and trade log), phantom keys check, phantom config show (secrets redacted).
• Tests: 30 passing in ~2s, fully hermetic — config parsing + mode validation, indicators on trending/flat fixtures, paper-broker cash + PnL invariants, all four risk guards (HOLD-block, confidence floor, stop-loss/take-profit force-exit, daily kill-switch), decision aggregator across BUY/SELL/HOLD + volatile-regime damping, position sizing, backtest end-to-end with synthetic OHLCV.

Quick start:

cd phantom
python3 -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'
cp .env.example .env
# Optional: add ANTHROPIC_API_KEY for sentiment. Nothing else is required to paper-trade.

phantom run                                                   # paper mode on live Binance prices
phantom backtest --symbol BTC/USDT --days 14 --min-confidence 30   # see the engine actually trade
phantom dashboard                                             # http://127.0.0.1:8765

Safety notes: Most trading bots lose money — this is a learning scaffold, not financial advice. Always start paper, then testnet, then a tiny live allocation you can afford to lose entirely. When you eventually generate Binance keys, enable spot trading only, never withdrawals, and IP-restrict them. The risk guards are guardrails, not guarantees — slippage and gaps can blow past a daily-loss limit.

Documentation: phantom/README.md — architecture diagram, mode table, backtest tuning, and critical warnings.

---

orion

Orion — Desktop AI chat app that talks only to your machine: inference runs through Ollama locally. No cloud APIs, no keys.

• Stack: Python 3.11+, Tkinter (default UI on macOS), optional CustomTkinter on Linux/Windows or with ORION_UI=ctk
• Features: Streaming replies, multiple chats, model picker, system prompt + temperature, persistent history under ~/.orion/, delete chats, settings JSON
• macOS note: Use Python from python.org (not only Xcode Command Line Tools Python) for a reliable Tcl/Tk GUI; the Orion README explains PATH, venv, and troubleshooting white/blank windows

Quick start:

cd orion
python3 -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
python -m pip install -r requirements.txt
python main.py

Documentation: orion/README.md

---

lyra

Lyra — Desktop AI chat app for local Ollama, same on-disk format as Orion (~/.orion by default), with a PySide6 / Qt 6 interface instead of Tkinter.

• Stack: Python 3.11+, PySide6, ollama Python client, requests
• Features: Live token streaming, markdown/code styling in the transcript after each reply, sidebar history (grouped by date), model combo, system prompt, temperature, settings (fonts, Ollama host / OLLAMA_HOST, pull/delete models, clear history), optional LYRA_DATA_DIR, optional assets/icon.png, PyInstaller notes in the project README

Quick start:

cd lyra
python3 -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python main.py

Documentation: lyra/README.md

---

chess3d_llm

Chess3D Commentator — browser 3D chess with Stockfish analysis in a Web Worker and an LLM coach that explains the last move in plain English, grounded in engine eval and principal variation (not invented lines). Related vanilla 2D chess: chess/.

• Stack: React 19, Vite 8, TypeScript, Tailwind 4, React Three Fiber, chess.js, vendored Stockfish WASM, optional FastAPI explain proxy, Ollama or Anthropic for commentary
• Engine: Stockfish runs in-browser (public/stockfish.wasm.js); eval bar, PV, move classification (Best → Blunder)
• Commentary: buildPrompt sends FEN, eval before/after, centipawn loss, classification, and PV; providers — mock (offline), ollama (direct to local Ollama, no Python server), auto (API with Ollama fallback), Anthropic via server
• UI: 3D board with click-to-move, promotion dialog, flip/undo, keyboard navigation, optional auto-comment after each move
• Tests: 12 Vitest tests (prompt builder, analysis thresholds, chess.js integration)

Quick start:

cd chess3d_llm
npm install
cp .env.example .env
# Default .env.example uses direct Ollama — ensure: ollama pull llama3.2
npm run dev
# → http://127.0.0.1:5173

Optional API server (Anthropic keys stay server-side; Vite proxies /api → :8780):

cd chess3d_llm/server
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
cp .env.example .env
uvicorn chess3d_server.main:app --host 127.0.0.1 --port 8780

Documentation: chess3d_llm/README.md

---

brushwork

Brushwork — lightweight Paint-style bitmap editor: pencil, brush, airbrush, eraser, lines/shapes (incl. rounded rect, polygon, quadratic curve), flood fill with tolerance, eyedropper, text, rectangular selection (move/delete/crop), clipboard image paste, resize/rotate/flip/invert/clear, wheel zoom + middle pan + fit-to-window, recent files, JPEG save quality, print, shortcuts/about. PySide6 / Qt 6.

• Stack: Python 3.11+, PySide6
• Features: Raster canvas, QSettings recent files, QPrintDialog, dirty-document prompts, toolbar zoom %

Quick start:

cd brushwork
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python main.py

Documentation: brushwork/README.md

---

pitch

Pitch — AI-powered desktop football (soccer) video analysis: deep-learning YOLOv8 detects players and the ball on match video or webcam; overlays include boxes, trails, heatmap, rough team colors (ML clustering), a simplified offside hint, possession + stats, and JSON export. Inference runs locally via PyTorch (MPS on Apple Silicon when available).

• AI / ML: Convolutional object detection (YOLOv8) + unsupervised jersey grouping (K-means); all on-device, no cloud APIs.
• Stack: Python 3.11+ (3.14 OK), CustomTkinter + Tk root (macOS-friendly), OpenCV, Ultralytics YOLOv8, PyTorch, NumPy, Pillow, scikit-learn
• UX: The UI opens right away; weights load on first “Open Video” / Webcam (first run may download yolov8*.pt — terminal shows progress).
• CLI: python main.py --model yolov8n.pt · python main.py --source /path/to/match.mp4
• macOS: Prefer Python from python.org for a solid Tcl/Tk + GUI stack (same idea as Orion).

Quick start:

cd pitch
python3 -m venv venv && source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt
python main.py

Documentation: pitch/README.md

---

hollow

Hollow — first-person psychological horror prototype in Unity 6 (URP): you’re hunted in a stylized night asylum while an AI creature patrols, reacts to footsteps and microphone noise (with HollowSettings mic sensitivity + pause slider), investigates sound with PatternTracker bias, chases on sight, searches when it loses you, and remembers hiding spots where it has caught you. Optional stack: FMOD adaptive audio, ML-Agents (validated BehaviorParameters only; biases brain weights, not raw NavMesh), Whisper Python sidecar for voice transcription.

• Engine: Unity 6000.x, C#, NavMesh (AI Navigation package), Input System
• Presentation: HollowRuntimeVisuals — procedural night skybox, moon + trilight-style readability, shared URP Lit environment materials, monster silhouette mesh; main menu is a spooky Halloween-themed runtime UI with developer credit.
• Feel: Procedural ambience + footsteps out of the box; fog tuned for visibility; runtime HollowLevelBootstrap builds a new procedural asylum layout on Level_Asylum each run (seed from HollowLevelSession); HUD shows adaptation stats from PatternTracker.
• Flow: MainMenu → Enter the asylum / Grimoire (controls) → Level_Asylum (do not stay on empty SampleScene)

Quick start: Install Unity 6000.x → Unity Hub Add the project folder hollow/My project → open it → Play (or open Assets/Scenes/MainMenu.unity first).

Documentation: hollow/README.md (folder index) · hollow/My project/README.md (full game + systems + controls)

---

vscode_copilot_app_job_recruiter

A job recruiter web application built with GitHub Copilot assistance.

• client/ — React + Vite frontend with Tailwind CSS
• server/ — Node.js backend with REST API routes (auth, chat, LinkedIn, profiles)
• job_recruiter/ — Project documentation, setup guides, and reference material

Stack: React, Vite, Tailwind CSS, Node.js, Express

---

flappy_cat

A browser-based Flappy Bird–style game built with Phaser 3 and Vite. Guide a cat through scrolling obstacles (laundry lines, furniture, dogs, yarn, lasers), collect fish and power-ups, and chase a high score—with Normal, Zen, and Daily modes, local persistence, and procedural audio.

Stack: Phaser 3, Vite, JavaScript (ES modules)

Quick start:

cd flappy_cat
npm install
npm run dev

---

shadow_runner

Shadow Runner — a browser-playable 2D neon platformer portfolio demo built with Phaser 3, Vite, and TypeScript. Escape a city security system, collect memory shards, unlock movement abilities, build custom challenge rooms, and defeat the final Sentinel boss.

• Gameplay: polished platformer movement with acceleration, friction, coyote time, jump buffering, variable jump height, dash, double jump, phase, checkpoints, hazards, enemies, moving platforms, and collectibles.
• Campaign: three handmade levels — Rooftop Wake, Glass Factory, Signal Tower — plus The Sentinel boss encounter.
• Editor: grid-based level editor with tile, hazard, shard, enemy, checkpoint, spawn, exit, erase, drag-painting, right-click erase, playtest, save, export, and import.
• Persistence: browser localStorage under shadow_runner_save_v1 for completed levels, best times, collected shards, unlocked abilities, sound setting, and custom levels.
• Presentation: procedural neon visuals, procedural Web Audio SFX, HUD, camera shake, particles, floating feedback, level select, about screen, and shareable game-over result.

Stack: Phaser 3, Vite, TypeScript, Arcade Physics, Web Audio, localStorage, Vitest, ESLint

Quick start:

cd shadow_runner
npm install
npm run dev

Quality commands:

npm run build
npm run lint
npm run test

Documentation: shadow_runner/README.md

---

wavechat

Wavechat — a full-stack real-time chat learning project with a Discord-lite dark UI. It demonstrates Socket.io rooms, live messaging, online presence, room-scoped typing indicators, sign out, system join/leave messages, and last-50 in-memory chat history per room.

• Frontend: React 19, Vite 8, Tailwind CSS 4, Socket.io Client
• Backend: Node.js ES modules, Express, Socket.io
• Realtime concepts: join_room, leave_room, send_message, typing, stop_typing, room_users, room_typing
• State model: no database; usernames, rooms, presence, typing users, and recent messages are held in server memory

Quick start:

cd wavechat/server
npm install
node server.js

cd wavechat/client
npm install
npm run dev

Open http://localhost:5173 in two browser tabs with different usernames to test messaging, presence, and the user is typing... indicator.

Documentation: wavechat/README.md

---

portfolio

Omar Brome Portfolio — a modern single-page portfolio and CV website with a dark Linear/Vercel-inspired aesthetic, animated hero, typewriter roles, active smooth-scroll navigation, skills cards, experience timeline, project grid, competitive programming links, contact cards, downloadable CV, and custom OB favicon.

• Stack: React 19, Vite 8, Tailwind CSS 4, Framer Motion, React Icons
• Content: C++/Qt desktop experience, Linux tooling, full-stack web background, AI-assisted development, selected ai-playground projects, LCPC/ACPC achievements
• Assets: bundled CV PDF at public/Omar_Brome_CV.pdf and custom SVG favicon

Quick start:

cd portfolio
npm install
npm run dev

Documentation: portfolio/README.md

---

swiftkeys

Swiftkeys — a Monkeytype-inspired typing speed test app with live raw/net WPM, accuracy tracking, difficulty modes, punctuation/number toggles, animated results, WPM charting, username-only auth, and a leaderboard that works in local demo mode or with PostgreSQL persistence.

• Frontend: React, Vite, Tailwind CSS, Framer Motion, Recharts
• Backend: Node.js, Express, PostgreSQL via pg
• Typing engine: first-keystroke timer start, Escape reset, per-character correctness, WPM history, timed and word-count modes
• Leaderboard: local fallback by default; global PostgreSQL leaderboard when DATABASE_URL is configured

Quick start:

cd swiftkeys/client
npm install
npm run dev

Documentation: swiftkeys/README.md

---

snack_nasab

Snack Nasab — a mobile-first, bilingual (Arabic / English) fast-food menu web app with public browsing (/ar, /en), RTL/LTR switching, and an admin dashboard for categories and items (CRUD). Uses NextAuth for admin login and Prisma + PostgreSQL for data.

Stack: Next.js (App Router), TypeScript, Tailwind CSS, Framer Motion, Prisma, PostgreSQL, next-intl, NextAuth

Quick start: See snack_nasab/README.md for .env, migrations, seed, and default admin credentials.

---

paypal_dhl

Lumière — a luxury-themed React + Vite + TypeScript candle-shop demo with PayPal Sandbox checkout and DHL Tracking API (EU) behind a Vite dev proxy for CORS. Includes demo-mode payment simulation when the SDK is unavailable or misconfigured.

Stack: React, Vite, TypeScript, Tailwind CSS, React Router, Axios

Quick start:

cd paypal_dhl
cp .env.example .env
# Set VITE_PAYPAL_CLIENT_ID and VITE_DHL_API_KEY for sandbox.
npm install
npm run dev

---

football_hajez_app

Malaab (ملاعب) — mobile-first 5v5 mini-football booking app for Lebanon.

• Player: pick team + role, deep-link invites (/match/:id?team=&role=), role waitlist when full, Whish payment proof flow, host approval lifecycle.
• Pitch Host: schedule 90-minute sessions (:00 / :30), manage hosted matches, verify/reject payment proofs.
• Preview sharing: OG/Twitter tags in-app, optional Supabase Edge function for bot unfurls.
• Ops: unit tests (Vitest), E2E smoke (Playwright), optional analytics events, optional Sentry monitoring.

Supports dual persistence:

• local demo mode (localStorage)
• Supabase backend mode (Postgres + Auth + RLS + RPC + Storage)

Stack: React, Vite, TypeScript, Tailwind CSS v4, React Router v6, Supabase

Quick start:

cd football_hajez_app
npm install
npm run dev

Quality commands:

npm run test
npm run test:e2e:install
npm run test:e2e
npm run lint
npm run build

Full setup and architecture docs:

• football_hajez_app/README.md
• football_hajez_app/docs/ops-env.md

---

prayer_ios_app

أوقات الصلاة (Awqat Al-Salah) — native SwiftUI iOS app for Lebanese prayer times: AlAdhan (no API key), Qibla, monthly calendar, local notifications, adhan assets, offline cache. Open PrayerTimesApp.xcodeproj and run on iOS 17+.

Stack: Swift 5.9+, SwiftUI, URLSession, UserNotifications, CoreLocation, AVFoundation

Docs: prayer_ios_app/README.md · prayer_ios_app/XCODEPROJ_SETUP.md

---

cursor_work Projects

A collection of various apps and games built with Cursor AI assistance. These live at the repository root in separate folders, including:

• 🛰️ Meridian (./meridian) — LangGraph-driven agentic build pipeline (Brainstorm → Plan → Test → Implement → Review loop) with pluggable Claude/Gemini/OpenAI providers, sandboxed workspaces, Typer CLI, and FastAPI + WebSocket dashboard
• qmigrate (./qt_migration_agent) — Qt 5 -> Qt 6 migration agent (52 rules: C++/QML/PySide2/CMake/qmake), unified-diff patches, optional Claude reviewer, MIGRATION.md report
• 💌 HeartBot (./heartbot) — WhatsApp caring-messages bot (Twilio + OpenAI/Anthropic, cron scheduler, SQLite memory, PM2 on VPS)
• ⚽ FootballFilter (./footballfilter) — WhatsApp auto-decline bot for football invites (whatsapp-web.js + Claude, keyword + AI detection, PM2 on VPS)
• 🪙 Phantom (./phantom) — AI-augmented crypto trading bot (CCXT Binance + Claude sentiment + risk guards), paper-trading by default with testnet + live modes gated behind flags, FastAPI dashboard with live equity curve, backtest engine
• 💬 Orion (./orion) — Local Ollama desktop chat (Python, Tkinter / CustomTkinter)
• ♟️ Chess3D Commentator (./chess3d_llm) — 3D web chess + Stockfish WASM + Ollama move commentary
• 🐱 Flappy Cat (./flappy_cat) — Phaser 3 arcade game
• 🏃 Shadow Runner (./shadow_runner) — Phaser 3 neon platformer with campaign levels, boss fight, progression, and level editor
• 💬 Wavechat (./wavechat) — real-time Socket.io chat with rooms, presence, typing indicators, and in-memory history
• 🧑‍💻 Omar Brome Portfolio (./portfolio) — animated React/Vite portfolio and CV site
• ⌨️ Swiftkeys (./swiftkeys) — Monkeytype-style typing speed test with WPM, charts, and leaderboard
• 🍔 Snack Nasab (./snack_nasab) — bilingual fast-food menu + admin
• 💳 Lumière / PayPal + DHL (./paypal_dhl) — storefront + sandbox checkout + tracking
• ⚽ Malaab / football_hajez_app (./football_hajez_app) — 5v5 match booking + pitch host scheduler (localStorage)
• 🕌 Awqat Al-Salah / prayer_ios_app (./prayer_ios_app) — Lebanese prayer times (SwiftUI, AlAdhan API)
• 👁️ Hollow (./hollow) — Unity 6 horror prototype (night visuals, pattern adaptation, ML-Agents bias, mic settings, spooky main menu); project in hollow/My project
• 📘 Facebook-style social media app (./facebook)
• ♟️ Chess game (./chess) — vanilla 2D browser chess (no engine/LLM)
• ❌ Tic Tac Toe game (./games)
• 🎱 Pool game (./pool)
• ...and more (./calculator, ./web_app1, etc.)

---

🚀 Getting Started

Job Recruiter App

Frontend:

cd vscode_copilot_app_job_recruiter/client
npm install
cp .env.example .env
npm run dev

Backend:

cd vscode_copilot_app_job_recruiter/server
npm install
cp .env.example .env
node index.js

Orion (local Ollama desktop chat)

See orion/README.md — includes prerequisites (Ollama + models), venv setup, ORION_UI, and macOS Tk notes.

Chess3D Commentator (3D chess + Stockfish + Ollama)

See chess3d_llm/README.md — npm run dev with VITE_LLM_PROVIDER=ollama for direct local commentary (no Python server). Optional FastAPI on port 8780 for Anthropic.

Hollow (Unity 6 horror prototype)

Use Unity Hub to add hollow/My project, open with Unity 6000.x, then see hollow/My project/README.md for controls, scenes, FMOD / ML-Agents / Whisper, and design notes.

HeartBot (WhatsApp VPS bot)

See heartbot/README.md — Twilio WhatsApp sandbox, .env setup, paper mode, Nginx/SSL webhook URL, and PM2 deployment on Ubuntu 22.04.

FootballFilter (WhatsApp auto-decline bot)

See footballfilter/README.md — whatsapp-web.js QR login, .env setup, dry-run mode, detection layers, and PM2 deployment on Ubuntu 22.04.

Flappy Cat, Shadow Runner, Wavechat, Portfolio, Swiftkeys, Snack Nasab, PayPal + DHL, Malaab, Prayer iOS

Use the Quick start blocks under each project above, or open that folder’s README.md for full setup (especially Snack Nasab’s database and auth, Wavechat’s two-terminal client/server setup, Portfolio’s static CV assets, and Swiftkeys’ optional PostgreSQL leaderboard). For the iOS prayer app, use Xcode with prayer_ios_app/PrayerTimesApp.xcodeproj — see prayer_ios_app/README.md.

---

🛠️ Built With

• Unity / C# (Hollow)
• React
• Next.js
• Vite
• Tailwind CSS
• Framer Motion
• Phaser
• Node.js
• Express
• Socket.io
• PostgreSQL
• Prisma
• LangGraph & LangChain (Meridian agent orchestration; Phantom sentiment layer)
• FastAPI (Meridian, Phantom, Chess3D Commentator explain API)
• Three.js & React Three Fiber (Chess3D Commentator)
• chess.js (Chess3D Commentator rules)
• Stockfish (Chess3D Commentator, in-browser WASM)
• Typer & Rich (Meridian + Phantom CLIs)
• CCXT (Phantom exchange integration — Binance spot, REST OHLCV)
• pandas (Phantom indicators + backtest engine)
• Anthropic Claude · Google Gemini · OpenAI (Meridian pluggable LLM providers; Phantom news sentiment; HeartBot + FootballFilter; Chess3D optional via server)
• Ollama (Orion, Lyra, Recall, Chess3D Commentator local commentary)
• whatsapp-web.js (FootballFilter WhatsApp session via QR login)
• Twilio (HeartBot WhatsApp messaging)
• PM2 (HeartBot + FootballFilter 24/7 process management on VPS)
• GitHub Copilot & Cursor AI
• Swift / SwiftUI (iOS)