User Guide

From downloading to running your first task takes about five minutes. After this page you should be able to drive Dolaima yourself.

1. Getting started

Download and unpack

Grab the archive for your platform from the download page. Unpacking gives you a single-file executable:

• Windows: waycoder.exe (x64 or ARM64)
• Linux / macOS: waycoder (x64 or ARM64)

It is a native single file — no .NET runtime required. Copy it anywhere and put it on your PATH. The macOS build is not signed or notarized, so the first launch needs a right-click → Open, or removing the file's quarantine flag.

The download page also offers the GUI edition (waycoder-gui, a desktop window): it unpacks to waycoder-gui.exe plus a few native libraries (SkiaSharp and friends) that must stay in the same folder. Both editions share one config and workspace (~/.waycoder/). The rest of this guide uses the terminal edition.

Configure a model and your own API key

# First run: straight into the full-screen terminal UI
waycoder

Then configure a model from inside the app:

• Press Ctrl+T to open Settings (or type /settings) and go to the Model group; or
• Use the commands: /provider list to see providers, /model key <provider> <key> to store a key, /model to pick a model (Ctrl+M opens the model picker directly).

With a local model (Ollama / LM Studio), point the BaseUrl at the local port and use any placeholder key — local servers do not validate it. The BaseUrl does not need /v1; the app appends it for you. For a local model with a small context window, turn on economy mode (--economy on), otherwise the full prompt may exceed the model's window.

Your first conversation

waycoder
# Then just type what you need, for example:
collect every TODO under src into one list

When the yellow confirmation bar appears, press Y to allow, N to deny, A to allow everything for this session. To see the plan before anything is touched, press Shift+Tab to switch to Plan mode.

2. Five front ends + one-shot mode

Front end	Command	Notes
Full-screen terminal UI (default)	waycoder	Where a bare launch lands. Multi-turn chat, F1–F10 slots, sidebar, inline permission bar
Web UI	waycoder --web [port]	Three-column browser UI, default port 9527; opens the browser for you
Plain CLI	waycoder --cli	Reads line by line → plain-text replies. Good for scripts, CI, and terminals without a full-screen mode
Desktop GUI	waycoder --gui [file]	A separate desktop window (Avalonia); pass a file to open the built-in editor straight away
Watch mode	waycoder --watch	Watches source files for AI! comments and runs as soon as you save

# The five front ends
waycoder                          # full-screen terminal UI (default)
waycoder --web                    # web UI (port 9527 by default)
waycoder --cli                    # plain CLI
waycoder --gui                    # desktop GUI
waycoder --watch                  # watch for AI! comments

# One-shot mode: runs and exits
waycoder -p "collect every TODO under src into one list"
echo "list the directory and count lines" | waycoder   # prompt from stdin
waycoder --json -p "fix the null pointer in login"     # stdout is one structured JSON object, for IDEs / CI

# Deliver tasks to slots (F1–F10; several at once is fine)
waycoder -pa "read-only, analysis only" -p1 "analyse module A" -p2 "analyse module B"

How Watch mode works: write a comment like # AI! why does this fail? in your source, save the file, and Dolaima picks the comment up as the prompt, runs it, and writes the result back. AI? asks a question instead of changing anything.

3. Slash commands you will actually use

Type / for autocompletion and /help for the full list. Ctrl+U opens the command palette (high-frequency actions plus every slash command).

Command	What it does
/help	Every command and shortcut
/mode	Switch work mode (build / plan / chat; same as Shift+Tab)
/model	Model catalogue: <id> selects the large model / small <id> the small one / list / test / import
/provider	Providers: list / add / select / apikey set <provider> <key>
/connect	Connection layer: switch a named connect in one step, chain on enables the fallback chain
/config	Configuration from the command line: list / get <key> / set <key> <value>
/settings	Graphical settings screen (same as Ctrl+T)
/permit	Permission mode (the confirmation axis): ack / auto / smart / yolo
/perm	Sandbox boundary (the boundary axis): off / project / network-off / hard
/edit	Built-in source editor (syntax highlighting / line numbers / find & replace / Lint summary after saving)
/diff	Preview the changes file by file (/diff <keyword> filters by file name)
/session	Sessions: list / save / load / resume
/compact	Compact the context manually (when a long conversation slows down)
/reset	Clear the conversation and start over
/tokens	Token usage and cost estimate
/git	Git operations (status / log / diff); /autocommit commits automatically
/undo	Roll back: edit-level (per file) or checkpoint-level (/timeline shows the timeline)
/kb	Self-learning knowledge base: mine distils git history / search / diagnose <error> / review spaced repetition
/init	Project init: scans the project and writes AGENT.md (/init claude writes CLAUDE.md)
/update	Check for updates; /update now downloads and self-replaces immediately
/mcp	MCP server management (status / reconnect)
/exit	Exit and save the session (same as Ctrl+C)

More commands — /join (continue from a Claude/Codex/OpenCode/Crush/Aider/Gemini session), /teach (teaching mode), /doctor (self-check), /theme, /free (free models), /repro (export a reproducible script) — are listed under /help and in the FAQ.

4. Keyboard shortcuts

These are the keys of the chat screen (full-screen terminal). While a dialog is open the keyboard belongs to the dialog, with one exception: Ctrl+C — the only system key, effective at any time.

🌐 Global

Key	Action
F1–F10	Switch workspace slots
Esc	Interrupt the current Agent (while running)
Ctrl+Z	Graceful pause (stop after this batch)
Ctrl+C	Exit (saves the session first)
Ctrl+Q	Emergency exit (force-save, immediate)
Ctrl+S	Open the session list
Ctrl+L	Force a full-screen redraw

✏ Editing

Key	Action
Enter	Send the message
Shift+Enter	New line in the input area
Ctrl+Insert	Copy the selection (Ctrl+C is taken over as exit, so copying uses this key)
Ctrl+V	Paste
Tab	Path completion / insert 4 spaces
↑↓	Input history (when the input area is not empty)
←→	Move the caret in the input area
Home / End	Start / end of the input line

📋 Inline choice bar (permission confirm / plan approval / questions)

This bar expands in place below the input box; it is not a dialog.

Key	Action
↑↓ / Home / End	Move between options
Enter	Confirm / next question
Esc	Deny / cancel
Y / N / A	Allow / deny / allow all (permission confirmation)
Space	Check / uncheck (multi-select)
←→ / Tab	Page through (multi-question questionnaires)
1–9	Pick item N directly (on a multi-select page it toggles that item)

🔄 Modes

Key	Action
Shift+Tab	Cycle the work mode Build→Plan→Chat (or /mode)
Ctrl+P	Cycle the permission mode (Ask/Auto/SmartAuto/Yolo)
Ctrl+E	Cycle the economy mode (off → auto → on → extreme)
Ctrl+M / /model	Open the model picker
Ctrl+N	Quick-switch to the next connect
Ctrl+U	Command palette
Ctrl+G	Cycle the reasoning depth

🧭 Navigation

Key	Action
↑↓	Scroll the chat (when the input area is empty)
Ctrl+↑ / Ctrl+↓	Scroll the chat by 3 lines
PgUp / PgDn	Page through the chat list
Ctrl+Home / Ctrl+End	Jump to the top / bottom of the chat
Ctrl+T	Open settings
Ctrl+B	Toggle the sidebar
Ctrl+O	Swap the large and small models

🖱 Mouse

Action	Result
Left click	Select / confirm
Wheel	Scroll lists and panels
Drag the title bar	Move a floating window
Drag an edge	Resize a floating window

🛠 Tools

Key	Action
Ctrl+D	Diff-preview the changed files
Ctrl+R	Generate a sync QR code (scan to move across devices)
Ctrl+F	Search the conversation history
Ctrl+H	Open this help panel
Ctrl+W	Theme picker (use /theme next to rotate themes)
Alt+T	Read the last reasoning in full (reasoning is collapsed to one line in the chat; clicking it works too)

5. The four axes: how the modes split up

Dolaima's modes are four independent directions, and every question has exactly one answerer:

Axis	Decides	Values	How to switch
Behavior work mode	What work gets done and which tools exist	Build (default, all tools) · Plan (read-only tools + slim prompt; the plan is approved before it runs) · Chat (0 tools, 0 prompt)	Shift+Tab cycles · /mode build|plan|chat · --mode at startup
Confirmation permission mode	When a dangerous operation interrupts you	Ask (default) · Auto (asks on changes) · SmartAuto (asks on danger) · Yolo (never asks)	Ctrl+P cycles · /permit ack|auto|smart|yolo · --permit / -y at startup
Boundary sandbox	What it can touch (writable scope / network)	off (default, no boundary) · project (project root only) · network-off (no network) · hard (project root + no network)	/perm off|project|network-off|hard
Cost economy mode	How many tokens get spent (prompt tier + compaction thresholds + output cap)	off · auto · on (default) · extreme (minimal prompt + core tools)	Ctrl+E cycles · /config economy … · --economy at startup

The decision chain in one sentence: whether a tool exists is decided by the work mode (Chat = none, Plan = read-only whitelist, Build = full or economy-trimmed); what it may touch is decided by the sandbox; whether it interrupts is decided by the permission mode; how many tokens are spent is decided by the economy mode.

6. Where configuration and data live

Desktop: configuration and data live under ~/.waycoder/ in your home directory (on Windows, %USERPROFILE%\.waycoder\):

Path	Contents
~/.waycoder/config.json	The main configuration (the single authoritative source) — model, economy mode, sandbox, theme and every other setting
~/.waycoder/api_keys.json	API keys, one per provider
~/.waycoder/connections.json	Named connects, providers and the model fallback chain
~/.waycoder/provider/*.json	The model catalogue (one file per provider)
~/.waycoder/kb/	The self-learning knowledge base (/kb)
.waycoder/ in a project	Per-project data: memory/, hooks/, sessions, checkpoints

Settings can also be read and written from the command line: waycoder --config get Model, waycoder --config set Temperature 0.3; the in-app equivalent is /config.

7. Mobile quick start

Configure a key

Open the app → Settings → Model → pick a provider → paste your own API key. Once it is in, the home screen shows the configured state.

The deal is exactly the same as on the desktop: the app ships with no model credits. The key is yours from your provider, usage is billed by that provider directly, and the key is stored on-device only (in the app's private directory) — it is never sent to us.

What the five tabs do

Tab	What it is for
Home	Welcome and guidance, plus the current configuration status (which provider / model)
Chat	Talk to the AI or hand it a task; streaming output, with interrupt and queueing
Shell	A simulated terminal: run shell commands, and run VML programs
Files	Browse and manage the sandboxed workspace; open a file to edit it
Settings	Providers / model / API key, editor and display options, the Full Edition, and About

The built-in editor has syntax highlighting and line numbers, and edits files in the workspace directly. Its bottom panel has five pages — Problems, Output, Find, Outline and AI: Outline lists the functions and types in the current file (with parameter lists and return types) and jumps to a line when tapped, and the AI page chats about the whole file and shows a diff before it writes anything. Compile and run from the Shell tab.

Run a sample program

The app ships with samples, sorted by language. On the Shell tab, type:

vml run examples/c/demo_std.c
# samples for other languages live under examples/<language>/, e.g. a classic game
vml run examples/c/tetris.c

The first time a VML program runs, the app extracts the bundled standard library into the workspace (about 39 MB / 5200+ files), with a progress line on screen — only the first time, or after a library update. Later launches are fast.

Free Edition vs Full Edition

The free version already gives you the editor and compiling/running C and VML assembly. The Full Edition is a one-time in-app purchase (not a subscription) that unlocks the compilers and optimizer for all 27 languages. Buy or restore it under Settings → Full Edition. After changing phones or reinstalling, use "Restore purchase" with the same account — you are not charged twice.

---

Still stuck? See the FAQ, or get in touch from the support page.