The cognitive twin turns ten open tabs into one calm surface — your music, your code, your tasks, your projects, on a single page. It runs locally, learns your patterns, and stops asking you to remember anything.
Every other assistant either remembers nothing, or remembers everything but can't act. digital_twin is the third option — a persistent model of how you work, that does the work too.
How it looks · 03
One screen. Everything that matters.
The twin runs as a small local daemon. It watches your music library, your code, your calendar, your tasks — and surfaces the things that actually need you. Everything else, it handles quietly in the background.
Event-driven, not always-on. The twin wakes up when something matters — a song finishes, a CI run fails, a calendar block starts — and goes silent otherwise.
Pattern memory. It notices that you always warm up with a Coltrane track at 9am. After the third time, it just queues it.
You stay in control. Every action is proposed before it runs. Every change is auditable. The twin suggests — you decide.
Quickstart · 04
Three commands. Then it's running.
Clone the repo, index the music, open the twin. Every command is copyable. Sprint 1 ships the indexer and the shell; the landing + e2e + design system are sprint 0 and already on disk.
# clone the repogit clone https://github.com/kajica2/digital-twin.git &&cd digital-twin
# install dependenciesnpm install
# index your music library (sprint 1)npm run index-songs
# open the twin shellopen pages/twin-os/index.html
MIT-licensed
runs on your machine
your data never leaves the disk
Architecture · 05
Four layers. One system.
The twin is not a single agent. It's a layered system — scan, model, reason, orchestrate — where each layer feeds the next and none of them require a human in the loop once the work is defined.
1
Scanner
Index the environment
Runs on demand or on a cron. Traverses the filesystem at startup — reads package.json, requirements.txt, agent skills, installed tools (brew, pip, npm), GitHub repos, Obsidian vault index. Outputs a structured snapshot of every tool, project, and capability available right now. If a new package appears, the scanner finds it on the next run.
The scan output writes to a durable layer — memory/user.md for cross-project preferences, memory/agent.md for agent behavior, and a project-level twin index for domain-specific context. This is what allows the twin to know "I already have a transcription pipeline" without re-running discovery. The model is the memory of the environment.
Given a job — "transcribe this recording", "build a landing page for X", "run the weekly report" — the reasoner reads the model and selects the right tools in the right order. It's not an LLM doing freeform reasoning from scratch; it's a routing decision constrained by the actual inventory. If Whisper and pYIN are installed, route audio transcription there. If not, route to the API. The reasoner picks from what's actually available.
Mavis orchestratortools.json inventory
4
Orchestrator
Set up and run the work process
Once the reasoner picks the path, the orchestrator sets up the process — writes a subagent prompt, schedules a cron, triggers a webhook, or hands off to the next agent in the chain. The orchestrator also handles failure modes: if a step fails, it retries, rolls back, or escalates to the human digest with a diff. The orchestrator is the part that does the work. The other three layers exist so it always knows what it's working with.
The twin doesn't just describe the environment — it acts on it. These are the processes it has already built or maintains.
arXiv + GitHub research swarm — cron-triggered subagent that runs every 48 hours. Polls arXiv for new AMT (automatic music transcription) papers, checks GitHub for tool updates, writes a summary. Result lands in music-transcription-monitor/docs/ and triggers a GitHub Pages rebuild.
↓
Puppeteer deploy-test loop — fires on every web deploy. Visits the live URL, asserts HTTP 200, checks DOM for expected strings, fails on console errors, re-deploys and retries if the check fails. This is the twin verifying its own output.
↓
Memory maintenance — after each session, the twin appends durable learnings to memory/user.md (cross-project rules), memory/agent.md (agent behavior), or project-level AGENTS.md (repo-specific context). The next agent that spins up reads the model and starts with working context.
↓
E2E regression gate — after any sprint (multi-step code change), the twin runs the project's end-to-end test before reporting done. Typecheck + build pass don't count. The test must pass. If it fails, the sprint isn't done.
Domain twins · 07
Domain-specific twins. Built from the scan.
The general scanner produces domain-specific instantiations. Each twin knows its domain cold and runs the process without asking.
01
Music Twin
The whole studio, indexed
Ableton projects, Pro Tools sessions, MuseScore scores, sample libraries, Max for Live patches, Vital presets. Routes to Suno for demos, DAW for production, Solokit for analysis.
02
Trumpet Twin
Live recordings → chart, automatically
Live recordings, transcription output, charts, practice logs. Keeps the pYIN + VexFlow pipeline warm. Routes new recordings to ingest → transcribe → chart, end to end.
03
Web Twin
Every spoke, watched
Every kajica2.github.io page, every Vercel deploy, every GitHub Pages repo. Monitors every deploy with the Puppeteer gate. Notifies — or auto-reverts — on failure.
04
Research Twin
The literature, in your inbox
arXiv, GitHub trending, bob_mover_jazz_lexicon, Solokit corpus, Obsidian vault. Runs the AMT research swarm. Keeps the music-transcription-monitor dashboard current.
The twin is MIT-licensed. Run it locally. Extend it when you want. The architecture is the system; the tools are the binding. Both can change without the other breaking.