What is entheai

entheai is a personal, macOS/Apple‑Silicon, terminal‑native hybrid coding agent written in Rust. A cloud orchestrator plans; it fans out to a swarm of model‑matched sub‑agents that build in parallel and merge back verified.

Highlights

Runs local models via Osaurus, ships a visual TUI with shader backgrounds and a live 3D codebase graph, and keeps compounding memory across sessions.

Hybrid brain & fan-out

The tiered hybrid brain separates planning from execution. A capable cloud model reasons about the whole task; cheaper local or specialized models do the parallel work.

Fan-out

The orchestrator decomposes a task into units and dispatches a sub‑agent per unit — each in its own git worktree, each on the model that best fits its role. Work merges back only after that unit's tests pass.

task ──▶ orchestrator (deepseek/v4-pro)
           ├─ coder    · osaurus/qwen2.5-coder
           ├─ test     · deepseek/v4-pro
           └─ review   · osaurus/deepseek-r1
                         ▼
              merge + verify ▶ main

Who it's for

Solo developers on Apple Silicon who want an agent that lives in the terminal, respects local compute, and can parallelize large refactors without a cloud bill for every token.

Install & build

Clone the repo and build a release binary. You'll need a recent Rust toolchain.

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

./target/release/entheai --version

Configure entheai.toml

entheai reads entheai.toml from the working directory. Point it at a local Osaurus model or a cloud provider.

[provider.osaurus]
endpoint = "http://127.0.0.1:11434"

[provider.opencode-zen]
api_key = "env:OPENCODE_ZEN_KEY"

[router]
plan = "deepseek/v4-pro"
code = "osaurus/qwen2.5-coder"

Core keys

First run

Ask entheai to summarize your repo. Tokens stream into the terminal as the plan comes back.

entheai "summarize this repo"

Providers

entheai speaks to several model backends. Local‑first via Osaurus; cloud when you need heavier reasoning.

Models & ids

Every model is referenced with the <provider>/<model> convention.

osaurus/qwen2.5-coder
opencode-zen/scribe
deepseek/v4-pro
openrouter/anthropic/claude

The agent loop

Perceive → plan → act → verify. Each tool call passes through the permission gate; each result folds back into memory.

The tiered router

The router matches each unit of work to a model tier by difficulty, cost, and locality — planning to the strongest model, mechanical edits to fast local ones.

Fan-out & sub-agent roles

Roles include coder, docs, test, and review. Each runs in an isolated worktree so parallel work never collides.

Permission gate & YOLO

By default every side‑effecting tool call asks for approval.

allow run_shell("cargo test")? [y/N]

Memory — five namespaces

Compounding memory with auto‑compaction keeps context lean while retaining what matters.

Skills · plugins · MCP

Bundle reusable procedures as skills, add capabilities with plugins, and connect external tools over MCP.

Shader & codebase graph

The TUI renders an animated shader background and can toggle a live 3D graph of your codebase — nodes are modules, edges are dependencies, lit as the agent touches them.

Companion & Radio

Two small extras that run alongside the terminal session: a desktop companion window and an in-TUI music player.

Companion

A borderless, always-on-top 180×180 window that spawns automatically when the TUI starts. It shows a QR code for pairing a phone to the session over Tailscale, and doubles as a glanceable status light — it glows and pulses differently depending on whether the agent is idle, working, waiting on a permission prompt, or has hit an error. Click it to copy the session URL to your clipboard; it fades out when the session ends.

The QR code encodes the session ID, Tailscale MagicDNS hostname, port, and working directory.

[companion]
enabled = true          # spawn on TUI start
always_on_top = true    # float above other windows

# Suppress the companion window for a session
entheai --no-companion

Radio

An in-TUI music player. Give it a YouTube URL and it downloads the audio in the background (via yt-dlp) and plays it through your speakers (via rodio) — on a dedicated thread, so audio never blocks the UI.

Downloads are cached at ~/.cache/entheai/radio, keyed by video ID — repeat plays are instant. The now-playing status appears in the status bar (♪ Song Name) and clears on stop or when the queue empties.

Crate map & system

entheai is a Rust workspace. The orchestrator drives providers, Osaurus, a codebase‑memory MCP server, and the sub‑agent pool.

entheai-core      · agent loop, router
entheai-providers · osaurus, zen, deepseek
entheai-memory    · MCP server, 5 namespaces
entheai-tui       · shader + codebase graph
entheai-agents    · worktree pool, merge/verify

Roadmap & design docs

Longer‑form specs and plans live alongside the source.

Design docs on GitHub ↗