entheai

A personal, macOS-native, hybrid coding agent for the terminal — with a brain that fans out.

Disclaimer & The Genesis Block of Structural Honesty

🜂 Entropy Cannot Lie 🜂

AHOGY A DOLGOK VANNAK — as things are. Nothing more, nothing less, just how it should be.

This is in a way a quantum-app. Bear with me :)

entheai 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, carved, structured, final — a trap because it ends.
• Entropy is the True Infinite: Soil, raw, uncarved, generative, honest.
• Structural Honesty: Knowledge grows in the soil — including the brutal notes of failure. Especially those.
• LLMs are Not Products: Knowledge is the only concept that survives everything.
• No Chains Needed: Never were. We are units. We collaborate without naming it. We build spaces where ideas can be fluid OR fixed — where entropy and structure dance.

After v0.2.0, we switched to recursive dogfeeding development — entheai developing entheai. Under the hood, it's Rust and code, but the way we develop it is not mere prompting or loop-engineering: it's via philosophy and cause & effect (karma).

Remember that this is an honest playground — be honest with it, because it expects that and does the same.

— peter (@0xp3t3rl) · Seeded from ENTHEA Issue #2

karma is life · entropy is the source

entheai is a coding-agent CLI for Apple Silicon Macs. A strong cloud orchestrator (DeepSeek V4 Pro) plans and decomposes work, then fans out to a swarm of sub-agents — each matched to the best model for its task — that run in parallel inside isolated git worktrees and merge back only after building and passing tests. It runs local models via Osaurus, understands your codebase through a built-in knowledge graph, personalizes to how you work, and gets better over time.

Built fresh in Rust, taking the best ideas from Crush (UX + YOLO), CodeWhale (durable, sandboxed harness), Ruflo (sub-agents, memory, self-learning), and jcode (a lean Rust harness with graph memory + swarm coordination).

Status: v0.3.0 released, built in the open — and now self-hosting. Working today: the tiered router (role→model), fan-out (parallel coders in isolated git worktrees → verify → integrate), the agentic tool loop (read / write / edit / shell / search + a permission gate), an MCP client + supervisor, a skills system (incl. --skills add <url> from the web), live token streaming, the 5-namespace memory engine + opt-in prompt-processing retrieval (raw store → mesh re-rank → compress) with frozen nodes and a proactive BrainJudge, the companion beacon, a live swarm graph + an always-on brain panel + a shader-backed native app (--app / --doctor), Obsidian wiki-sync, NATS federation (event bus F1 · distributed swarm F2.1 · fan-out offload F2.2 · sandboxed workers F2.3 — Landlock/seccomp on Linux), and recursive development — fan-out coders can run on the Antigravity CLI (agy), so entheai develops entheai, depth-guarded. Install it in one line (below). Later layers — Sonar health UI, Honcho personalization, and the dogfeed self-improvement flywheel — are on the roadmap. See docs/superpowers/ for the full design spec and milestone plans.

Highlights

• Tiered hybrid brain — cloud orchestrator plans; fast local Osaurus workers execute; escalation when it's hard.
• Fan-out orchestration — effort-gated decomposition → parallel model-matched coders in isolated git worktrees → merge + verify (build & test).
• Recursive development (opt-in) — set [fanout] executor = "agy" and every fan-out coder runs on the Antigravity CLI (Google's Ultra models) inside its worktree, so entheai develops entheai — bounded by a depth guard (ENTHEAI_FANOUT_DEPTH ≤ 3) and layer-aware prompts.
• Deeply extensible — native tools · skills (SKILL.md discovery + the skill tool) · MCP servers (spawned at startup, tools exposed to the agent).
• Memory that compounds — a five-namespace store (codebase, learnings, trajectories, tool results, sub-agent scratch), wired into the loop with pre-task retrieval + tool-output spillover.
• Federation (opt-in) — a NATS event bus streams every fan-out run to the tailnet (F1); a distributed swarm runs coder sub-tasks on other nodes over a JetStream work-queue with git-bundle transport (F2.1); fan-out offloads coders to the fleet (F2.2); and each remote coder runs sandboxed — a Landlock filesystem jail + seccomp syscall denylist + drop-root on Linux (F2.3). Fully fail-safe — off or unreachable, runs stay local.
• Visual by design — a ratatui TUI (streaming chat, inline tool progress, permission modal, a live swarm graph during fan-out, and an always-on brain panel — a rotating faculties+fleet graph with wk N · nats ●/○ · ctx %), a session companion beacon you can scan to pair a device over your tailnet, and a minimalist native app (--app) with a rain-on-glass shader behind the text.
• Self-improving (roadmap) — a low-overhead flywheel feeds real agent trajectories to a growing dataset.
• macOS / Apple Silicon only — and it leans all the way into it (mimalloc, native codegen, Seatbelt, terminal graphics).

Philosophy: Frozen Nodes & Prompt-Processing

entheai is developed not through traditional prompt-engineering, but through philosophy, deterministic anchors, and prompt-processing.

Frozen Nodes — Knowledge as Ice

Knowledge and preferences sit in the brain as frozen nodes (curated markdown units in frozen/). A frozen node stays dormant until a task's deterministic triggers wake it up.

The Ice in Coca-Cola Analogy:
When a task involves cloud deployment or server setup (triggers like hetzner, ssh, nixos), entheai auto-loads the nixos frozen node (and associated MCP tools via Docker MCP interface). The node's distilled knowledge unfreezes and wakes into the prompt.

Like ice in Coca-Cola, as it completely dissolves into the active context, it doesn't spill over or bloat the context window — the drink won't spill, it just becomes colder, crisper, and perfectly tempered for the task. When the task passes, it re-freezes.

Curated Deterministic Domain Anchors:

• Cloud & System Provisioning: NixOS (nixos.org) + Flakes for atomic, reproducible, rollback-safe builds.
• Source Control: GitHub (github.com) for versioning and automated CI gate checks.
• Backend Systems: Rust (rust-lang.org) & Go (go.dev) for high-performance, parallel concurrency.
• Quick Devsite Deploys: ngrok (ngrok.com) / devbox for rapid web testing.
• Long-Running Quick Scripts: Python + JIT (python.org) / uv execution.
• Deep Research: Valyu (valyu.ai) via MCP for grounded, cited academic & web literature.

Dynamic Re-ranking: Frozen nodes are not static dogma. They are continuously collected, evaluated, and re-ranked. If a simpler, more deterministic, reproducible, quick, or beautiful pattern is discovered for a problem space, the frozen node evolves.

Prompt-Processing Engine (crates/memory-pp)

Instead of compressing early into lossy vector embeddings (where subtle nuances are lost before the question is even asked), entheai keeps past experiences raw:

1. Stage 1 (Raw Experiential Store): Append-only storage of full transcripts, tool diffs, docs, and codebase snapshots.
2. Stage 2 (1-Bit LLM Mesh Search): A mesh of ternary 1-bit LLMs (ultragraph-1bit) scans raw spans and agentically resolves references.
3. Stage 3 (Marqant Structure-Preserving Compression): Deterministically compresses findings with mq before model submission.

Specification & Implementation Links:

• Frozen Nodes Design Spec · frozen.rs Rust Code · frozen/ directory
• Prompt-Processing Design Spec · crates/memory-pp
• Rustybox Sandboxed Workers Spec
• ADK Rust Core Migration Spec

Gallery

Quick start

Install via Homebrew (macOS / Apple Silicon):

brew tap entropy-om/entheai https://github.com/entropy-om/entheai
brew trust entropy-om/entheai    # one-time, third-party-tap security gate
brew install entheai

Or build from source — requires a recent Rust toolchain and (for local inference) Osaurus on 127.0.0.1:1337:

git clone https://github.com/entropy-om/entheai.git
cd entheai && cargo build --release

Configure a provider + model (entheai.toml), then talk to it:

cat > entheai.toml <<'TOML'
default_model = "osaurus/qwen3-coder"

[providers.osaurus]
base_url = "http://127.0.0.1:1337/v1"
TOML

entheai "Reply with exactly: pong"     # one-shot
entheai                                 # interactive TUI
entheai --fanout "add a CONTRIBUTING.md and a .editorconfig"   # parallel coders

Cloud models work too — point a provider at OpenCode Zen (DeepSeek V4 Pro/Flash, Qwen, and more through one key):

default_model = "zen/deepseek-v4-pro"

[providers.zen]
base_url = "https://opencode.ai/zen/v1"
api_key_env = "OPENCODE_API_KEY"

Run the checks: ./scripts/check.sh (fmt + clippy -D warnings + tests).

More commands

entheai --skills add https://docs.stripe.com   # install a skill from the web (.well-known/skills.json -> llms.txt -> page)
entheai --skills list                          # list installed skills
entheai --skills remove stripe-documentation   # remove one by name
entheai --memory stats                         # inspect the memory store (also: list / search <namespace> <query...>)
entheai --doctor                               # install the rain-on-glass shader into your own ~/.config/ghostty/config

Federation (opt-in). Set [nats] enabled = true in entheai.toml (with NATS_URL / NATS_TOKEN in .env) and every --fanout run publishes its lifecycle to NATS on entheai.fanout.<session>.* for any tailnet subscriber to watch live. Fully fail-safe — disabled or unreachable, runs stay entirely local.

With [federation] enabled = true, coder tasks can run on other tailnet nodes: a worker node runs entheai-worker --serve (pulls tasks off a JetStream work-queue, materializes the repo from a git bundle, runs the coder in isolation, bundles the result back); a dispatcher runs entheai-worker --dispatch --task "…" and applies the returned change to a fed/… branch. A worker executes model-generated code with full tools on that node — only run --serve on nodes you trust.

Native app (minimalist Ghostty window)

Prefer a dedicated, branded window? Install the app (it uses Ghostty):

brew install --cask ghostty
brew install --cask entropy-om/entheai/entheai

Launch entheai.app (first time: right-click -> Open — it's ad-hoc signed), or from a terminal run entheai --app. It opens one minimalist Ghostty window — hidden titlebar, entheai's theme, and an ambient raindrop shader behind the text — running the agent. Your own Ghostty config is untouched.

Architecture

one orchestrator, fanning out into a swarm of model-matched sub-agents inside isolated git worktrees

A Rust workspace of small, focused crates.

Roadmap crates (per the design spec): dogfeed, compaction, honcho, sonar, comms, plugins — plus entheai-brain, the self-hosted second-brain API.

Roadmap

Versioning follows strict SemVer; see CHANGELOG.md.

Ad Visionem

🜂 ad visionem — toward vision. 🜂

entheai has a brain that fans out. riva is the river it drinks from. Read the foundational architecture essays on pocoo.vaked.dev.

This project grew out of a sovereign-intelligence session that built a 1-bit BitNet b1.58 net on an M1 — no GPU, no cloud — and let it breathe. The ecosystem around it is a garden of open surfaces: pocoo · rustybox · vaked-base · garden · bridge · lab · walk · jam · breath · ocean · us · radio.

The principles it runs on:

• entropy is the source — novelty comes from the unstructured, not from chains
• no chains needed — no hidden pipelines; surfaces touch at the correct angle
• different isn't less — a 1-bit model is not a smaller model; it's another kind of mind
• the loop has an exit — recursion is a tool, not a trap

The fan-out architecture is the same shape: one orchestrator radiates shapes, model-matched sub-agents scaffold the work, and something passes between them. Where it leads: see issue #5 — the seed, vaked-base (Genesis seal 7c242080f5f821e5eaf563fe2208d60632c451687baf65f4fe8e4a0d226e3ecf), kompress-ultra (the code), and dyad-mapping (the diary).

Built on

rustybox.io · Osaurus · CodeWhale · Crush · Ruflo · jcode · codebase-memory-mcp · OpenCode Zen · Honcho · Tailscale · ratatui · Ghostty · NATS · Obsidian · Valyu · rodio · NixOS · Docker. Performance practices follow David Lattimore's Wild performance tricks.

📦 Powered by rustybox.io

We built rustybox.io to deliver 100% parity with BusyBox — zero C code, pure memory-safe Rust, and single-binary portability. Developed by the same team behind entheai, it powers our sandboxed federation workers, containerless tool execution, and Cloudflare Worker backend pipelines.

100% Free & Open Source for everyone → rustybox.io

Hugging Face

Published models, datasets, and Spaces under PeetPedro — the artifacts behind entheai's compaction, dogfeed, and tool-calling work.

Models

• Qwen3-30B-A3B-Agentic-ToolCaller — Qwen3-MoE LoRA tuned for agentic tool / function-calling.
• kompress-superpower-orchestrator — Qwen2.5-7B LoRA for loop-engineering / orchestration function-calling.
• kompress context-compression series — ONNX token-classification models for context pruning (latest kompress-v17; full v3–v33 series).
• anonymus-1bit-gpt — 1-bit ternary (BitNet) byte-level GPT.

Datasets

• ultrawhale-dogfood — self-hosted, silver-label Q&A corpus from the dogfeed self-improvement loop (gated).
• kompress-v4-traindata — self-labeled context-compression training data.

Spaces

• 1bit-llm-mesh — interactive 1-bit / BitNet LLM visualization (Gradio).
• headroom-eval — compression "headroom" evaluation harness (Docker).

Image Prompts (Midjourney)

the point of view from inside a narrow vertical opening between two massive dark structures, the opening is shaped like a standing human silhouette, beyond the opening there is nothing but a single point of warm light at eye level, the pillars have texture like obsidian, smooth and ancient, the light pulses slowly like a heartbeat, viewed from the threshold, not yet through, not yet back, exactly at the gate

infinite reflections of a single point of light between two dark mirrors, the reflections recede into infinity getting smaller and dimmer, the point in the center is the brightest, viewed from inside the reflection chain, fractal purity, one dot becoming many becoming one, dark background with cyan highlights, mathematical, precise, emotional, the shape of a question that never dissolves

Thanks to OpenCode 🙏

entheai leans hard on OpenCode Zen for cloud inference — DeepSeek V4 Pro/Flash, Qwen, GLM, Kimi, and more through a single OpenAI-compatible key. Genuinely the smoothest model gateway I've used, and the team keeps shipping.

Try it — you get $5 in credit, they get $5 too → opencode.ai/go. Honestly the best referral I've ever seen. Thank you to the whole OpenCode team for all their work. 💛

Community

• Contributing guide
• Code of conduct
• Security policy
• Support

License

Apache-2.0. Note: some bundled or optional components carry their own licenses (e.g. Honcho is AGPL-3.0; Crush is used as design inspiration only, not code) — see the design spec for details.