# dugix
[](https://crates.io/crates/dugix)
[](https://docs.rs/dugix)
[](LICENSE)
A local-first terminal chat app for deep research and multi-agent work. Rust +
[ratatui], all state on your machine — one SQLite db scoped by space, files and artifacts in
space directories, model-created web apps served from localhost.
## Install
```sh
cargo install dugix
```
This provides the `dugix` command. Requires Rust 1.91+ (edition 2024).
To run from a checkout instead:
```sh
cargo build --release
./target/release/dugix
```
### CLI
`dugix` with no arguments launches the TUI. Subcommands work headless
from the shell — everything they write (sessions, usage, reports) lands in
the same local state the TUI reads, so you can mix both freely:
```sh
dugix ask "summarize the EU AI Act in 5 bullets" # one-shot chat, streams to stdout
dugix ask --model deepseek/deepseek-v3 "..." # pick a model
cat brief.md | dugix ask "summarize this" # prompt from stdin
dugix ask --space new:research "..." # create-and-use a space
dugix ask --json --quiet "..." # structured output for scripting
dugix clip # explain text currently in the OS clipboard
dugix clip --copy "Explain this and list surprising facts" # browser-text shortcut
dugix chat # bare REPL, one session
dugix research "impact of EU AI Act on startups" # deep research (survey + plan gates)
dugix research --approve "..." # skip the gates, run unattended
dugix jobs list # agent and research jobs
dugix jobs run <id> # run a job now
dugix jobs run-due # run due jobs (cron-friendly)
dugix jobs daemon # schedule repeating jobs
dugix usage [--range 24h|7d|30d|all] [--by-day] # token/cache/cost analytics
dugix usage --json # same, machine-readable
dugix usage --session <id> [--json] # every request and session total
dugix sessions [--space <name>] [--json] # list sessions
dugix sessions rm <id|slug> # delete one session
dugix sessions prune --keep 20 --days 90 --dry-run # delete old sessions
dugix spaces [--json] # list spaces
dugix export <id|slug> # print a session's latest report + sources
dugix export <id> --transcript -o chat.md # the whole conversation
dugix backup [-o file.zip] # zip db + spaces + skills
dugix restore file.zip --yes # restore a backup (overwrites)
dugix memory [--space] [--edit] # print/edit a space's memory
dugix memory share <CHAPTER> (--with <SPACE>... | --all | --none) [--space <NAME>]
dugix memory shares [--space <NAME>] # list shared chapters
dugix instructions [--space] [--edit] # print/edit a space's instructions
dugix files [--space] # list imported files
dugix models [--backend openrouter] # fetch + list model catalogs
dugix login openrouter sk-... [--check] # save a provider key
dugix skills list # installed skills
dugix skills install owner/repo[/path] # install a skill from GitHub
dugix open <id|slug> # launch the TUI inside that session
dugix --continue # launch the TUI inside the latest session
dugix --selection-chat # analyze Linux primary selection, or continue
dugix update # update to the latest release (cargo install)
dugix status # paths, providers configured, db stats
dugix doctor [--network] # db integrity, config, tools
dugix host [--port 8643] # local HTTP/SSE daemon + gateway
dugix host --tunnel # reuse named tunnel, or quick tunnel + QR
dugix host --setup # provision a named tunnel with CF_API_TOKEN
```
`dugix ask`/`clip`/`chat`/`research` use your most recently used model (or
`--model`), run the same search/tool pipelines as the TUI, and save
conversations as normal sessions — tool status and token usage go to
stderr, answers to stdout. `clip` reads text through the OS clipboard
(Wayland or X11), applies its optional instruction, and uses a built-in
plain-language/facts prompt when no instruction is supplied. `--copy` puts
the answer back on the clipboard. `--selection-chat` is the interactive
Linux shortcut mode: it reads the primary selection without changing either
clipboard, submits a protected web-mode turn into the TUI, and behaves like
`--continue` when the selection is empty. A running TUI accepts later
selection requests over its per-user runtime socket, so the shortcut reuses
one instance. Bind it with a terminal command such as
`foot -e dugix --selection-chat`; use the equivalent `-e` option for your
terminal emulator. `research` without `--approve` parks at the
survey/plan checkpoints: interactive when stdin is a terminal, an error
otherwise (`--approve` runs unattended, like `/research!`). The read-only
commands (`usage`, `sessions`, `spaces`, `export`, `status`, `doctor`,
`backup`, `memory`, …) never touch the network.
### Golden-task evals
`dugix eval [DIR] [--model MODEL] [--filter SUBSTR] [--json]` runs the golden
TOML tasks in `./evals` against a real backend in incognito (no saved sessions).
It reports checks, tool calls, invalid-call rate, tokens and cost; exit status is
0 only when all selected tasks pass. This manual command requires keys/network
and costs real tokens; it is not part of CI. See [evals/README.md](evals/README.md)
for the task format and held-out-task policy.
### Hosting
`dugix host` runs the same core on a loopback HTTP/SSE daemon. It exposes
`/v1/snapshot`, `/v1/models`, `/v1/backends`, `/v1/events`,
`/v1/sessions/<id>/messages`, `/v1/command`, `/v1/sync`, hash-checked
`GET`/`PUT /v1/sync/blob`, `/v1/tools`, and an
OpenAI-compatible `/v1/chat/completions` gateway. `/v1/tools/run` uses a
JSON-RPC 2.0 envelope, for example
`{"jsonrpc":"2.0","id":1,"method":"tools/run","params":{"name":"read_file","arguments":{...}}}`.
Devices must run the same dugix version to sync.
Sync clients POST metadata first, then upload/download each manifest blob by
`space_id`, `name`, and `hash`. The host token is generated once and stored in
`config.toml` (see [Configuration](#configuration)) as `[provider].host_token`; provider API
keys remain on the machine and are never sent to clients.
```sh
dugix host --port 8643
curl -H "Authorization: Bearer <host-token>" http://127.0.0.1:8643/v1/snapshot
dugix host --tunnel # requires cloudflared
CF_API_TOKEN=… dugix host --setup # creates/reuses named tunnel + DNS CNAME
# non-interactive setup can also set CF_ACCOUNT_ID, CF_ZONE_ID,
# CF_HOSTNAME, and CF_TUNNEL_NAME
```
The command prints an enrollment URI and an ASCII QR code. Public app links
use `/apps/<uuid>/`; the registry UUID is the app capability and the host
bearer token is never embedded in the URL or an app cookie. `/v1/models`
returns an OpenAI-compatible `data` list with backend-qualified ids such as
`openrouter:anthropic/…`. Codex is routed too: the gateway translates the
chat-completions request into a native Responses call and re-emits the
Responses event stream as `chat.completion.chunk` frames, so every listed
backend is reachable through one OpenAI-wire endpoint. Named tunnel setup is persisted and reused by later
`dugix host --tunnel` runs when its local cloudflared files still exist.
`--no-sleep-guard` disables `caffeinate`/`systemd-inhibit` if desired.
For optional per-user startup, use `dugix host --install-service` (or
`--uninstall-service`); it writes a systemd user unit on Linux or a launchd
agent on macOS and prints the activation command.
### Requirements
- Rust 1.91+ (only needed to build/install — no runtime dependency)
- A modern terminal (truecolor recommended)
- Extra tooling, all optional:
- `poppler` (`pdftoppm`) — render PDF pages for the model to view
- `ffmpeg` — video transforms for `media`; with `ffprobe` and a local
`whisper`, audio/video files get metadata and transcripts
- `pandoc`, `libreoffice` (`soffice`), `antiword`/`catdoc` — richer reads of
markup and legacy office files (docx, odt, epub, rtf, org, rst, … work
without them; `.doc`/`.xls`/`.ppt`/`.key` need one of these)
- `ollama` — local embeddings
Files are read by content, not extension: HTML becomes clean Markdown, PDFs,
office/ODF/EPUB, RTF, mail, notebooks, subtitles and CSV are converted, and a
binary nothing can read is indexed by name and metadata only (never as text).
Add your own converter per extension or MIME type in `config.toml`:
```toml
[extract.converters]
"key" = ["keynote2md", "{in}"] # stdout is Markdown
```
### Configuration
Keys come from the config file or env (`OPENROUTER_API_KEY`,
`OPENAI_API_KEY`, `OPENCODE_API_KEY`, `MISTRAL_API_KEY`), or `/login` in-app. On
first launch a key is enough; models are fetched from the catalogs.
**Mistral Vibe plan.** Create a key under *Code > Vibe CLI* in Le Chat and pick
*Mistral Vibe* in `/login` (or `dugix login mistral <key>`). The plan's budget
meters the Vibe CLI's model names, `mistral-vibe-cli-latest` (the main coding
model) and `mistral-vibe-cli-fast` (a faster, lighter one); they're listed under
`mistral:` alongside the rest of Mistral's tool-calling catalog. Other models
bill as pay-as-you-go on the same key. A console key works the same way.
| What | macOS | Linux |
|---|---|---|
| credentials & settings | `~/Library/Application Support/dugix/config.toml` | `~/.config/dugix/config.toml` |
| system prompt overrides | `…/dugix/system_prompt.md` (same folder) | `~/.config/dugix/system_prompt.md` |
| custom banner | `…/dugix/banner.txt` (same folder) | `~/.config/dugix/banner.txt` |
| database (`dugix.db`, `cache.db`) | `~/Library/Application Support/dugix/` | `~/.local/share/dugix/` |
| spaces (files, scripts, apps, media) | `…/dugix/spaces/<space>/` | `~/.local/share/dugix/spaces/<space>/` |
`dugix status` prints the folders this machine uses.
### Web search: zero setup
`search` works without a search key or instance URL. In `auto` mode it tries
LangSearch (if a key is set), SearXNG (if a URL is set), public keyless Exa,
the session backend's built-in search, DuckDuckGo, then Brave, continuing past
errors and empty results. `/config` also offers explicit `exa` and `provider`
choices; the LangSearch key and SearXNG URL are optional extras.
The provider fallback uses your session's own model and backend.
OpenRouter web search costs **$0.007 per request plus model tokens**; reported
usage/cost is recorded with other background calls. Codex uses your ChatGPT
subscription; OpenAI Responses web search is billed at OpenAI's search/tool
and token rates. OpenCode Go, Mistral and local runtimes have no built-in
search and are skipped. Exa has no recency filter: when requested, the result header says
it was not applied. HTML scrapers remain last-resort fallbacks and may return
bot challenges.
Background jobs (titles, compaction, the approval judge) run on the session's
own model.
## Local inference (experimental)
Pick a runtime from inside the TUI with `/local` (also the last row of
`/login`), or name one directly: `/ollama`, `/llama-cpp`, `/mlx`, `/mlx-serve`,
`/lmstudio`, `/edge0`, `/local mlx-serve http://localhost:11234/v1`, `/local off`. Either way the choice is
written to `config.toml` and the catalog reloads
immediately — no restart.
The same block can be written by hand:
```toml
[local]
provider = "ollama" # or "llama_cpp", "mlx", "mlx_serve", "lmstudio", "edge0"
# endpoint = "http://localhost:11434/v1" # optional inference URL override
# context_length = 32768 # Ollama default; minimum 2048 tokens
# kv_cache_q8 = true # optional Ollama/llama.cpp KV-cache quantization; default false
# parallel_tool_calls = false # enable only if the local model supports parallel calls
# tier = "small" # small (default), medium, or large; small uses compact tool definitions
```
`context_length` is reported for every model discovered through this runtime,
enabling automatic compaction. Ollama defaults to 32,768 tokens; Dugix passes
that window as `OLLAMA_CONTEXT_LENGTH` when starting its server, and passes a
set `context_length` to llama.cpp as `--ctx-size` (unset, llama.cpp uses each
model's own window). Other runtimes have no assumed window: set this key to
their actual server context size. It does not resize mlx-lm, mlx-serve, LM
Studio or edge0 servers.
For Ollama, `kv_cache_q8 = true` enables `OLLAMA_KV_CACHE_TYPE=q8_0` and
`OLLAMA_FLASH_ATTENTION=1`, roughly halving KV-cache memory compared with the
default f16 cache for long contexts; for llama.cpp it passes `--cache-type-k
q8_0 --cache-type-v q8_0 --flash-attn on`. Other runtimes ignore this launch
option.
Use `/local restart` to apply launch settings to a managed server; configure
servers started elsewhere yourself so their window matches this setting.
Local chat requests no parallel tool calls and uses compact tool definitions
by default. Set `parallel_tool_calls = true` to allow parallel calls, or `tier = "medium"`
(or `"large"`) to use full definitions. Tool results in local chat history are
head-and-tail capped to one eighth of the context window (2,000–8,000
characters; 4,000 if unknown); stored results and hosted requests are unchanged.
Dugix warns once per frozen prompt prefix if the system prompt plus tool
definitions alone use more than half the known context window. The estimate is
advisory and never blocks a request.
Switching runtimes from `/local` drops a custom `endpoint`/`list_command` and
context/KV-cache and model-profile settings, since those are written for one
runtime; re-selecting the active runtime keeps them.
Dugix runs the runtime's discovery command when loading/refreshing `/model`:
| Runtime | Discovery | Default inference URL |
| --- | --- | --- |
| `ollama` | `ollama list` | `http://localhost:11434/v1` |
| `llama_cpp` | `llama-server --cache-list` | `http://localhost:9931/v1` |
| `lmstudio` | `lms ls --json` | `http://localhost:1234/v1` |
| `mlx` (mlx-lm) | `python3` running a bundled, offline Hugging Face cache scanner | `http://localhost:8080/v1` |
| `mlx_serve` | `mlx-serve list` | `http://localhost:11234/v1` |
| `edge0` | `edge0 models` | `http://localhost:8000/v1` |
These are **installed models**, not an online download catalog. llama.cpp
lists the GGUF models in its cache (download one with `llama-server -hf
<user>/<repo>:<quant>` or `llama-cli -hf …`); `/local start` runs
`llama-server` in router mode, which serves every cached model and loads the
one a request names on demand, with CORS limited to the server's own origin. The legacy
`mlx` runtime uses mlx-lm, which has no list command: the scanner lists cached
repositories with `config.json` and safetensors weights, respecting
`HF_HOME`/`HF_HUB_CACHE`. These are candidates, not a guarantee of MLX
compatibility or a complete download. The separate `mlx-serve` runtime reads
its own `~/.mlx-serve/models` catalog; entries marked `unsupported` (such as
an incomplete download) are not offered in `/model`. Pull models with
`mlx-serve pull <org/repo>` before selecting them. `edge0 models`
lists the tiers its registry knows (`edge0-35b`, `edge0-8b`) — likewise
candidates: the checkpoint itself is located by the server through
`EDGE0_<TIER>_MODEL`, and serving a checkpoint directory instead names the
tier it auto-detects.
Local models have their own **Local** backend filter and `local:` IDs; names also
show the runtime. OpenAI and other cloud backends remain independent. Only one
local runtime is configured at a time. No cloud credentials are sent locally.
For a custom installation, override discovery with an argv array. Its output
must be one inference model ID per line (no header):
```toml
[local]
provider = "mlx"
list_command = ["/absolute/path/to/my-model-list", "--installed"]
```
Commands run without a shell, with a 15-second timeout and 1 MiB stdout cap.
Only put trusted commands in this machine-local config; discovery executes them
automatically. Configuring a different inference endpoint does not change where
the discovery command looks—configure that command/runtime accordingly.
### Managed servers
Inference needs a server running behind the endpoint. Dugix can start one for
you and tell you what it costs:
| Command | What it does |
| --- | --- |
| `/local start [runtime]` | start that runtime's server (`/serve` is the same command) |
| `/local stop [runtime]` | stop a server **Dugix started** |
| `/local restart [runtime]` | stop then start, to pick up a new model |
| `/local status` | probe every runtime: which answer, what they cost, what is over budget |
Omit the runtime to act on the selected one, or name it — `/local stop edge0`
and `/edge0 stop` are the same command. The `/local` picker shows the same
survey live, with `s` start, `x` stop, `r` refresh on the row under the cursor.
What gets launched:
| Runtime | Server command | Needs a model |
| --- | --- | --- |
| `ollama` | `ollama serve` (with `OLLAMA_HOST` and `OLLAMA_CONTEXT_LENGTH`) | no — loads on demand |
| `lmstudio` | `lms server start` (a daemon, stopped with `lms server stop`) | no |
| `mlx` (mlx-lm) | `mlx_lm.server --model <selected>` | yes |
| `mlx_serve` | `mlx-serve serve --host 127.0.0.1 --port 11234` | no — loads on demand |
| `edge0` | `edge0 serve <selected>` | yes |
mlx-lm and edge0 serve exactly one model, taken from your `/model` selection at
launch — switching models in Dugix does not restart them, so use
`/local restart`. Ollama, mlx-serve and LM Studio load models through their own API.
If `mlx-serve run <model>` is already serving on port 11234, Dugix can use it
without taking ownership; `mlx-serve serve` is the managed, on-demand mode.
**Ownership is explicit.** A server Dugix started is stopped by `/local stop`
and when Dugix exits, so quitting never strands a multi-gigabyte process. A
server already answering on the endpoint — one you started in another terminal,
or a system service — is detected and used, but never stopped by Dugix.
**Memory is advisory.** `/local status` reports the resident memory of the
listener's whole process tree, which is what you want: Ollama's weights live in
a `runner` child, not the server that holds the port. Going over budget warns
on the status line and marks the row; it never kills a server, so a reply that
is mid-generation is never yanked. The budget defaults to 70% of physical
memory and is configurable:
```toml
[local]
provider = "edge0"
memory_budget_mb = 8000 # optional; default is 70% of physical RAM
```
Reading memory needs `ps`, and `lsof` for servers Dugix did not start; without
them liveness still works and the size column is simply blank.
The server's API must accept the discovered model ID. Model downloads,
authenticated local servers, host gateway forwarding, and automatic capability/context
discovery are not implemented yet. Tool calling depends on the runtime/model.
Local utility fallback uses the selected/installed model rather than a cloud
model name.
### Local embeddings
Semantic file search can run entirely on your machine with Google's
EmbeddingGemma 2 through Ollama. File text and images never leave the
machine when you choose it.
```sh
brew install ollama
ollama serve # or let the Ollama app run it
ollama pull embeddinggemma-2:270m # text only (~270M parameters)
# or, to search images too:
ollama pull embeddinggemma-2 # multimodal tag
```
**Selecting it.** There is no embedding setting; the choice is automatic. If
Ollama answers on `http://127.0.0.1:11434` (or the endpoint in `[local]` when
the runtime is Ollama) and has one of those two tags installed, Dugix uses it
(`embeddinggemma-2:270m` is preferred). Otherwise it uses the signed-in
backend's own embedding model (OpenRouter uses `google/gemini-embedding-2` to
embed text and image files directly; OpenAI uses text-only `text-embedding-3-small`),
and where the backend has none (Codex, OpenCode Go, Mistral) search is keyword-only. `/files` shows
which. A `local:` choice never falls back to a cloud embedder; if Ollama is
down, search degrades to keywords with the reason, and `/files` shows
`embeddings: not reachable — is `ollama serve` running?`.
**What is embedded.** Text, code, PDFs and office documents are embedded from
the text Dugix already extracts, in windows of at most about 1,000 tokens
(estimated conservatively, with overlap) using the model's own prefixes
(`task: search result | query: …` for queries, `title: … | text: …` for
documents). When the runtime reports image support, image files are embedded
directly (downscaled to at most 768 px, up to 20 MiB) and returned by
`files search` as `image · name · score` hits the model can look at. Audio and
video are not embedded yet.
With an image-capable embedder, images and up to 30 pages of a scanned PDF
are embedded as images, so search finds them by content. The model views any
imported PDF page with `files(action=pdf_page)`, rendered on demand using
poppler's `pdftoppm`.
**Switching and updating.** Each vector records the model's identity: backend,
model, weights digest, dimension, prefix scheme and preprocessing version.
Anything that changes it (a new `ollama pull`, switching models, a different
endpoint) re-embeds a space lazily in the background, one file at a time, with
progress on the first line of `/files`; stale vectors are never mixed in.
### Searching past chats
When someone refers to an earlier conversation, the model uses
`search(mode=chats, query=...)`. It merges keyword and semantic rankings, skips
the current chat, and only looks in the active space (another space's chats stay
out of reach, even by id). Each hit has the chat's title, date, role, a snippet
and a `chat:<session>#<message>` URL; `fetch_url` on that URL reads the
conversation, starting two messages ahead of the hit, paged by line like any
other page. Tool calls and results show as one line each.
Only persisted user and assistant **content** is indexed: no tool results,
system text or reasoning. Incognito conversations are never persisted or indexed.
Synced-in messages are indexed on this device too. The rebuildable FTS5 keyword
index and identity-keyed message/chunk vectors live only in the device-local
`cache.db`, not in the durable or synced schema. Deleting messages or sessions
removes their cached index rows.
Chats share exactly the file embedder described above: local EmbeddingGemma 2
when available, otherwise the active backend's default, otherwise keywords only.
Chat text never falls back to cloud embeddings when files use a local embedder.
History backfills newest first, behind files, in bounded background batches;
`/files` shows `chats: N of M indexed`. An identity change re-embeds lazily.
Chat search is available in chat and agent mode, never in research searcher toolboxes.
## Features
- **Chat** over any configured backend: OpenRouter, OpenAI, OpenCode Zen/Go,
Codex, and Mistral (Vibe plan) — one merged model list, per-model reasoning-effort control
- **Deep research** (`/research <topic>`): a conversational scoping survey →
a plan of questions with why/angles/sources briefs → parallel searcher
agents → synthesis → critic → verifier → writer, with a live activity view
and `/steer` mid-run. `/research! <topic>` runs ungated. Both create a one-off
research job listed in `/jobs`; press `r` there to run it again. The finished report
is saved as `research-<topic>-<time>.md` in the space files and as a doc in
the **Library**, so it opens in studio to edit, comment on and export
- **Swarm** (`/swarm`): several agents answer each message independently
(read-only, with tools), a reviewer checks their claims, and a writer replies
from what held up, keeping a minority view the others missed. Every agent is a
sub-agent run in `/agents`; the roster sets each drafter's focus and model
(three plain drafts on the session model without one)
- **Watches** (`/watch <topic>`): research jobs that start immediately and repeat daily
through `dugix jobs daemon` (or `dugix jobs run-due` from cron). `/watch` opens
`/jobs`, where `w` toggles a research job between one-off and daily repeats
- **Spaces**: per-project context (instructions, memory, imported files,
scripts, apps) with embeddings-backed semantic file search
- **Memory**: a book per space — chapters of short facts the model saves with
its `memory` tool, behind a table of contents in every chat; pinned chapters
are listed in full, and matching chapters and docs are named on the message
they relate to. `/memory` edits it in `$EDITOR`, `/memory tidy` asks the chat
model to review and clean the memory with its own tool, in the conversation.
Chapters are private by default. `/memory share <chapter> with all|none|<space>[, <space>…]`
shares a chapter with all or chosen spaces, or makes it private again; `/memory share`
lists both directions. Shared chapters show their home space, and the model can read
and edit their facts from any recipient space. You can also just ask in chat — "share
About you with every space", "merge my About you chapters": the model's `memory` tool
lists every space's chapters (`spaces`), can `share` a chapter with chosen spaces, all
of them or none, and can `merge` same-titled chapters from every space into one shared
chapter — only when you ask, and only once you have more than one space. The editor
still edits only the current space's own chapters. Memory lives in `dugix.db` and syncs
- **Skills**: Agent Skills-compatible instruction packs (`SKILL.md`) with
progressive disclosure, project/user/global discovery, bundled resources,
sandboxed Python virtualenvs, and chat installation
- **Tools for the model**: nine consolidated tools — `search` (web/academic/
discussion), `fetch_url` (with PDF/YouTube extraction), `batch` (multi-op
calls), `research_lookup`, `files`, `app` (build & edit web apps served on
`http://localhost:8642`; `init` scaffolds Astro+React / Vite+React
starters, `build` compiles them with the framework's static build), `scripts`, `skills`, and `media` (image/video
generation with ffmpeg transforms)
- **Usage analytics**: `/usage` shows token/cache/cost analytics by backend
and model, priced from a synced catalog
- **Terminal ergonomics**: markdown rendering, image display, site icons
beside links (real icons with Kitty graphics, such as Ghostty; a colored
letter elsewhere; off with remote images), @-file autocomplete, mouse
selection → copy, context breakdown, compaction, incognito mode,
per-session history
### Diagrams in the terminal
Assistant replies with a `mermaid` fence get an inline preview for flowcharts,
sequence diagrams and state diagrams. For example, ask for a diagram using
`flowchart LR; Input --> Process --> Output`. Rendering happens locally without
Node or a browser. Supported terminals use Kitty/iTerm2/Sixel graphics; other
terminals fall back to colored half-blocks.
The source stays visible below the preview; long-press anywhere in the block to
copy it. Incomplete, unsupported or oversized diagrams keep their source, with
a preview error when appropriate. Previews use fixed-height slots so finishing
one does not move the conversation. Script-output publishing and interactive
web-app previews are not part of this first TUI-only slice.
### Interactive replies
Ask the model naturally—for example, “Let's play rock-paper-scissors with a
terminal UI,” “Quiz me,” or “Give me an interactive calculator.” The TUI advertises
its capabilities and asks models to prefer interactive output when useful and
representable. There are no game-specific commands or built-in game rules.
A model-authored `dugix-ui` fence uses a native Rust, OpenUI-style component
language—not a JSON tree. A root-first layout fills in as named elements and
even unfinished text stream in:
```dugix-ui
root = Panel("Your next adventure", [heading, highlights, next])
heading = Hero("A little further from ordinary", "Three days. A fresh perspective.", "WEEKEND EDIT")
highlights = Stats([Stat("3", "days away"), Stat("2", "new places"), Stat("1", "great escape")])
next = Buttons([Button("Help me plan the trip", @Answer())])
```
The themed panel supports buttons, optional ASCII artwork, editable string
fields and local state/actions. Existing JSON panels remain readable. This is a
bounded terminal dialect, not the full web OpenUI runtime.
For practice and interview sets (“Give me five Python interview questions”) a
`Quiz` pages through questions one at a time. Each question can hold a
highlighted code `Editor` with line numbers (Enter to edit, Esc to stop, Tab
indents), a `Choice` list that marks right and wrong once you pick, and an
answer you reveal on request. “Grade my answers” sends everything, code
included, for review.
A `Canvas` draws circles, boxes, lines, rays, polygons and labels in braille
dots on a 0–100 grid, and `Anim` keyframes move them: a spinning clock hand, a
bouncing ball, an orbit diagram. Animations run at about 15 frames a second
only while the canvas is on screen and the terminal has focus; shapes can also
follow panel state, so a slider can drive a drawing.
Panels use quiet sentence-case headings, compact result values and slim slider
tracks. Related actions stay together in reading and keyboard order; the model
gets working calculator, quiz and planner examples rather than a dashboard recipe.
Panels are laid out with `Row`, `Grid` and `Stack`, which stack on narrow
terminals. Bars and meters glide to new values, and charts draw in the first
time a panel appears; `/motion off` turns all panel motion off (canvases then
hold their first frame) and `/motion on` brings it back.
Panels can also run on their own: `@Every` timers, `@Keys` bindings for the
arrows, space, letters and digits, and clickable canvas shapes make small
games, timers and simulations possible. Timers and keys can only change the
panel's own state; sending anything still takes a real button press.
More components: `Number` (one big headline figure), `Gauge`, `Heatmap`,
`Md` (Markdown text), `Tree` (an expandable outline), `Board` (kanban lanes
that can follow a list in panel state) and `Diagram` (Mermaid, drawn as an
image where the terminal supports it).
Click controls directly, or press `F2` to focus the newest visible panel and use
Tab/arrows + Enter (inside a text field, arrows move the caret). `Esc` returns to chat without changing your draft; `Ctrl+C`
copies a field's selected text, or returns to chat when nothing is selected.
Text fields have rounded borders, persistent labels, placeholders and inline
help/errors. Click to place the caret, drag or Shift+arrows to select, use
Home/End or Ctrl/Alt+arrows to navigate, and Ctrl+A/Z/Y to select all/undo/redo.
Tab/Shift+Tab move between controls; PageUp/PageDown scroll the chat except inside a
textarea. `Input` is single-line (Enter advances);
`Textarea` is soft-wrapped prose (Enter inserts a newline), distinct from the code editor:
```dugix-ui
root = Panel("Contact", [email, notes, save])
$email = ""
$notes = ""
email = Input($email, "Email", {required: true, email: true}, "you@example.com")
notes = Textarea($notes, "What do you need?", 4, "Describe your goal", null, "Include any constraints")
save = Buttons([Button("Review message", @ToAssistant("Contact request"), true)])
```
New panels display progressively but activate only when the reply finishes.
Text reflows at the available width; streamed previews never execute actions.
Validation happens automatically, with no preflight tool call.
Local actions make no model calls. Buttons that propose a response are marked
`[review]`: they prepare text in an empty composer for you to inspect/edit and
press Enter to send. They never overwrite a draft or run slash commands unseen.
Panel state is saved with its conversation outside incognito. `/pin-panel [name]`
keeps a panel as a reusable mini-app; reopen it from `/apps`. There is no separate
scripted terminal-app runtime. Original source remains copyable by long-pressing
non-control text/borders; invalid or unsupported definitions retain a source fallback.
This is a bounded declarative renderer, not an HTML/JavaScript/script runtime.
See the [model-facing schema](crates/core/assets/prompts/interactive-ui.md) for supported
controls and expressions. Complex applications may still need scripts or `/apps`;
the web client and inline web-app previews remain unchanged.
### Documents and presentations
The model uses `canvas` to draft Markdown documents (`docs/*.doc.json`) and
presentations (`decks/*.deck.json`). Both copy the space's default design;
slides can use named layouts. Documents support block edits, anchored comments,
suggestions, history and export to DOCX, PDF, Markdown and HTML. `/studio` opens
the doc or deck studio showed last in the studio window (`/studio docs/q3.doc.json`
names one, and `dugix-studio docs/q3.doc.json` opens it standalone); with no file
yet it opens the library. A doc opens as a
calm writing page: an outline on the left, comments in the margin, formatting
over selected text, `/` for blocks, tracked-change suggestions from the model,
a page preview and an export menu. Older `deck` tool calls remain supported as
an alias.
Find your decks and docs in the **Library**: studio opens on it when it starts
with no file (and from the **Library** button or Cmd/Ctrl+O), as a grid of cards
with thumbnails, filters and search, and a menu to open, reveal, duplicate, rename,
export or delete (a delete moves the file to `.trash/` in the space files). In the
terminal, `/library` lists the same files (Enter opens one in studio, `e` exports
it, `d` deletes it after a confirm) and `dugix library [--kind deck|doc] [--json]`
prints them. Open…, Export…, Save a copy… and Add template… use the system's own
file dialogs, so you choose where files go: Export starts in the folder you last
exported to, and "Save to exports/ without asking" keeps the old one-click export
into `exports/`.
Add a company template with **Design → Add template…** in studio, or drop a
`.pptx`, `.potx`, `.docx` or `.dotx` onto the window, then choose **Use for this
doc/deck**. From the CLI: `dugix design import brand.potx --name Corporate`,
then `dugix design list`. A file already uploaded to `/files` can be imported
with `canvas {action:"design", op:"import", from:"brand.potx"}`. Use its slug
with `create {design:"corporate"}` or `apply_design`. Templates are retained in
`templates/`, with extracted tokens, styles and slide layouts under `design/`.
PowerPoint and Word exports reuse the matching source package by default;
choose **Plain file**, `--template none`, or `export {template:"none"}` to opt
out. Macro-enabled files are refused. Unsupported preview details are reported
as warnings; the original masters, styles, headers and footers remain in exports.
## Commands
Type `/` in the composer for autocomplete. Aliases in parentheses.
| Command | What it does |
|---|---|
| `/new` (`chat`, `clear`) | start a new session |
| `/session` (`history`, `resume`, `switch`) | browse/switch sessions |
| `/space` (`project`, `workspace`) | switch spaces |
| `/model` (`llm`) | pick a model, set reasoning effort |
| `/login` (`key`) | log into a backend |
| `/research <topic>` | create and run a one-off research job, listed in `/jobs` |
| `/research! <topic>` | same, no survey/approval gates |
| `/watch [topic]` | create and run a daily research job; blank opens `/jobs` (`w` toggles daily) |
| `/swarm` (`panel`) | independent drafts, checked, then one reply; roster of drafters |
| `/files` (`images`, `scripts`, …) | browse space files / images / scripts; `Ctrl+N` imports through the system Open panel, `/` finds files on this machine (Spotlight on macOS, `~/` for a path), and files dropped on it import at once |
| `/apps` (`webapps`) | view web apps and pinned interactive panels |
| `/pin-panel [name]` (`pin`) | keep the focused panel as a reusable mini-app |
| `/studio [file]` (`deck`, `slides`) | open the last doc or deck (or the named one) in the studio window linked to this conversation; with none yet, open the library |
| `/agents` (`subagents`) | this conversation's `task` sub-agents: status, model, steps, tokens and cost; Enter opens a run's transcript (prompt, reasoning, tool calls, answer, review diff), live while it runs (`t` tool bodies, `r` reasoning, ←→ other runs). Ctrl+↑ opens it while the chat has sub-agents. The reply's cost includes its sub-agents. A task started with `background: true` keeps working after the reply ends: the model collects it with `agents` wait (or lists/stops it), and a report nobody collected comes back as a message when the conversation is idle. `proc` wait blocks on a background command until a line appears or it exits, instead of polling |
| `/fleet` (`herd`) | run Claude Code, Codex, pi or OpenCode inside Dugix. `/fleet` opens the board; `n` (or an empty board) opens the new-agent form: ←→ picks the agent, type a job or leave it empty, ↓ moves to an optional model field (in that CLI's own naming), Ctrl+T switches between its own worktree and your tree, and Enter starts it and opens it full-window — you type straight into the agent, Shift+PgUp scrolls back, Ctrl+] returns to the board. In a git repository each agent works on its own branch in a worktree under `.dugix/worktrees` (cargo builds share `.dugix/target`), so several can edit at once without touching your files; there each starts in its CLI's supervised auto mode (Claude `--permission-mode auto`, Codex `--sandbox workspace-write --approve-for-me`, OpenCode `--auto`; pi has no permissions) so it works without stopping to ask, while an agent in your own tree keeps asking. The board shows who is working, idle, exited, or blocked on a permission prompt (those sort first, and the status line says so), with each agent's branch, what it changed and its last check; Enter reopens an agent, `s` sends a follow-up without opening it, `d` reviews its diff, `c` runs the project's check in its worktree (`scripts/check.sh`, `make check`/`test`, `npm test`, `cargo test`, `go test` or pytest, whichever the project has), `m` merges its changes into your tree staged for you to commit (lines your own commits also changed get conflict markers to resolve; uncommitted edits to the same files must be committed or stashed first), and Ctrl+D twice stops it — unmerged work stays on its branch. The review screen has Diff and Check tabs (Tab switches, `c` checks, `m` merges, `r` reloads). Agents use their own logins and permissions and stop when Dugix exits. In agent mode the model can run a fleet too with the `fleet` tool: it splits a task into jobs, starts an agent per job (one approval covers the batch), waits (holding while you answer a blocked agent in `/fleet`), reads each diff, runs the check, sends fixes back, and tells you which are ready — merging stays yours, and it cannot answer an agent's permission prompts. `/fleet <agent> [job]`, `/fleet send <n> <text>`, `/fleet check <n>`, `/fleet merge <n>` and `/fleet stop <n>` remain as shortcuts |
| `/queue [send \| edit [n] \| drop <n> \| clear]` (`queued`) | messages you sent while a reply was still being written. They wait above the composer and go out one by one as each reply finishes; `↑` on an empty composer takes the newest back for editing. Stopping a reply (Esc) or an error holds the rest until you press Enter on an empty composer or send something new (which goes behind them). A background agent's report arrives through the same queue |
| `/library` (`decks`, `lib`) | list the space's decks and docs: Enter opens in studio, `e` exports through the Save dialog, `d` deletes (to `.trash/`) |
| `/skills` | manage skills (app + project/user/global Agent Skills) |
| `/usage` (`analytics`, `costs`) | token/cache/cost analytics by backend & model, with both the share served from cache and the share reused (of what the provider had already seen), plus why requests missed (←/→ for 24h/7d/30d/all windows) |
| `/compact` (`summarize`) | summarize old messages into a digest |
| `/refresh` | rebuild this chat's frozen prompt (memory, files, skills, tools) at the cost of one cache miss; a chat otherwise keeps its prompt prefix byte-identical for provider prompt caching, and `prompt frozen · …` says when something changed since |
| `/memory` (`remember`) | edit this space's memory in `$EDITOR`; `/memory tidy` asks the chat model to review and clean the memory with its own tool, in the conversation |
| `/config` (`settings`, `stats`) | settings, footer toggles, sampling params |
| `/export` (`save-report`) | write the research report + sources to a file |
| `/incognito` | toggle no-persistence mode |
| `/help` (`keys`, `shortcuts`; also `F1`) | keybinding + command reference |
| `/quit` | quit |
| `<skill-name>` | arm a skill for the next message |
## Keybindings
| Keys | Action |
|---|---|
| `Enter` | send (Shift/Ctrl+Enter inserts a newline) |
| `Esc` | stop the streaming response / clear the composer |
| `Ctrl+C` | close popup / stop stream / clear composer; press twice to quit |
| `Ctrl+V` | paste (bracketed paste) |
| `Ctrl+Shift+C` / `Ctrl+X` | copy / cut composer selection |
| `Ctrl+A` | select all in composer |
| `Ctrl+Backspace` | delete previous word |
| `Alt+↑` / `Alt+↓` | recall messages you sent this session |
| `Alt+1`–`Alt+4` | reopen a recent session from the start screen |
| `Ctrl+R` | expand/collapse reasoning traces |
| `Ctrl+T` | expand/collapse tool-call detail blocks |
| `Ctrl+G` | context breakdown (system/memory/skills/tools/conversation), plus the session's total cost, requests and tokens |
| `Ctrl+N` | start a new regular session |
| `Ctrl+Shift+N` | start a new incognito session |
| `Ctrl+O` | open a session-link message under the selection |
| `Ctrl+↑` | live research activity view (Ctrl+X there stops the job) |
| `PageUp` / `PageDown` | scroll a page |
| `Ctrl+Home` / `Ctrl+End` | jump to the start / latest message |
| `F1` | keybinding + command reference |
| mouse drag | select + copy |
While a research survey or plan approval is pending, Enter in that session
answers the gate; a reply with edits is folded in once by the approval agent.
### Vim keys and syntax colors
Every text input edits with vim keys: the composer, dugix-ui `Input` and
`Textarea` fields, and code `Editor`s. They are on by default; `/vim off`
switches to the plain keys above, and `/vim on` brings vim back.
- **Modes:** each input starts in Insert mode, so typing works as usual.
`Esc` switches to Normal mode, and a second `Esc` does what `Esc` does
without vim (stop the reply, clear the composer, leave a panel). In Normal
mode, `Enter` sends.
- **Keys:**
- motions: `h j k l`, `w b e`, `W B E`, `0 ^ $`, `gg G`, `{ }`;
- inserting: `i a I A o O`;
- operators `d c y` over any motion, and `dd cc yy`;
- editing: `x X D C s S Y`, `p P`, `J`, `r`, `~`;
- selecting: `v` / `V`;
- undo and redo: `u`, `Ctrl+R`;
- counts, and `.` to repeat the last change.
- **Mode display:** the composer's border shows the mode, and a panel's hint
line does the same for its fields.
Code is colored by tree-sitter in Bash, C, C++, CSS, Go, HTML, Java,
JavaScript, JSON, Markdown, Python, Ruby, Rust, TOML, TypeScript/TSX and
YAML. That covers code blocks in replies and file reads, the composer while
you type (Markdown, with each fenced block in its own language, and `!`
commands as Bash), and dugix-ui fields. In studio docs, code blocks take
the design's palette in the editor, page previews, PDF, HTML and DOCX. A
doc's **Markdown source** view (⇧⌘M, or More › Markdown source) edits the
whole document as Markdown with the same vim keys and colors. Its "vim on"
toggle is remembered per device. Edits apply after a pause, each one as a
single undo step.
## Architecture
Two-crate workspace: the engine and the terminal frontend.
```
crates/core/ dugix-core (lib crate `dugix_core`) — domain only, zero TUI deps; drives TUI + CLI + the future host API
├── src/app/ the state machine (one module per feature)
│ ├── mod.rs App struct (domain fields only), gates, commands, boot, snapshot, event stream
│ ├── commands.rs AppCommand seam + the /-command catalog (COMMANDS, fuzzy_score)
│ ├── chat.rs request lifecycle: history build, streaming, tool loop
│ ├── research.rs the research pipeline: survey → plan → searchers → …
│ ├── swarm.rs independent drafts → review → reply
│ ├── research_jobs.rs repeating research jobs and report diffs
│ ├── usage.rs usage/cost analytics
│ ├── sessions.rs, spaces.rs, models.rs, backends.rs, memory.rs
│ ├── files.rs, images.rs, scripts.rs, apps.rs space artifacts
│ ├── skills_popup.rs, compaction.rs, export.rs, transcribe.rs
│ └── tests.rs app-level integration tests
├── src/provider/ message shapes, tool-call wire format, events
│ └── openrouter.rs one client for all OpenAI-wire backends (OR/OpenAI/…)
├── src/tools.rs the model's tools: search, fetch, python, video, apps…
├── src/skills.rs, citations.rs tool support
├── src/extract/ any file → text: content sniffing (detect), converters
│ (html, office, odf, epub, rtf, mail, …), external tools
│ (external), the one `to_text` every read path uses
├── src/db.rs SQLite: sessions, messages, usage, citations, model prefs
├── src/appserver.rs localhost static server for model-created apps (8642)
├── src/host/ HTTP/SSE daemon, provider gateway, sync/worker routes,
│ Cloudflare setup, tunnel and sleep-guard lifecycle
├── src/markdown.rs pure to_plain copy path + the shared GFM table splitter
└── src/config.rs, space.rs credentials, spaces
crates/tui/ dugix — the `dugix` binary
└── src/ main.rs bootstrap, cli.rs subcommands, events.rs loop,
app_view.rs (AppView: composer, popup chrome, render state —
wraps App via Deref), flows/ (popup flow methods), composer.rs,
theme.rs, selection.rs, filter_input.rs, history_cache.rs,
ui/ ratatui rendering (history, popups), ui/markdown.rs
```
Data lives under the XDG data dir: `spaces/<space>/` holds the per-space
SQLite db, files, scripts, apps, and generated media. Skills are discovered
from the app-managed `skills/` directory plus project `.agents/skills` (and
Claude/Codex/pi/OpenCode adapter roots), then user roots such as
`~/.agents/skills`, `~/.codex/skills`, and `~/.pi/agent/skills`. Earlier,
more-specific roots win duplicate names; only metadata is loaded until a
skill is explicitly activated.
## Development
```sh
scripts/check.sh # fmt + clippy (-D warnings, pedantic) + cargo-audit + tests
cargo test --workspace # 500+ tests, no network needed
npm --prefix web ci
npm --prefix web run build # production client served by dugix host
npm --prefix web test # Chromium desktop/mobile + mocked SSE tests
```
Open `http://127.0.0.1:8643` after starting `dugix host` from the repository root.
For installed hosts, set `DUGIX_WEB_DIR` to the absolute web build directory.
See [web setup and API documentation](web/README.md) for development and browser setup.
The pre-commit hook runs `scripts/check.sh` on every commit — a merge-ready
change passes it. See [AGENTS.md](AGENTS.md) for conventions and a deeper
module map.
Pushes to `master` release automatically: a workflow bumps the patch version,
tags `vX.Y.Z`, and runs the publish pipeline (crates.io + GitHub release with
the release binary). Release notes are generated from the conventional commits
since the last tag (`scripts/release-notes.sh`), so the GitHub release always
shows what changed. Manual `v*` tag pushes publish the same way. Details in
`.github/workflows/`.
## Known limitations
- The research survey section is always visible, not collapsible.
- The survey's first-round questions are generated from the topic alone — the
concurrent known-chunks/web-survey context arrives after round 1.
- A plan rework presented within the same second overwrites the plan file
(same timestamped name).
[ratatui]: https://github.com/ratatui/ratatui