hugo/DS4Server
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

Make F1 open the complete User Guide

Browse Source
This commit is contained in:
Georg Bauer
2026-08-31 07:43:29 +02:00
parent 32c3a1a47a
commit 7f88e23884
2 changed files with 249 additions and 194 deletions
Download Patch File Download Diff File Expand all files Collapse all files

415
docs/USER_GUIDE.md
View File

@@ -1,230 +1,275 @@
# DS4Server Help
# DS4Server User Guide
DS4Server runs supported DwarfStar language models locally on your Mac. Chats,
project references, and settings stay on this computer.
DS4Server is a native macOS application for running supported DwarfStar models
locally. Model files, chats, project references, settings, checkpoints, and
agent-extension data stay on this Mac.
## Projects and chats
## Getting started
Choose **Add project** to give the coding agent access to a folder. The agent's
file tools are bounded to that project. Use **File > New Chat** (`⌘N`) to start
a chat in the active project. Chats are saved after their first message and can
be renamed, pinned, archived, compacted, rebuilt, or deleted from the sidebar.
An active chat has a green dot beside its title. You can switch chats or start
another one while it works; each chat keeps its own transcript, queued prompts,
tools, approvals, context, and interactive UI state. Model inference shares the
single loaded runtime so model weights are not duplicated, while independent
tool work continues concurrently.
1. Open **View > Model Manager** (`⇧⌘M`). Download a supported model and any
acceleration artifact you intend to use, or verify an artifact already on
disk. A model cannot run until its complete file passes verification.
2. Choose **Add project** and select the folder the agent should work in. The
project remains in its original location; DS4Server stores only its reference
and chat data.
3. Choose **File > New Chat** (`⌘N`). Select a thinking profile and a shell
permission mode in the composer.
4. Enter a request and send it. **Thinking** is the DS4 default, **Direct** omits
hidden reasoning, and **Think Max** appears only when that model profile has
the required long context.
The composer status row shows the current project and, for Git repositories,
the current local branch. An unsaved draft can be moved with the project menu;
saved chats keep their original project. Use the branch menu to switch local
branches when that project's chats are idle. The thinking menu is preselected
to the active model's default mode and loads that model-and-thinking profile:
**Thinking** is the DS4 default, while **Direct** answers without hidden
reasoning. **Think Max** is available when its profile uses at least 393216
context tokens, matching DS4's long-context requirement.
The selected model is shared by the app and the optional local HTTP endpoint.
Preferences are saved locally and generation settings are scoped by model and
thinking profile where the controls indicate that.
The **Git** pane shows added, changed, and deleted files from the current
worktree, including separate staged and worktree markers. Select files to stage,
unstage, or commit them, or commit the existing staged set. Committing with no
selection or staged files asks before staging and committing every change. File
names open a colored diff that can switch between unified and side-by-side
layouts. The fetch, pull, and push actions use the `origin` remote and report
authentication, hook, conflict, and other Git errors without hiding them.
## Projects, chats, and context
Quitting with active chats asks for confirmation. Confirming stops their model
and tool work; canceling leaves every chat running.
The sidebar switches projects and chats. Project controls add, rename, or delete
a project reference. Deleting one removes its DS4Server sessions and
checkpoints, but never deletes the referenced folder. An unsaved draft can move
to another project; a saved chat remains attached to its original project.
Use **File > Export Chat as Markdown** (`⇧⌘S`) to save the visible conversation,
including reasoning and tool results. System-only messages are omitted.
Chat controls can rename, pin, archive, restore, compact, rebuild, export, or
delete a conversation. Archived chats remain under the project's archive until
restored or deleted. Deleting a chat permanently removes its transcript and KV
checkpoint. **File > Export Chat as Markdown** (`⇧⌘S`) saves the visible
conversation, including reasoning and tool results but excluding internal
system messages.
## Writing and editing
Send another prompt while a response is active to queue it for that chat.
**Stop** cancels current model and agent work. You can work in several chats at
once: each keeps its own transcript, prompt queue, tools, approvals, context,
and interactive surfaces. Independent tool work may overlap, but model
inference is serialized through one shared runtime so weights are not duplicated.
Quitting with active chats asks whether to stop them first.
Enter a prompt at the bottom of the Chat view. While a response is running,
additional prompts are queued. **Stop** cancels generation and active agent
work. The Edit menu follows the focused text control and supports undo, redo,
cut, copy, paste, and select all. Transcript text can be selected and copied.
The context indicator shows used and available tokens. Near the limit,
DS4Server compacts older model context while retaining the full visible
transcript. Saved chats also keep local KV checkpoints for fast continuation.
A checkpoint belongs to the exact model, quantization, context size, and runtime
configuration that created it. After one of those changes, DS4Server reports a
context rebuild, prefills the saved transcript, and writes a compatible
replacement without losing messages. **Rebuild context on next use** requests
the same safe rebuild manually.
The context indicator beside the composer shows used and available tokens.
DS4Server automatically compacts long chats near the context limit; the full
visible transcript remains available.
## Agent capabilities and safety
## Checkpoints and model changes
The coding agent can use native tools to list a directory, read files, search
file contents, write or edit files, inspect Git state, and maintain Dev Brain.
It can also run shell commands and use web search or visit pages when the task
needs them. Content search is not filename discovery: until DS4Server ships a
native filename glob tool, recursive filename lookup may require an approved
shell command. A directory listing remains a non-recursive view of one folder.
Each saved chat keeps a local KV checkpoint so its next turn can resume without
prefilling the whole conversation. A checkpoint belongs to the exact model,
quantization, context size, and executor configuration that created it.
Tool calls are checked against typed schemas before execution. Unknown tools,
missing or extra fields, malformed calls, and invalid values return structured
errors instead of running. Results appear in the transcript. Copy actions expose
their complete text, and large output may also be saved to a local file rather
than filling the transcript. **Stop** cancels active generation and cancellable
tool work.
If the selected model, model file, quantization, context size, or relevant
runtime configuration changes, DS4Server cannot safely resume that checkpoint.
It reports that the context is being rebuilt, prefills the saved transcript,
and writes a compatible replacement. No chat messages are lost. **Rebuild
context on next use** performs the same safe rebuild manually.
The shell permission mode is stored with each chat:
## Models
- **Heuristic** applies DS4Server's built-in command-risk checks.
- **AI based** asks the local model to classify a shell command in a separate
one-shot request. A risky result shows its reason. If classification fails or
is invalid, approval is required.
Open **View > Model Manager** (`⇧⌘M`) to download, resume, verify, or remove
supported model artifacts. Preferences choose the active model and control
generation, context, speculative decoding, Metal execution, SSD expert
streaming, steering, checkpoint storage, diagnostics, and the local endpoint.
Generation values are stored per model and thinking mode. Acceleration and SSD
values are stored per model, while the Prompt section's system prompt is shared
by every profile.
An approval dialog shows the command and working directory. **Allow once** runs
that operation; **Deny** returns the refusal to the agent. Destructive, network,
privileged, application-control, credential, and outside-trusted-path commands
require approval as applicable. Dev Brain's configured vault is trusted like
the project for ordinary path checks, but does not bypass those risk classes.
Model files are large. Verification checks the complete artifact before it is
used. Removing a model never removes projects or chat history.
### Ralph loops
## Agent tools and approvals
Ask the agent to use a Ralph loop when a bounded task benefits from repeated
autonomous passes, for example, “Use a Ralph loop with at most 12 rounds to fix
and verify this parser.” Ralph is an agent tool, not a view or slash command.
Its default is 8 rounds and its allowed range is 1–64.
The local agent can inspect and edit project files, search text, and run shell
commands. Operations that can affect data outside the ordinary project workflow
show an approval dialog. Read the command and working directory before choosing
**Allow once**. Choose **Deny** to return the refusal to the agent.
Each round receives the same objective in a fresh model context, inspects the
current project, and leaves file changes on disk. The next round receives only
the previous validated report, applicable workspace instructions, and available
skills. The current model settings and permission mode still apply. Ralph stops
on completion, a reported blocker, a failed round, cancellation, or the round
limit; a worker's completion report is evidence to review, not independent
certification. Ralph workers cannot start nested Ralph loops.
The permission selector at the bottom of each chat is stored with that session.
**Heuristic** uses the built-in command checks. **AI based** asks the local model
to classify each shell command in an isolated one-shot request; risky commands
show the model's reason in the normal approval dialog. If that check fails or
returns an invalid answer, DS4Server requires approval. Preferences choose the
default for new sessions. When Dev Brain is enabled, its configured vault is
treated like the project for path-risk checks; destructive, network, privilege,
application-control, and credential risks still require approval.
### Workspace instructions and standard skills
Tool calls and results appear in the transcript. Use their copy actions for the
complete, untruncated text; large outputs can also be opened from their saved
file. Calls are checked against typed schemas before execution, so unknown
tools, missing or extra fields, invalid values, and malformed tool syntax are
returned to the agent as structured errors instead of being executed.
DS4Server reads global instructions from
`~/Library/Application Support/de.rfc1437.ds4server/AGENTS.md`, then project
instructions from root to the working directory. In each directory,
`AGENTS.local.md` overlays `AGENTS.md`. Deeper guidance wins over broader
guidance, while system, developer, and direct user instructions remain higher
priority. Additions, changes, and removals are tracked during a chat and restored
after compaction; an unreadable changed file leaves its last readable version in
effect with a notice.
## Ralph loops
Manually installed standard skills live at
`~/.agents/skills/<name>/SKILL.md`. DS4Server initially gives the agent each
valid skill's name, description, and location; the agent reads the full skill
only when the task matches. These roots are readable but not writable through
agent file tools. Start a fresh chat after changing the manually installed skill
set so its prompt and tool roots agree.
For a bounded task that benefits from repeated autonomous passes, ask the agent
to use a Ralph loop, for example: “Use a Ralph loop with at most 12 rounds to
fix and verify this parser.” This is an agent tool, not a slash command or a
separate view. The normal default is 8 rounds and the allowed range is 1–64.
### Dev Brain
Ralph runs in the foreground. Each round receives the same immutable objective
in a fresh model context, inspects the current project as its source of truth,
and ends with one structured report. File changes remain on disk between
rounds, but earlier conversation does not: only the previous validated report,
applicable workspace instructions, and available skills are handed to the next
worker. This limits accumulated context while allowing the next round to
continue, verify, or repair the work.
Dev Brain is a project-backed Obsidian wiki for durable, source-cited engineering
knowledge. In **Preferences > Dev Brain**, select an existing vault containing
`.obsidian`, enable it, and save. Ask the agent to build, refresh, search, or
validate the wiki. DS4Server manages its contract files and explicitly marked
topic pages, not Obsidian settings, hidden files, attachments, or unrelated
notes. Verified pages can support answers; stale or needs-review pages are leads
that the agent must recheck against project source. Disabling Dev Brain removes
its tools and guidance without deleting the vault.
The current chat's model settings and permission mode still apply. Risky shell
commands and visible browser actions can therefore pause for the usual
approval. **Stop** cancels the loop and its active work. Ralph also stops when a
worker reports completion or a blocker, a child round fails, or the round limit
is reached. Completion is a worker report rather than independent
certification; review its evidence or ask the parent agent to verify it when
that distinction matters. Ralph workers cannot start nested Ralph loops.
## Agent extensions
## Workspace instructions and standard skills
**Preferences > Agent Extensions** installs and manages portable Codex plugins:
DS4Server applies workspace guidance from these locations:
1. Enter an HTTPS Git repository URL and, optionally, a branch, tag, or commit.
2. Choose **Install**. The repository must contain
`.codex-plugin/plugin.json` and provide at least a skills directory or a
supported lifecycle-hooks manifest.
3. Inspect the displayed description, source URL, requested ref, resolved
commit, author, version, skill count, and hook names.
4. Enable the extension. An extension with command hooks first asks for explicit
trust. Its programs run with your user permissions even though DS4Server
invokes them without a shell and limits their environment, runtime, input,
and output.
5. Use **Update** to fetch the configured source/ref, disable the toggle to stop
future use, or **Uninstall** to remove the installed package and its stored
extension data. Hook failures appear on the extension row.
- `~/Library/Application Support/de.rfc1437.ds4server/AGENTS.md` applies to all
projects.
- `AGENTS.md` in the project root applies to that project.
- `AGENTS.md` and `AGENTS.local.md` in nested directories apply after the agent
successfully reads, writes, or edits a file in that part of the project.
Enable, disable, and update changes apply to subsequent matching hook events.
A current chat does not retroactively receive a `SessionStart` event. Because a
chat's native tool roots are initialized for that session, start a fresh chat
after adding, updating, enabling, or disabling extension skills. An app restart
is not otherwise required.
Instructions are ordered from broad to specific. A deeper file takes
precedence over broader guidance, and `AGENTS.local.md` is the final overlay for
its directory. DS4Server records additions, changes, and removals during an
ongoing chat and restores the applicable instruction set after context
compaction. Files that cannot be read safely produce a context notice; if the
file was already tracked, its last readable version remains in effect.
Workspace instructions cannot override system, developer, or direct user
instructions.
Extension skills are versioned inside their plugin and are managed with its
toggle, update, and uninstall actions. They are separate from manually installed
standard skills under `~/.agents/skills`. Installed packages, per-extension
data, and `registry.json` live under
`~/Library/Application Support/de.rfc1437.ds4server/extensions/`.
Reusable standard skills are discovered from
`~/.agents/skills/<name>/SKILL.md`. Each `SKILL.md` starts with YAML frontmatter:
## A2UI interactive surfaces
```yaml
---
name: review-release
description: Review a release against this project's checklist.
---
```
A2UI is an interactive or graphical response the agent can generate when it is
more useful than prose. It is not another model and is not a tool you operate
directly. Enable or disable it in Preferences. Ask for an interactive chart,
table, form, map, or other surface, then open the **A2UI** view (`⌘2`) if the app
does not switch there automatically.
The directory name must match `name`; names use lowercase letters, digits, and
single hyphens. DS4Server initially gives the agent only each valid skill's
name, description, and path. When a task matches, the agent reads the complete
file and any needed resources from that skill directory. Standard skill files
are readable but not writable through agent tools. Install only skills you
trust, place them manually before starting a chat, and start a new chat after
changing the installed set. There is currently no built-in skill installer or
extension marketplace.
Buttons can send events back to the agent. Text fields, checkboxes, sliders,
date/time inputs, and choice pickers update the surface's data. Tabs and modals
organize content. Previous and next actions navigate saved surface history;
**Dismiss** removes the current saved surface after confirmation. Ordinary model
prose remains in the Chat transcript. Video and audio controls open native
playback windows.
## Dev Brain
The embedded catalog currently supports:
Dev Brain is a project-backed wiki for durable engineering knowledge. It lets
the coding agent compile architecture, behavior, decisions, invariants,
workflows, and relationships once, then retrieve that verified context in later
chats. Registered projects remain authoritative; Dev Brain is not a general
memory store and never replaces checking changed source code.
- Content: Markdown/text, images and avatars, icons, video, audio, and dividers.
- Layout: rows, columns, lists, cards, modals, and tabs.
- Controls: buttons, text fields, checkboxes, sliders, date/time inputs, and
single- or multiple-choice pickers.
- Visual and research components: bar, line, area, stacked-bar, pie, donut, and
heatmap charts; tables; metrics; timelines; maps; mind maps; and forms.
To set it up:
## The rest of the app
1. Create or choose a dedicated Obsidian vault. The folder must already contain
**.obsidian**.
2. Open **Preferences > Dev Brain**, choose the vault, enable Dev Brain, and
save.
3. In a project chat, ask the agent to build or refresh Dev Brain. Tell it the
questions and areas that matter most so it can maintain **purpose.md** and
compile a small set of useful topic pages instead of summarizing every file.
### Models and preferences
Useful requests include “Build Dev Brain for these projects,” “Refresh Dev
Brain after my recent changes,” “What does Dev Brain know about the cache
invariants?”, and “Check the wiki, then verify this against the source.” The
agent gets the real vault folder from Dev Brain, then uses its normal list,
read, search, write, and edit tools on the Markdown. A dedicated validation tool
checks the result and refreshes the disposable local SQLite search index.
**Model Manager** downloads, resumes, verifies, and removes managed model and
acceleration artifacts. Removing an artifact does not remove projects or chats.
Preferences select the active model and its default thinking profile. Generation
values are stored per model and thinking mode; acceleration and SSD settings are
stored per model; the custom system prompt is shared across profiles. Other
sections control A2UI, permission defaults, endpoint settings, Git diff display,
Dev Brain, extensions, checkpoint storage, and diagnostics.
The vault remains ordinary Obsidian Markdown:
### Main views, sidebar, and branches
- **purpose.md** records its scope, priorities, and recurring questions.
- **schema.md** is the detailed contract the agent follows when maintaining it.
- **index.md** is a generated catalog of every managed topic page.
- **log.md** is an append-only history of material updates.
- Topic pages live under **projects/**, **subsystems/**, **concepts/**,
**decisions/**, **invariants/**, and **workflows/** as needed.
**Chat** shows the conversation, **A2UI** shows interactive surfaces, **Git**
shows the current worktree, and **Stats** reports model, generation, HTTP, SSD,
and KV-cache activity. **View > Show Sidebar** (`⌘B`) hides or restores the
project sidebar. The composer status shows the active project and its local Git
branch. Branch switching is available while that project's chats are idle.
Every topic cites exact project files and a Git revision or content hash.
**Verified** pages may support answers. **Stale** pages are navigation leads
whose evidence changed, and **needs-review** pages contain visible uncertainty;
the agent must recheck project sources before relying on either. After editing,
the agent runs validation. Unsafe paths and invalid page structure or provenance
are errors to repair in place. Broken links are reported as warnings: the valid
page stays on disk, so the agent can make a small edit or create the missing
page without regenerating its work. Validation rebuilds **index.md**
deterministically instead of asking the model to keep it synchronized.
### Git
DS4Server may modify only the four contract files and topic pages explicitly
marked as Dev Brain-managed. Standard agent file tools can access the vault but
cannot modify Obsidian settings, hidden files, or unrelated notes. You can
inspect, edit, link, and version the managed Markdown normally; invalid manual
edits are reported rather than silently trusted. Disabling Dev Brain removes its
folder, search, and validation guidance from the built-in coding agent without
deleting the vault.
The Git view separates staged and worktree changes. Select files to stage,
unstage, or commit; selecting a file opens a colored unified or side-by-side
diff. Committing with no selected or staged files asks before staging and
committing every change. Fetch, pull, and push use the `origin` remote and report
authentication, hook, conflict, and other Git errors.
## Views and sidebar
Use **View > Show Sidebar** (`⌘B`) to hide or restore the project sidebar. The
Chat view shows the transcript, A2UI shows the latest interactive surface, and
Stats reports model, generation, HTTP, SSD, and KV-cache activity.
## Local HTTP endpoint
### Local API
Preferences can enable an OpenAI- and Anthropic-compatible endpoint on
`127.0.0.1` (port `4000` by default). Endpoint conversations are owned by their
client and do not appear in the project sidebar. CORS is off by default and
should only be enabled for trusted local browser clients.
`127.0.0.1`, port `4000` by default. Endpoint conversations belong to their
client and do not appear in the sidebar. CORS is off by default; enable it only
for trusted browser clients on this Mac. Saving changed endpoint settings
restarts the local listener.
## Data and recovery
### Data and recovery
Application data is stored under `~/Library/Application Support/de.rfc1437.ds4server/`.
Deleting a project from DS4Server removes its saved sessions and checkpoints,
but never deletes the referenced project folder. Deleting a session removes its
transcript and checkpoint permanently.
Application data is under
`~/Library/Application Support/de.rfc1437.ds4server/`: `config.yaml` stores
preferences, `data.sqlite3` stores projects and chats, `models/` stores managed
artifacts, `kv-cache/` stores checkpoints and metrics data, `extensions/` stores
plugins, and `browser/` stores the agent browser profile. Project source remains
where you selected it.
Removing a model can be recovered by downloading or restoring and verifying the
same artifact. A context incompatible with changed runtime settings is rebuilt
from the saved transcript. Deleted project references, chats, extension data,
and their checkpoints are not restored by DS4Server; use your own backup if you
need recovery from deletion.
## Troubleshooting
- **No model selected or model unavailable:** select a model in Preferences,
then download and verify all required artifacts in Model Manager.
- **Verification failed:** retry verification or download. DS4Server will not
load incomplete or hash-mismatched weights.
- **Context is rebuilding:** the saved checkpoint no longer matches current
model/runtime settings. Let the transcript prefill finish; messages remain.
- **Extension install failed:** use an HTTPS Git URL and verify the repository
contains a valid portable plugin manifest plus skills or supported hooks.
- **Extension hook failed:** read the error on its Preferences row, repair or
update the extension, then retry the matching event. Trust is required before
command hooks can run.
- **Tool approval denied:** the operation was not run. Send a safer request or
repeat it and approve only after checking the command and working directory.
- **A2UI is unavailable:** enable A2UI in Preferences and ask the agent for an
interactive surface in a new prompt.
## Keyboard shortcuts
These are the shortcuts registered by the native DS4Server menu. On Macs whose
top row controls brightness or media, use `fn-F1` when macOS requires it;
DS4Server does not override the system keyboard mapping.
| Shortcut | Action |
| --- | --- |
| `F1` | DS4Server User Guide |
| `⌘,` | Preferences |
| `⇧⌘M` | Model Manager |
| `⌘N` | New Chat |
| `⇧⌘S` | Export Chat as Markdown |
| `⌘B` | Show or hide the sidebar |
| `⌘1` | Chat view |
| `⌘2` | A2UI view |
| `⌘3` | Git view |
| `⌘4` | Stats view |
| `⌘Z` | Undo |
| `⇧⌘Z` | Redo |
| `⌘X` | Cut |
| `⌘C` | Copy |
| `⌘V` | Paste |
| `⌘A` | Select All |
| `⌘Q` | Quit DS4Server |