README
¶
Daintree Assistant
❗ Internal testing only, for now. Pre-release software under active development. Anyone is welcome to use it, but expect breaking changes — to the backend wire protocol, the on-disk schema, and the sign-in flow. An update may mean re-running install and losing local state.
A single native Go binary: a local command-line orchestration assistant for Daintree. It plans Daintree operations, spawns and supervises visible agent terminals, watches them with cheap models, schedules timers, and keeps your main conversation clean.
It is not a code editor and never edits your files. When a change is needed it spawns a visible agent in a worktree and supervises it.
Every model call takes one path — CLI → Daintree Assistant backend → OpenRouter → the
selected model. The CLI holds no provider credential of its own: it forwards your key, and
the backend owns the system prompt, skill selection, and model choice. See
docs/BACKEND.md.
Supported platforms
macOS (arm64, amd64) and Linux (amd64, arm64).
Windows does not run — and is not merely untested. Exactly one process at a time may
own a project's state.db, and that lease is an flock, which has no Windows port. Every
stateful mode takes the lease before doing anything, so all of them fail there.
Installing
Two steps, and nothing else — no npm, no node, no native toolchain. The result is one
self-contained ~24 MB binary; nothing is fetched at run time.
1. Install Go. You need 1.21 or newer — not 1.25.8. Go 1.21+ reads this module's
go 1.25.8 directive and downloads the matching toolchain itself. Go is a build-time
requirement only; the binary it produces does not depend on it.
brew install go # macOS
sudo snap install go --classic # Linux (distro packages are often too old)
go version # want go1.21 or newer
No Homebrew or snap? Take the official package from https://go.dev/dl/.
2. Install, sign in, verify.
go install github.com/daintreehq/assistant/cmd/daintree-assistant@latest
daintree-assistant login # choose "Official", paste your API key
daintree-assistant doctor # read it top to bottom; you want no FAIL lines
Two things that trip people up:
go installwrites to$(go env GOPATH)/bin(usually~/go/bin), which is not onPATHby default on macOS — so the install succeeds and the command is then not found. Fix it withecho 'export PATH="$(go env GOPATH)/bin:$PATH"' >> ~/.zshrc && exec zsh.- During the tester phase your API key is your own OpenRouter key, and it funds every model call your turns make — including background watcher and supervision work that runs while you are not looking. Use a dedicated low-limit key, not your main one.
Updating
Updating is a full reinstall — the same one command:
go install github.com/daintreehq/assistant/cmd/daintree-assistant@latest
You never update Go. Any 1.21+ downloads whatever toolchain this project requires by itself, so a Go install you set up once keeps working.
There is no self-update command and nothing tells you when you are behind, which matters
because the backend deploys independently and the skew failures are hard rather than
graceful: a protocol mismatch answers HTTP 426 and the turn cannot run, and an outdated
on-disk schema is refused. So re-run the install command whenever a backend or schema
change is announced, then run doctor.
Running it
daintree-assistant # interactive cockpit
daintree-assistant "which worktrees are ready?" # one-shot, prints, exits
daintree-assistant --json "…" # one-shot, JSONL events to stdout
daintree-assistant --classic # plain line REPL (also the non-TTY fallback)
daintree-assistant doctor # environment check
daintree-assistant status # supervisor health and live work
daintree-assistant support-bundle # redacted diagnostics to send a maintainer
The cockpit renders inline in your terminal's normal screen buffer — never the
alternate screen, never with the mouse captured — so the host terminal keeps native
scrolling, selection, and copy-paste. ^O opens the operations deck, ^X toggles raw
tool detail, /help lists the rest.
doctor is the gate. It diagnoses the install, the sign-in (including "no credit
left" as its own verdict), the backend, and both MCP connections, and exits non-zero only
on a real failure. Start there when anything is wrong.
Inside Daintree
Daintree launches the CLI and injects the MCP connection via DAINTREE_MCP_URL,
DAINTREE_MCP_TOKEN, and DAINTREE_PROJECT_ID. Without them it runs in degraded local
mode, where its whole orchestration role is offline: file reads, memory, timers and the
audit trail still work, but nothing that reaches a terminal, agent, or worktree does.
Contributing
git clone https://github.com/daintreehq/assistant && cd assistant
make build # → ./bin/daintree-assistant
make install # → /opt/homebrew/bin or /usr/local/bin
go test ./... # no network — fakes for MCP and the backend
go vet ./... && gofmt -l .
make install forces GOBIN so it cannot leave a second copy behind. Daintree finds the
CLI by a PATH lookup, so a stale copy earlier on PATH silently wins — and the symptom
is not "wrong version" but a feature that mysteriously does not exist. doctor lists
every copy it finds.
Documentation
| Testing it | |
|---|---|
docs/beta/FIRST_RUN.md |
Install → sign in → first result |
docs/beta/TROUBLESHOOTING.md |
A decision tree keyed to doctor's check ids |
docs/beta/PRIVACY_AND_DATA.md |
What leaves your machine |
docs/beta/INTERNAL_BETA.md |
Scope, limitations, what it costs you |
| Working on it | |
|---|---|
docs/BACKEND.md |
The model / skill / prompt story — start here |
docs/ARCHITECTURE.md |
How the pieces fit |
docs/BUBBLE_TEA.md |
The cockpit contract |
docs/SUPERVISOR.md |
The persistent daemon |
docs/TOOLS.md |
Adding a tool |
docs/LOGGING.md |
The debug-log event reference |
docs/generated/ |
Generated from the live registry: tools, commands, compatibility |
License
Apache 2.0. See LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
benchmarks
|
|
|
orchestration
command
Command orchestration runs the end-to-end orchestration benchmark: the REAL CLI binary + the LIVE local backend (127.0.0.1:8473) against a scripted fake Daintree world.
|
Command orchestration runs the end-to-end orchestration benchmark: the REAL CLI binary + the LIVE local backend (127.0.0.1:8473) against a scripted fake Daintree world. |
|
orchestration/runner
Package runner executes benchmark scenarios: it builds the real CLI binary, spins a fresh fake-Daintree world + isolated state dir per run, drives one one-shot `--json` turn against the LIVE local backend, and grades the result with the scenario's checks.
|
Package runner executes benchmark scenarios: it builds the real CLI binary, spins a fresh fake-Daintree world + isolated state dir per run, drives one one-shot `--json` turn against the LIVE local backend, and grades the result with the scenario's checks. |
|
orchestration/scenario
Package scenario defines the benchmark cases: a frozen prompt + a scripted fake-Daintree world + objective pass predicates.
|
Package scenario defines the benchmark cases: a frozen prompt + a scripted fake-Daintree world + objective pass predicates. |
|
cmd
|
|
|
daintree-assistant
command
Command daintree-assistant is the single static-binary entrypoint for Daintree's local orchestration assistant.
|
Command daintree-assistant is the single static-binary entrypoint for Daintree's local orchestration assistant. |
|
tooldump
command
Command tooldump writes this CLI's tool inventory — the exact `input.tools` payload sent to the backend on every turn — to stdout as JSON.
|
Command tooldump writes this CLI's tool inventory — the exact `input.tools` payload sent to the backend on every turn — to stdout as JSON. |
|
internal
|
|
|
agent
Package agent drives the main-thread agentic turn loop.
|
Package agent drives the main-thread agentic turn loop. |
|
app
Package app is the single composition root.
|
Package app is the single composition root. |
|
asyncwork
Package asyncwork is the runtime owner of asynchronous tool invocations — the durable futures behind terminal.run.async / terminal.await.async.
|
Package asyncwork is the runtime owner of asynchronous tool invocations — the durable futures behind terminal.run.async / terminal.await.async. |
|
backend
Package backend is the native Daintree Assistant backend client — the CLI's ONLY model gateway.
|
Package backend is the native Daintree Assistant backend client — the CLI's ONLY model gateway. |
|
cli
Package cli owns CLI routing (one-shot / classic REPL / doctor / cockpit seam), the human console sink, and the classic line REPL.
|
Package cli owns CLI routing (one-shot / classic REPL / doctor / cockpit seam), the human console sink, and the classic line REPL. |
|
cli/jsonout
Package jsonout is the one-shot JSONL sink, schema v1.
|
Package jsonout is the one-shot JSONL sink, schema v1. |
|
cli/render
Package render is the dependency-free ANSI console helper.
|
Package render is the dependency-free ANSI console helper. |
|
commands
Package commands is the slash-command subsystem: the pure-data COMMAND_REGISTRY (single source of truth for names/syntax/palette/help — drives suggestions, help blobs, and both handler surfaces) plus the two handlers (REPL prints via render; UI returns structured cards) and the rich /doctor checklist.
|
Package commands is the slash-command subsystem: the pure-data COMMAND_REGISTRY (single source of truth for names/syntax/palette/help — drives suggestions, help blobs, and both handler surfaces) plus the two handlers (REPL prints via render; UI returns structured cards) and the rich /doctor checklist. |
|
config
Package config resolves the assistant's runtime configuration with the trusted-env security boundary.
|
Package config resolves the assistant's runtime configuration with the trusted-env security boundary. |
|
costledger
Package costledger accumulates what this session has spent on the caller's own upstream key.
|
Package costledger accumulates what this session has spent on the caller's own upstream key. |
|
credentials
Package credentials persists the assistant's sign-in: which backend endpoint to talk to, and the caller's API key for it.
|
Package credentials persists the assistant's sign-in: which backend endpoint to talk to, and the caller's API key for it. |
|
daemon
Package daemon drives all autonomous work in-process: a 3s scheduler tick fires due timers and runs due watchers (a terminal-supervision state machine and a deterministic PR poller), persisting everything to the store so the architecture survives restarts and performs sleep catch-up.
|
Package daemon drives all autonomous work in-process: a 3s scheduler tick fires due timers and runs due watchers (a terminal-supervision state machine and a deterministic PR poller), persisting everything to the store so the architecture survives restarts and performs sleep catch-up. |
|
debuglog
Package debuglog writes a per-session, append-only, human-readable trace.
|
Package debuglog writes a per-session, append-only, human-readable trace. |
|
deps
Package deps is a build-time anchor that blank-imports the third-party stack the Phase-C subsystems (UI, storage, MCP) will use, so `go mod tidy` keeps these modules pinned in go.mod/go.sum before any subsystem code imports them.
|
Package deps is a build-time anchor that blank-imports the third-party stack the Phase-C subsystems (UI, storage, MCP) will use, so `go mod tidy` keeps these modules pinned in go.mod/go.sum before any subsystem code imports them. |
|
domain
Package domain holds the pure, dependency-free domain vocabulary of the assistant: enums, persisted-record structs, the ToolResult envelope, ID and timestamp helpers, the event vocabulary, and JSON wire contracts.
|
Package domain holds the pure, dependency-free domain vocabulary of the assistant: enums, persisted-record structs, the ToolResult envelope, ID and timestamp helpers, the event vocabulary, and JSON wire contracts. |
|
host
Package host implements the embedded assistant-host protocol.
|
Package host implements the embedded assistant-host protocol. |
|
ipc
Package ipc is the local coordination layer for the persistent supervisor: flock-based ownership leases, the per-project control socket path, and the NDJSON request/response protocol the daemon serves on it.
|
Package ipc is the local coordination layer for the persistent supervisor: flock-based ownership leases, the per-project control socket path, and the NDJSON request/response protocol the daemon serves on it. |
|
mcp
Package mcp connects the assistant to Daintree's local MCP server and exposes a small, degradation-tolerant API.
|
Package mcp connects the assistant to Daintree's local MCP server and exposes a small, degradation-tolerant API. |
|
ports
Package ports defines the small interface seams that wire the subsystems together: EventSink (event fan-out) plus the core service interfaces the agent loop depends on (Store, Router, ToolRegistry, MCPClient, Queue).
|
Package ports defines the small interface seams that wire the subsystems together: EventSink (event fan-out) plus the core service interfaces the agent loop depends on (Store, Router, ToolRegistry, MCPClient, Queue). |
|
projectinstructions
Package projectinstructions loads a repo's DAINTREE.md instruction file.
|
Package projectinstructions loads a repo's DAINTREE.md instruction file. |
|
prompts
Package prompts holds MainPromptContext — the structured runtime/environment facts the CLI collects and hands to the agent session.
|
Package prompts holds MainPromptContext — the structured runtime/environment facts the CLI collects and hands to the agent session. |
|
queue
Package queue implements the attention queue: every sub-thread (timers, watchers, workflows, model workers) reports here instead of interrupting the main thread.
|
Package queue implements the attention queue: every sub-thread (timers, watchers, workflows, model workers) reports here instead of interrupting the main thread. |
|
redact
Package redact scrubs secret-looking values out of text on its way to somewhere it will persist: the debug log, the durable audit rows, the approval sheet, the cockpit's expanded activity rows.
|
Package redact scrubs secret-looking values out of text on its way to somewhere it will persist: the debug log, the durable audit rows, the approval sheet, the cockpit's expanded activity rows. |
|
safety
Package safety holds the tool-dispatch safety policy: tier gating, the always-confirm matrix, the HARD no-file-edit invariant, the read-only secret guards, and project-root path containment.
|
Package safety holds the tool-dispatch safety policy: tier gating, the always-confirm matrix, the HARD no-file-edit invariant, the read-only secret guards, and project-root path containment. |
|
storage
Package storage is the durable SQLite store of the assistant: timers, watchers, the attention-queue inbox (events), the tool-dispatch audit trail, per-run event logs, the conversation transcript, automation grants, the workflow ledger, agent-launch sagas, skill run state, and cross-session project memories (with an FTS5 recall index).
|
Package storage is the durable SQLite store of the assistant: timers, watchers, the attention-queue inbox (events), the tool-dispatch audit trail, per-run event logs, the conversation transcript, automation grants, the workflow ledger, agent-launch sagas, skill run state, and cross-session project memories (with an FTS5 recall index). |
|
supervisor
Package supervisor is the persistent per-project daemon: the process that keeps supervising Daintree work after the interactive cockpit closes.
|
Package supervisor is the persistent per-project daemon: the process that keeps supervising Daintree work after the interactive cockpit closes. |
|
terminal
Package terminal holds the TTY-gated raw escape sequences the cockpit writes straight to the host terminal, OUTSIDE Bubble Tea's managed render path.
|
Package terminal holds the TTY-gated raw escape sequences the cockpit writes straight to the host terminal, OUTSIDE Bubble Tea's managed render path. |
|
tools
Package tools is the tool-dispatch choke point.
|
Package tools is the tool-dispatch choke point. |
|
tools/agenttaskx
Package agenttaskx is the no-file-edit escape hatch: agentTask.spawnForEdits (risk "project").
|
Package agenttaskx is the no-file-edit escape hatch: agentTask.spawnForEdits (risk "project"). |
|
tools/artifactx
Package artifactx is the oversized-result paging tool family (artifact.read, risk "read").
|
Package artifactx is the oversized-result paging tool family (artifact.read, risk "read"). |
|
tools/asyncx
Package asyncx is the asynchronous-operations tool family: the model-facing surface of the runtime-owned durable futures in internal/asyncwork.
|
Package asyncx is the asynchronous-operations tool family: the model-facing surface of the runtime-owned durable futures in internal/asyncwork. |
|
tools/auditx
Package auditx is the audit-export tool family (audit.export, risk "read").
|
Package auditx is the audit-export tool family (audit.export, risk "read"). |
|
tools/contextx
Package contextx is the read-only orchestration-helper family: compact main-thread snapshots (context.snapshot) and cheap terminal reads/summaries (terminal.read VERBATIM, terminal.summarize via the small model).
|
Package contextx is the read-only orchestration-helper family: compact main-thread snapshots (context.snapshot) and cheap terminal reads/summaries (terminal.read VERBATIM, terminal.summarize via the small model). |
|
tools/extractionx
Package extractionx is the on-demand terminal-extraction family.
|
Package extractionx is the on-demand terminal-extraction family. |
|
tools/fsx
Package fsx is the read-only project-filesystem tool family (fs.list, fs.read, fs.search), all risk "read".
|
Package fsx is the read-only project-filesystem tool family (fs.list, fs.read, fs.search), all risk "read". |
|
tools/grant
Package grant holds the automation-grant tools: grant.create, grant.list, grant.revoke.
|
Package grant holds the automation-grant tools: grant.create, grant.list, grant.revoke. |
|
tools/mcpwrap
Package mcpwrap holds the typed Daintree-MCP wrapper tools: recipe, worktree, forge reads, git.getProjectPulse, focus, and the workflow MCP passthroughs.
|
Package mcpwrap holds the typed Daintree-MCP wrapper tools: recipe, worktree, forge reads, git.getProjectPulse, focus, and the workflow MCP passthroughs. |
|
tools/mcpx
Package mcpx is the Daintree MCP tool family: discovery (daintree.status, daintree.listTools, tool.search), the raw passthrough escape hatch (daintree.call), and the typed MCP wrappers — terminal focus/input/arming, agent focus, and copyTree.
|
Package mcpx is the Daintree MCP tool family: discovery (daintree.status, daintree.listTools, tool.search), the raw passthrough escape hatch (daintree.call), and the typed MCP wrappers — terminal focus/input/arming, agent focus, and copyTree. |
|
tools/memory
Package memory holds the cross-session project-memory tools: memory.recall, memory.list, memory.save, memory.forget, memory.pin, memory.unpin.
|
Package memory holds the cross-session project-memory tools: memory.recall, memory.list, memory.save, memory.forget, memory.pin, memory.unpin. |
|
tools/questionx
Package questionx holds user.askMultipleChoice — the one tool that lets the model ask the human a single, finite, multiple-choice question mid-turn and BLOCK on the answer.
|
Package questionx holds user.askMultipleChoice — the one tool that lets the model ask the human a single, finite, multiple-choice question mid-turn and BLOCK on the answer. |
|
tools/queue
Package queue holds the attention-queue tools: queue.publish, queue.digest, queue.resolve.
|
Package queue holds the attention-queue tools: queue.publish, queue.digest, queue.resolve. |
|
tools/scratchx
Package scratchx is the session-scoped scratch-pad tool family (scratch.create, scratch.set, scratch.get, scratch.delete, scratch.drop).
|
Package scratchx is the session-scoped scratch-pad tool family (scratch.create, scratch.set, scratch.get, scratch.delete, scratch.drop). |
|
tools/skill
Package skill holds the local skill RUN-STATE tools: skill.run.get and skill.step.advance.
|
Package skill holds the local skill RUN-STATE tools: skill.run.get and skill.step.advance. |
|
tools/terminalid
Package terminalid canonicalizes caller-supplied Daintree terminal ids against the live roster.
|
Package terminalid canonicalizes caller-supplied Daintree terminal ids against the live roster. |
|
tools/terminalobs
Package terminalobs is the session-scoped, cross-call terminal observation memory: which agent terminals this process has SEEN working, and when the assistant last injected input into each.
|
Package terminalobs is the session-scoped, cross-call terminal observation memory: which agent terminals this process has SEEN working, and when the assistant last injected input into each. |
|
tools/timer
Package timer holds the durable-timer tools: timer.schedule, timer.list, timer.cancel.
|
Package timer holds the durable-timer tools: timer.schedule, timer.list, timer.cancel. |
|
tools/watcher
Package watcher holds the terminal/PR watcher tools: watcher.terminal.create, watcher.watchPR, watcher.list, watcher.cancel.
|
Package watcher holds the terminal/PR watcher tools: watcher.terminal.create, watcher.watchPR, watcher.list, watcher.cancel. |
|
tools/workflow
Package workflow holds the workflow-ledger tools: workflow.create, workflow.get, workflow.list, workflow.update.
|
Package workflow holds the workflow-ledger tools: workflow.create, workflow.get, workflow.list, workflow.update. |
|
ui/composer
Package composer is the dedicated cockpit input editor: an explicit buffer/cursor/kill-ring/history model that satisfies the full key contract.
|
Package composer is the dedicated cockpit input editor: an explicit buffer/cursor/kill-ring/history model that satisfies the full key contract. |
|
ui/markdown
Package markdown is the cockpit's SYNCHRONOUS markdown renderer.
|
Package markdown is the cockpit's SYNCHRONOUS markdown renderer. |
|
ui/theme
Package theme owns the cockpit's visual vocabulary: the semantic color palette, the theme MODE (dark / light / ansi / none), the signature glyph set with ASCII fallbacks, and the green splash gradient.
|
Package theme owns the cockpit's visual vocabulary: the semantic color palette, the theme MODE (dark / light / ansi / none), the signature glyph set with ASCII fallbacks, and the green splash gradient. |
|
waitbudget
Package waitbudget is the per-turn cumulative foreground-wait allowance shared by every blocking wait a tool performs inside one user turn (today: terminal.awaitAll's poll sleeps).
|
Package waitbudget is the per-turn cumulative foreground-wait allowance shared by every blocking wait a tool performs inside one user turn (today: terminal.awaitAll's poll sleeps). |
|
workflowgraph
Package workflowgraph is the client-owned workflow-intelligence layer: a typed, durable, patchable execution graph (DAG) per user goal.
|
Package workflowgraph is the client-owned workflow-intelligence layer: a typed, durable, patchable execution graph (DAG) per user goal. |
Click to show internal directories.
Click to hide internal directories.