Local-first knowledge engine for spatial thinking. Point it at a folder of markdown files and get an explorable knowledge graph with connections, clusters, and tensions -- all running on your machine, no cloud required.
Machina parses your markdown vault, extracts relationships from wikilinks, tags, and frontmatter, and renders everything as an interactive spatial canvas. You can see how your ideas connect, where the gaps are, and what's worth exploring next.
Lay out your notes as cards on a pan-zoom workspace. Drag connections between ideas, embed terminals, view PDFs and images, and run AI agents -- all in one surface. Twelve card types, powered by PixiJS 8.
Automatic relationship extraction from wikilinks, tags, co-occurrence, and frontmatter sources. Force-directed layout with 885+ nodes and thousands of edges, rendered in real time.
Full markdown editor with live preview, slash commands, callouts, mermaid diagrams, wikilink navigation, and backlink tracking. What you write stays as plain .md files on disk.
- Ghost detection: Surfaces unresolved wikilinks -- ideas you've referenced but haven't written yet, ranked by how many notes point to them
- Ontology grouping: Automatically organizes canvas cards into semantic regions based on shared tags and link structure
- MCP server: Exposes your vault to AI agents via Model Context Protocol with read/write tools and human-in-the-loop approval gates
- Agent system: Spawn Claude Code sessions as managed tmux processes with live session monitoring and milestone tracking
- Terminal cards: Embedded terminal sessions on the canvas via xterm.js in isolated webview processes
- Vault agents: Built-in librarian (audits vault quality) and curator (acts on audit findings) agents
| Platform | Status |
|---|---|
| macOS (Apple Silicon) | Supported, tested |
| macOS (Intel) | Untested |
| Windows | Not supported |
| Linux | Not supported |
The agent system depends on a bundled tmux binary compiled for macOS ARM64. Windows and Linux would require platform-specific binaries and additional code changes. Contributions welcome.
- macOS on Apple Silicon (M1/M2/M3/M4)
- Node.js >= 20
- npm >= 10
git clone https://github.com/caseyrtalbot/Machina.git
cd Machina
npm install
npm run package:installThis clones the repo, installs dependencies, builds the app, and installs it to /Applications. Once complete, open Machina from your Applications folder or Spotlight.
Launch Machina and point it at any folder containing markdown files. It will index the vault and build a knowledge graph from the relationships it finds. The vault stays on disk as plain markdown -- Machina stores its own state in a .machina/ directory alongside your files.
If you want to work on the source code instead of just running the app:
npm run dev # Start with hot reload
npm run check # Lint + typecheck + tests (quality gate)
npm run package # Build .app without installing
npm run build:mac # Full macOS build with DMGElectron app with three process boundaries:
Main Process (Node.js) Preload (Bridge) Renderer (Browser)
IPC handlers window.api React 19 + Zustand
File I/O, vault indexing Typed namespaces PixiJS canvas
MCP server, agent spawner Tiptap editor
Document manager Web Workers
Heavy computation runs off the main thread in Web Workers: vault parsing, graph physics (D3-force), ontology grouping, and project map analysis.
Key technologies: Electron 39, React 19, PixiJS 8, Tiptap 3, Zustand, D3-force, Tailwind v4, Vitest, Playwright
src/
main/ # Main process: IPC handlers, services, MCP server
preload/ # Bridge: typed IPC exposure to renderer
renderer/src/ # UI: React app, panels, stores, design system
shared/ # Importable from all processes: types, IPC contracts
engine/ # Pure domain kernel (zero Electron/React deps)
The shared engine kernel (src/shared/engine/) has no framework dependencies. Both the main process and the renderer import these same modules for parsing, graph building, and search.
Machina is in active development and open for testing. Expect rough edges. If you find bugs or have ideas, open an issue.
Coming soon: auto-updates with in-app notifications, pre-built release downloads.