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

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.

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