149 lines
7.4 KiB
Markdown
149 lines
7.4 KiB
Markdown
# DS4Server Help
|
|
|
|
DS4Server runs supported DwarfStar language models locally on your Mac. Chats,
|
|
project references, and settings stay on this computer.
|
|
|
|
## Projects and chats
|
|
|
|
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.
|
|
|
|
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 **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.
|
|
|
|
Quitting with active chats asks for confirmation. Confirming stops their model
|
|
and tool work; canceling leaves every chat running.
|
|
|
|
Use **File > Export Chat as Markdown** (`⇧⌘S`) to save the visible conversation,
|
|
including reasoning and tool results. System-only messages are omitted.
|
|
|
|
## Writing and editing
|
|
|
|
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 beside the composer shows used and available tokens.
|
|
DS4Server automatically compacts long chats near the context limit; the full
|
|
visible transcript remains available.
|
|
|
|
## Checkpoints and model changes
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## Models
|
|
|
|
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.
|
|
|
|
Model files are large. Verification checks the complete artifact before it is
|
|
used. Removing a model never removes projects or chat history.
|
|
|
|
## Agent tools and approvals
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## Dev Brain
|
|
|
|
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.
|
|
|
|
To set it up:
|
|
|
|
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.
|
|
|
|
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.” Search
|
|
and reads use a disposable local SQLite full-text index. The index checks vault
|
|
files and cited project evidence before use, so no separate indexing service or
|
|
manual refresh button is needed.
|
|
|
|
The vault remains ordinary Obsidian Markdown:
|
|
|
|
- **purpose.md** records its scope, priorities, and recurring questions.
|
|
- **schema.md** is the detailed contract the agent follows when maintaining it.
|
|
- **index.md** catalogs 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.
|
|
|
|
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. Wiki updates
|
|
are validated as a complete batch before publication, so a broken link,
|
|
out-of-bounds path, invalid citation, or stale verified claim leaves the last
|
|
valid wiki untouched.
|
|
|
|
DS4Server may modify only the four contract files and topic pages explicitly
|
|
marked as Dev Brain-managed. It does not modify Obsidian settings, attachments,
|
|
trash, 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 tools and instructions
|
|
from the built-in coding agent without deleting the vault.
|
|
|
|
## 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
|
|
|
|
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.
|
|
|
|
## 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.
|