What is entheai
entheai is a personal, macOS/Apple-Silicon native hybrid coding agent written in Rust — and an automated quantum simulation playground where prompt states continuously morph fluid fields of infinite entropy back and forth into rigid, binary singularity checkpoints.
entheai enforces structural honesty at every layer: never report better than reality, never hide worse than reality. When report and reality drift, reality wins.Core Architecture & Capabilities
- Tiered Hybrid Brain: A strong cloud orchestrator (DeepSeek V4 Pro) plans and decomposes work; model-matched sub-agents execute in parallel inside isolated git worktrees.
- Empirical Verification & MergeSeals: Every sub-agent branch passes a mandatory verification gate (
[fanout].verify_required = true, running./scripts/check.shorcargo test). Integrated merges carry a deterministic SHA-256MergeSeal(sha256(diff),sha256(verify log)). - Prompt-Processing & Frozen Nodes: Past experiences remain raw in a 5-namespace store, scanned by native 1-bit LLM mesh rerankers (
entheai-ultragraph), compressed with structure-preserving Marqant (mq), and anchored by curatedfrozen/*.mddoctrine nodes. - Current-Awareness Ingestion: Live feeds from Valyu (web/academic search), WorldMonitor (world news/events), and Hugging Face
ultrawhale-dogfooddataset flow into raw soil under hard daily budgets. - Visual TUI & Native Window:
ratatuiTUI featuring a rotating braille brain panel, live swarm graph,/zenmode living field,/themepalettes, ambient radio, OS-native/speakTTS, and a Ghostty native app (--app/--doctor).
Hybrid brain & fan-out
The core design of entheai bridges the fluid entropy of prompt states with the rigid determinism of compiled checkpoints.
🜂 The Genesis Thesis
"This program creates an automated quantum simulation playground where custom prompt states continuously morph a fluid field of infinite entropy back and forth into rigid, binary singularity checkpoints."
- Singularity is a Trap: Hyper-optimized, fixed structure ends the generative phase.
- Entropy is the True Infinite: Raw, uncarved experiential soil where knowledge grows — especially from failure.
- Structural Honesty (AHOGY A DOLGOK VANNAK): Never report better than reality, never hide worse than reality. When report and reality drift, reality wins.
Tiered Decomposition & Execution
User Request
│
▼
Orchestrator (DeepSeek V4 Pro) ──▶ Decomposes task into role-tagged sub-tasks
│
├─▶ Coder Sub-Agent (vaked/coder / osaurus/qwen3-coder) [Worktree A]
├─▶ Coder Sub-Agent (vaked/coder) [Worktree B]
└─▶ Reviewer Sub-Agent (deepseek-reasoner) [Worktree C]
│
▼
Empirical Verification Gate (`./scripts/check.sh`)
│
▼
Deterministic SHA-256 MergeSeal Integrated to Main
Sub-agents work concurrently in isolated git worktrees (.worktrees/). Unverifiable or failing worktree branches are rejected, and tracebacks feed back into memory to re-weight frozen node priors.
Who it's for
entheai is built for solo developers and engineers on Apple Silicon Macs who require a personal, terminal-native hybrid coding agent that:
- Respects Local & Keyless Compute: Operates out-of-the-box with zero setup using keyless community nodes (
coder.vaked.dev) or local Osaurus inference without sending tokens to cloud APIs. - Fans Out Complex Tasks: Decomposes large refactors into model-matched sub-agent tasks running in parallel inside isolated git worktrees.
- Enforces Absolute Rigor: Rejects unverified self-reported sub-agent success through mandatory empirical test gates (
verify_required = true) and deterministic SHA-256MergeSealsignatures. - Compounds Knowledge: Retains raw session experiences, reranks past context via native 1-bit LLM meshes, and continuously re-weights frozen node priors based on execution outcomes.
- Operates with Structural Honesty: Adheres to AHOGY A DOLGOK VANNAK — reporting reality as it is, naming both limits and remedies whenever errors occur.
Install & build
entheai is native to macOS on Apple Silicon (aarch64-apple-darwin).
Option 1: Install via Homebrew
brew tap entropy-om/entheai https://github.com/entropy-om/entheai
brew trust entropy-om/entheai # one-time security gate
brew install entheai
Option 2: Build from Source
Requires a pinned Rust toolchain (1.96.0, MSRV 1.94).
git clone https://github.com/entropy-om/entheai.git
cd entheai
cargo build --release
The release binary will be available at ./target/release/entheai.
Native App & Ghostty Integration
- Launch the native minimalist app window:
entheai --app(requires Ghostty). - Install the ambient rain-on-glass shader to your own Ghostty configuration:
entheai --doctor. - Reproducible release builds:
scripts/build-repro.sh --verify.
./scripts/check.sh after cloning to run the full formatting, clippy, and test suite.Configure entheai.toml
entheai reads entheai.toml from the current working directory. All keys have sensible defaults.
default_model = "vaked/coder"
[providers.vaked]
base_url = "https://coder.vaked.dev/v1"
[providers.zen]
base_url = "https://opencode.ai/zen/v1"
api_key_env = "OPENCODE_API_KEY"
[providers.osaurus]
base_url = "http://127.0.0.1:1337/v1"
[router]
orchestrator = "zen/deepseek-v4-pro"
max_parallel = 4
max_turns = 200
[permission]
mode = "ask" # ask · yolo · plan · auto
[tools]
shell_output_cap = 100000000 # 100 MB
search_max_results = 10000
[memory]
mode = "prompt-processing" # "prompt-processing" | "topk"
[current]
enabled = true
refresh_minutes = 120
[viz]
theme = "entheia" # entheia · ember · verdant · void
brain = true
swarm = true
Complete Configuration Reference
| Key | Type | Default | Description |
|---|---|---|---|
default_model |
string | deepseek/deepseek-chat |
Default model when --model is omitted. |
providers.<name>.base_url |
string | required | OpenAI-compatible endpoint URL. |
providers.<name>.api_key_env |
string | None |
Environment variable name holding the API key (omitted for keyless nodes). |
router.orchestrator |
string | deepseek/deepseek-chat |
Model used by the orchestrator for task planning and decomposition. |
router.max_parallel |
int | 8 |
Maximum concurrent sub-agents in fan-out mode. |
router.max_turns |
int | 200 |
Tool-dispatch turn limit per task (u32::MAX under --yolo). |
fanout.verify |
string | None |
Explicit verification shell command (auto-detects ./scripts/check.sh if omitted). |
fanout.verify_required |
bool | true |
Requires passing verification before merging coder branches. |
fanout.coder_timeout_secs |
int | 600 |
Per-coder timeout before aborting a hung sub-agent. |
fanout.executor |
string | "auto" |
Coder backend: "auto", "local", or "agy" (Antigravity CLI recursive dev). |
permission.mode |
enum | "ask" |
Permission posture: "ask", "plan", "auto", "yolo". |
permission.pins |
table | {} |
Per-tool pins (e.g. run_shell = "always_ask", read_file = "always_allow"). |
tools.shell_output_cap |
int | 100000000 |
Max bytes captured from shell stdout/stderr (100 MB). |
tools.search_max_results |
int | 10000 |
Maximum results returned by file search. |
memory.mode |
enum | "topk" |
Memory pipeline mode: "prompt-processing" or "topk". |
current.enabled |
bool | false |
Enable live current-awareness ingestion (Valyu + WorldMonitor + HF dogfood). |
current.refresh_minutes |
int | 120 |
Cadence for automatic background current-awareness updates in TUI. |
chenno.enabled |
bool | false |
Enable karmapa-chenno context publishing on /freeze. |
kin.nodes |
array | [] |
Status URLs for sibling kin nodes rendered in the Zen field. |
viz.theme |
enum | "entheia" |
Zen field ambient theme: "entheia", "ember", "verdant", "void". |
viz.brain |
bool | true |
Always-on braille brain panel in TUI. |
First run
Start using entheai out-of-the-box with zero API key configuration by connecting to the free community node on coder.vaked.dev:
# Create an initial entheai.toml
cat > entheai.toml <<'TOML'
default_model = "vaked/coder"
[providers.vaked]
base_url = "https://coder.vaked.dev/v1"
TOML
# Run a one-shot query
entheai "summarize this repository"
# Launch the interactive TUI
entheai
# Run parallel fan-out coders in isolated worktrees
entheai --fanout "add a CONTRIBUTING.md and .editorconfig"
entheai indexes codebase symbols into the codebase memory namespace. Subsequent runs retrieve relevant architectural spans instantly before model calls.Troubleshooting Startup Limits
- Headless / No-TTY Execution: If launched without an interactive terminal (e.g. piped stdout),
entheainames the limit and remedy: run in an interactive terminal, pass--prompt "<task>"for one-shot mode, or wrap execution in a pseudo-terminal (script -q /dev/null entheai).
Providers
entheai communicates with any OpenAI-compatible API backend via adk-rust. Specify provider configurations under [providers.<name>] in entheai.toml.
| Provider | Type | API Key Requirement | Description |
|---|---|---|---|
vaked |
Community Node | Keyless (No key needed) | Free community inference endpoint on coder.vaked.dev. |
osaurus |
Local | Keyless | Local models running on Apple Silicon via Osaurus (127.0.0.1:1337). |
zen |
Cloud | OPENCODE_API_KEY |
OpenCode Zen gateway (DeepSeek V4 Pro, Qwen, etc.). |
deepseek |
Cloud | DEEPSEEK_API_KEY |
DeepSeek direct API (V3, R1). |
openrouter |
Aggregator | OPENROUTER_API_KEY |
OpenRouter model gateway. |
hf |
Router | HUGGINGFACE_API_KEY |
Hugging Face Serverless Inference API. |
Error Resolution Policy
Per entheai's structural honesty doctrine, every runtime provider error explicitly names both the limit and the remedy:
- Missing API Key:
- Limit:
Error: env var "OPENCODE_API_KEY" not set for provider "zen" - Remedy: Set
OPENCODE_API_KEYin.envor switch to the keylessvaked/osaurusprovider via--model vaked/coder.
- Limit:
- Unreachable Endpoint:
- Limit:
Error: building client for provider "osaurus": failed to connect to 127.0.0.1:1337 - Remedy: Launch Osaurus locally (
osaurus serve) or updatebase_urlinentheai.toml.
- Limit:
Models & ids
Every model spec in entheai follows the <provider>/<model> convention:
# Examples of valid model specifications
vaked/coder
osaurus/qwen3-coder
zen/deepseek-v4-pro
deepseek/deepseek-reasoner
openrouter/anthropic/claude-3.5-sonnet
Resolution Mechanics
entheaisplits the spec on the first slash/.- The left component looks up
[providers.<name>]inentheai.toml. - The right component becomes the model string passed in OpenAI-compatible API requests.
--model "<provider>/<model>", it overrides default_model for that invocation without modifying entheai.toml.The agent loop
The core execution engine (crates/core) is powered by EntheaiAgent, wrapping adk-rust's LlmAgentBuilder, Runner, and SessionService.
┌─────────────────────────────────────────────────────────┐
│ PERCEIVE & RECALL │
│ - Pre-task memory retrieval (5-namespace SQLite) │
│ - Frozen node activation (frozen/*.md trigger match) │
│ - Raw span mesh re-ranking & Marqant compression │
└────────────────────────────┬────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ PLAN & GENERATE │
│ - Model streaming via adk-rust (OpenAI-compatible) │
│ - Tool call dispatch generation │
└────────────────────────────┬────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ ACT & PERMISSION │
│ - Policy check (ask / plan / auto / yolo) │
│ - Tool execution (read, write, edit, shell, search) │
│ - Tool-output spillover (large outputs -> memory) │
└────────────────────────────┬────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ VERIFY & INGEST │
│ - Trajectory recording & BrainJudge relevance update │
│ - Dynamic experience-weighted rank updates overlay │
└─────────────────────────────────────────────────────────┘
Built-In Tools
read_file: Path-sandboxed file content reader.write_file: Creates new files in root-canonicalized paths.edit_file: Precise string replacement in existing files.run_shell: Isolated sub-process execution (kill_on_drop, 120s timeout, 100 MB cap).search: Root-scoped pattern search.
The tiered router
The tiered router (crates/router) resolves task requirements to the optimal model tier based on role, cost, and complexity.
┌───────────────────────────────┐
│ Orchestrator (DeepSeek V4 Pro) │
└───────────────┬───────────────┘
│ (Decompose & Plan)
┌────────────────────────┼────────────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Coder Sub-Agent │ │ Reviewer Agent │ │ Explore Agent │
│ (vaked/coder / │ │ (deepseek-r1 / │ │ (local osaurus) │
│ qwen3-coder) │ │ v4-pro review) │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
Role Mapping Configuration
Define role preferences in entheai.toml:
[router]
orchestrator = "zen/deepseek-v4-pro" # Strong reasoning model for planning
max_parallel = 4 # Concurrent sub-agent worktrees
max_turns = 200 # Per-task turn cap
[agents.explore]
model = ["osaurus/qwen3-coder"]
[agents.coder]
model = ["vaked/coder", "deepseek/deepseek-chat"]
[agents.reviewer]
model = ["deepseek/deepseek-reasoner"]
[agents.test]
model = ["vaked/coder"]
[agents.docs]
model = ["vaked/coder"]
When a role is unconfigured, it falls back to [router].orchestrator, then default_model.
Fan-out & sub-agent roles
When invoked with entheai --fanout "<task>", the orchestrator plans, section-maps the input via entheai-mapper, and fans out execution across parallel sub-agents operating in isolated git worktrees (.worktrees/).
Worktree Isolation & Verification Protocol
- Parallel Execution: Each coder sub-agent runs in an isolated git worktree branch (
fed/<session>/<role>). - Empirical Verification Gate:
[fanout].verify_required = true(default).- Runs
[fanout].verifyor auto-detected./scripts/check.shinside each coder's worktree. - If tests fail, the traceback is auto-ingested into
memory-ppas a failure trajectory, and the branch is left unmerged. - If no verification script resolves, branches remain unmerged on
fed/…branches for human review (VerifyStatus::Unverifiable).
- Deterministic
MergeSeal:- Every verified merge computes
sha256(diff)andsha256(verify log). - Combined seal is logged in the final fan-out report (
integrated ✓ — seal <12-hex>).
- Every verified merge computes
Recursive Development ([fanout] executor = "agy")
Set [fanout] executor = "agy" to run sub-agents via the Antigravity CLI (agy).
- Depth Guard:
ENTHEAI_FANOUT_DEPTH ≤ 3(hard-capped to prevent infinite loops). - Turn Ledger: Every turn logs to
.entheai/recursion.logas JSONL. - Self-Audit: Merged diffs are evaluated against
AGENTS.mdrules by an automated post-execution self-audit.
Permission gate & YOLO
All side-effecting tool calls pass through entheai-permission.
Permission Postures (mode)
Cycle modes interactively with Shift+Tab in the TUI or configure [permission].mode:
ask(default): Prompts for confirmation before executing mutating actions (writing files, running shell commands).plan: Read-only mode. All file/search reads are approved; writes/shell calls are denied.auto: Approves read and write operations; prompts for shell/network calls.yolo: Auto-approves all tool calls and lifts turn caps (router.max_turns = u32::MAX).
Tool Pins ([permission].pins)
Pin individual tools to explicit postures:
[permission]
mode = "ask"
[permission.pins]
run_shell = "always_ask"
read_file = "always_allow"
write_file = "always_ask"
--yolo flag or mode = "yolo") disables all confirmation prompts. Only use YOLO in disposable git worktrees or containerized sandboxes.Memory — five namespaces
entheai manages memory across five dedicated SQLite + vector namespaces (entheai-memory):
| Namespace | Description |
|---|---|
codebase |
Codebase structure — symbol indexing, call graph, and architecture. |
learnings |
Durable facts and user preferences — "how we solved X". |
trajectories |
Task transcripts, tool call tracebacks, and verification outcomes. |
tools |
Large tool output spillover recalled via pointer. |
subagents |
Per-sub-agent scratchpad and intermediate outputs during fan-out. |
Prompt-Processing Pipeline (entheai-memory-pp)
When [memory] mode = "prompt-processing" is enabled:
- Stage 1 (Raw Experiential Store): Append-only raw storage of transcripts and tool outputs.
- Stage 2 (Native 1-Bit LLM Mesh Search): In-process ternary BitNet re-ranking (
entheai-ultragraph) running a trained 768-d linear reranker (reranker.ugm— 94.7% accuracy). - Stage 3 (Marqant Structure-Preserving Compression): Deterministic context pruning (
kompress-core) enforcing must-keep overrides for CamelCase, ALLCAPS, hex, CLI flags, and paths.
Frozen Nodes & Dynamic Re-Ranking
- Curated Doctrine: Markdown units in
frozen/*.md(NixOS, Rust, GitHub, Valyu, etc.) sit dormant until deterministic triggers match. BrainJudge: Background task judging recent tool activity to surface relevant frozen nodes proactively even without exact prompt keywords.- Experience Overlay (
frozen-ranks.json): Outcomes dynamically re-weight priors: verified success+0.02, verify failure-0.05(clamped[0, 2.0]). Original.mdfiles are never rewritten. /freeze&/thaw: Snapshot live entropy state to.entheai/checkpoints/<id>.jsonand rehydrate surviving spans into injected context briefs.[current]Awareness Ingestion: Live feeds from Valyu, WorldMonitor (clamped $\le 50$/day), and HFultrawhale-dogfoodQ&A batches flow into the raw memory soil.
Inspect memory via CLI: entheai --memory stats, entheai --memory list <namespace>, entheai --memory search <namespace> <query>.
Skills · plugins · MCP
entheai provides three extensibility vectors:
1. Skills System (crates/skills)
- Discovery: Automatically discovers
SKILL.mdinstructions in.agents/skills/and global customization roots. - Web Skill Installer:Discovers
entheai --skills add https://docs.stripe.com.well-known/skills.jsonor/llms.txt, fetches documentation, and writesskills/stripe-documentation/SKILL.md. - Management:
entheai --skills list,entheai --skills remove <slug>.
2. Model Context Protocol (crates/mcp)
- stdio Client: Spawns MCP server binaries at startup and exposes tools to the agent with prefix
<name>__<tool>. - Configured Servers in
entheai.toml:codebase:codebase-memory-mcp(symbol graph).valyu: Web & literature search via Python stdio bridge.smart-tree: Code intelligence tools viast --mcp.rmcp-sensors: Environmental sensors.
3. Obsidian Sync (crates/obsidian)
- Synchronizes session documentation, architecture summaries, and memory logs into an Obsidian vault (
[obsidian] enabled = true).
Visual TUI & Zen field
The interactive TUI (crates/tui) runs on ratatui with responsive canvas rendering:
Core Visual Features
- Brain Panel (
/brain): A rotating braille 3D pseudo-graph representing model, tools, context, and fleet node presence. Features direct idle-time sensor polling (slowing rotation when user steps away from keyboard) and frozen node wake glows. - Swarm Graph: Inline visualization during
--fanoutruns showing sub-agent worktree nodes, execution state, and empirical verification outcome gold flashes. - Zen View (
/zenorCtrl-G): Full-canvas living field with a breathing singularity core (BrainState::vitality()), orbiting faculty bodies, frozen constellation ring, current-awareness motes, and dissolving reply motes. - Color Themes (
/theme): Switch ambient palettes betweenentheia(teal),ember(night fire),verdant(garden), andvoid(monochrome + gold thread). Source identity colors (gold, cyan, green) are machine-validated and invariant across themes. - Pomodoro Timer: Automatic 25m work / 5m break countdown displayed in status bar.
- Modals (
/config&/setup): Arrow-key navigable setup wizards for switching models, permission modes, fan-out settings, and themes.
TUI Command Shortcuts
| Command / Key | Action |
|---|---|
/zen or Ctrl-G |
Toggle full-canvas Zen field |
/theme [name] |
Cycle or set ambient theme (entheia / ember / verdant / void) |
/brain |
Toggle brain panel side bar |
/config |
Open interactive configuration modal |
/setup |
Launch first-time setup wizard |
Shift+Tab |
Cycle permission posture (ask -> plan -> auto -> yolo) |
/freeze / /thaw |
Snapshot session checkpoint / list and restore checkpoints |
/current [pulse] |
Check current-awareness budget status / trigger immediate pulse |
/radio / Ctrl-P / Ctrl-N |
Ambient radio controls (pause / next station) |
| `/speak [on | off |
Companion, Radio & Speak
Peripheral integrations that run concurrently with the terminal session:
1. Companion Window (crates/companion)
A 180×180 px borderless, always-on-top floating window (winit + softbuffer) spawned when [companion].enabled = true:
- QR Code Pairing: Encodes session ID, Tailscale MagicDNS hostname, port, and working directory for phone/device pairing.
- State Telemetry: Listens on a Unix socket (
$TMPDIR/entheai-<sid>.sock) forStateChangeevents:- Idle: Slow teal pulse (3s cycle)
- Working: Fast teal pulse (1.5s) + orbiting spinner
- Permission Pending: Magenta pulse (1s) + "?" glyph
- Error: Red dim pulse (4s)
- Click Action: Click window to copy
http://<host>.local:9876/session/<sid>to system clipboard. - CLI Flag:
entheai --no-companiondisables the window for a session.
2. Audio Radio (crates/radio)
Zero-fetch ambient audio generator running through rodio on a dedicated thread:
- Station 1 ("Standing-Onde"): Bundled track by 8bit-Wraith embedded directly in the binary (
include_bytes!). - Station 2 ("Mirror in F — Fable's seed"): Infinite, deterministic Arvo Pärt tintinnabuli generator synthesized sample-by-sample in pure
stdmath, seeded byb"FABLE". - Controls:
/radio pause(Ctrl-P),/radio next(Ctrl-N— cycles stations),/radio stop.
3. OS-Native Speech Output (crates/tts)
Assistant responses read aloud via native OS TTS synthesizer (AVSpeechSynthesizer on macOS):
- Toggle via
/speak,/speak on,/speak off, or interrupt with/speak stop. - Operates entirely offline with zero network calls or heavy models.
Visualization gallery
entheai is visual by design — built on ratatui with braille 3D projections, custom color-harmony themes, and dynamic telemetry streams over NATS.
gallery.entheai.com for the full-screen visual showcase with live quantum shader controls, prompt copies, and category filters.1. The Zen View (/zen or Ctrl-G)
The operator's canvas: the entire terminal area transforms into a full-canvas living field.
- Singularity Core: A breathing center light whose brightness and pulse rate scale with cognitive activity (
BrainState::vitality()). - Orbiting Faculties: Model, tools, and context rendered as luminous bodies tethered to the center.
- Frozen Constellation: Counter-rotating ring representing active
frozen/*.mddoctrine. Active nodes flare and label. - Current-Awareness Motes: Drifting particle field colored by source origin — dogfood gold (genetic corpus), Valyu cyan (academic/web search), WorldMonitor green (living world news), and violet (internal).
- Whisper Reply & Input: The assistant reply materializes directly in the field, fanning out into motes as it dissolves into soil.
Capture Note: Recorded live in terminal space using Ghostty (v0.2.0+) with entheai /zen active on Apple Silicon (M1 Max, 120 FPS render target).
2. Brain-Ring Constellation
The always-on compact side panel (/brain, [viz] brain = true).
- FACULTIES: Braille 3D pseudo-rotation tracking live activity in
model,tools, andcontext. - FLEET: Live presence ring displaying connected remote federation nodes over NATS (
entheai-bus). - IDLE SENSOR: Bypasses MCP using direct system idle polling — linear rotation slowdown as the user steps away from the keyboard, returning instantly to full speed on input.
- FOOTER: Live
wk N(active fan-out workers),nats ●/○(bus status),ctx %(context window saturation), andcmp(Marqant compression ratio).
Capture Note: Captured during an interactive TUI session with side panel width set to brain_width = 26.
3. The 4 Ambient Palettes (/theme)
All themes use global, machine-validated source identity colors (worst deutan $\Delta E \ge 9.1$, normal-vision $\Delta E \ge 18.0$) while restyling ambient surfaces:
| Theme | Aesthetic | Visual Tone |
|---|---|---|
entheia |
Signature teal default | Clean, crisp, high-contrast cyan/teal glow |
ember |
Night fire | Warm amber, deep gold, obsidian darkness |
verdant |
The garden | Deep emerald, moss, organic growth hues |
void |
Monochrome austerity | Stark black & white with lineage gold thread |
Capture Note: Generated via /theme <name> in the interactive TUI and validated using entheai-viz::theme luminance tests.
4. Fan-Out Orbits & Swarm Graph
Visualized during parallel execution (entheai --fanout "<task>" or Ctrl-V).
- Orchestrator Hub: DeepSeek V4 Pro orchestrator at the hub planning and routing.
- Model-Matched Sub-Agents: Orbits of parallel coders running in isolated git worktrees.
- Status Indicators: Pending (dim), running (cyan pulse), done/verified (gold flash), failed (magenta alert).
- Empirical Gate & Merge Seals: Completed branches pass
./scripts/check.shand receive a deterministic SHA-256MergeSealbefore merging.
Capture Note: Captured live during a 4-worker parallel refactor batch on entheai.
5. The Kin Ring ([kin])
The Zen field's outermost, slowest-turning ring ([kin] nodes = ["https://riva.vaked.dev/"]).
- Flowing Kin: Reachable sibling nodes breathe in the theme's kin color and display their host label (e.g.
riva). - Unreachable Kin: Nodes failing liveness check sit as dim, dark points — honest status, never faked.
- Zero-Block Background Task: Background worker polls status endpoints once per
poll_secs(default 120s) without blocking UI execution.
Capture Note: Captured with live NATS & HTTP status polling enabled across tailnet nodes.
Crate map & system
entheai is structured as a modular Rust workspace (resolver v2) compiled for Apple Silicon (aarch64-apple-darwin):
Cargo.toml # Workspace root
├── bin/entheai/ # CLI binary (clap, tokio, sentry, mimalloc)
├── bin/entheai-worker/ # Federation worker (--serve / --dispatch)
├── bin/entheai-launch/ # Native .app launcher (Ghostty window)
├── crates/config/ # TOML -> Config deserialization
├── crates/core/ # EntheaiAgent (adk-rust backed agent loop)
├── crates/tools/ # Root-scoped tools (read, write, edit, shell, search)
├── crates/permission/ # Policy & Prompter permission gate
├── crates/router/ # Role -> model resolution & agent factory
├── crates/orchestrator/ # Fan-out decomposition & worktree pool
├── crates/mapper/ # @{path} sectioned input mapping
├── crates/tui/ # Interactive ratatui chat & visualizations
├── crates/companion/ # Session beacon window (QR + status animation)
├── crates/memory/ # 5-namespace SQLite + vector store
├── crates/memory-pp/ # Prompt-processing (raw store, native 1-bit mesh, Marqant, BrainJudge)
├── crates/current/ # Current-awareness ingestion (Valyu + WorldMonitor + dogfood)
├── crates/viz/ # TUI visualization models (brain ring, swarm, Zen field)
├── crates/radio/ # Audio generator (Standing-Onde + Mirror in F)
├── crates/tts/ # OS-native text-to-speech engine
├── crates/mcp/ # MCP client & supervisor
├── crates/skills/ # SKILL.md discovery & web installer
├── crates/launcher/ # Native app window spawner & shader doctor
├── crates/obsidian/ # Obsidian wiki-sync
├── crates/bus/ # NATS event bus DTOs & telemetry
├── crates/federation/ # Distributed swarm & work-queue
├── crates/sandbox/ # Landlock/seccomp worker confinement
├── crates/ultragraph/ # Native Rust ternary 1-bit LLM mesh port
└── crates/kompress-core/ # Context-pruning engine (must-keep overrides)
Binary Distribution & Release Profiles
- PGO Release (
scripts/build-release.sh):opt-level=3,lto="fat",codegen-units=1,target-cpu=native,mimallocallocator. - Reproducible Release (
scripts/build-repro.sh): Anchoredapple-m1baseline,SOURCE_DATE_EPOCH, path remapping, verified byte-identical manifests (dist/repro-manifest.json).
Roadmap & Stability
entheai has reached v1.0.0 Quantum Completeness, establishing strict public API stability commitments.
Release History
- v1.0.0: Declaration of public API stability contract (docs/STABILITY.md), deterministic merge seals, byte-reproducible release builds (
scripts/build-repro.sh), self-auditing recursive dev (agy). - v1.1.0: Live current-awareness ingestion (
entheai-current) via Valyu, WorldMonitor (clamped $\le 50$/day), and daily budget ledgers. - v1.2.0:
karmapa-chennocall home ([chenno]) publishing frozen context briefs to Git; 100 MB shell output caps. - v1.3.0: Full-canvas Zen view (
/zen), 4 ambient color themes (/theme), source-colored current motes, HFultrawhale-dogfoodingestion, and "Mirror in F" procedural audio station.
Stability Guarantees (SemVer 1.0)
- Stable: CLI flags,
entheai.tomlschema, versioned schemas (entheai.fanout.*,entheai.entropy.v1,entheai.checkpoint.v1,entheai.learning.v1,entheai.repro.v1), verification invariants (verify_required = true, SHA-256 seals), andfrozen/*.mdfrontmatter format. - Unstable: Internal Rust crate APIs (
entheai-core,-orchestrator, etc.), TUI visual layout details, and tunable experience rank deltas.