dugix 1.0.0

A local-first terminal chat app for deep research and multi-agent work
dugix-1.0.0 is not a library.

dugix

crates.io docs.rs license: MIT

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

cargo install dugix

This provides the dugix command. Requires Rust 1.91+ (edition 2024).

To run from a checkout instead:

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:

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 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) as [provider].host_token; provider API keys remain on the machine and are never sent to clients.

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:

[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:

[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):

[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:

[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.

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:

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:

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 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 Editors. 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

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 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 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).