dugix
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
This provides the dugix command. Requires Rust 1.91+ (edition 2024).
To run from a checkout instead:
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/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.
CF_API_TOKEN=… # 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 viewffmpeg— video transforms formedia; withffprobeand a localwhisper, audio/video files get metadata and transcriptspandoc,libreoffice(soffice),antiword/catdoc— richer reads of markup and legacy office files (docx, odt, epub, rtf, org, rst, … work without them;.doc/.xls/.ppt/.keyneed 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:
[]
= ["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:
[]
= "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):
[]
= "mlx"
= ["/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:
[]
= "edge0"
= 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.
# or, to search images too:
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/steermid-run./research! <topic>runs ungated. Both create a one-off research job listed in/jobs; pressrthere to run it again. The finished report is saved asresearch-<topic>-<time>.mdin 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 throughdugix jobs daemon(ordugix jobs run-duefrom cron)./watchopens/jobs, wherewtoggles 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
memorytool, 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./memoryedits it in$EDITOR,/memory tidyasks 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 sharelists 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'smemorytool lists every space's chapters (spaces), cansharea chapter with chosen spaces, all of them or none, and canmergesame-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 indugix.dband 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 onhttp://localhost:8642;initscaffolds Astro+React / Vite+React starters,buildcompiles them with the framework's static build),scripts,skills, andmedia(image/video generation with ffmpeg transforms) - Usage analytics:
/usageshows 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.
Escswitches to Normal mode, and a secondEscdoes whatEscdoes without vim (stop the reply, clear the composer, leave a panel). In Normal mode,Entersends. - 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 yover any motion, anddd 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.
- motions:
- 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
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).