VS Code extension
The extension is the primary cockpit — a dockable chat panel that talks to your local server at 127.0.0.1:8765. It’s a thin client: the work happens in the background service, so the panel stays fast and responsive while the agent runs.
Installing it
The Windows installer bundles the extension and tries to install it for you. If the activity-bar icon is missing, install the VSIX by hand — the full steps are on the Installation page. In short: Extensions view → … → Install from VSIX… → pick riverforge-vscode.vsix → reload.
The commands are listed in the Command Palette under Riverforge: …. Open it with Ctrl+Shift+P.
Commands
| Command | What it does |
|---|---|
Riverforge: Open Chat | Opens / focuses the dockable chat view |
Riverforge: Status | Checks server health (/health) |
Riverforge: Pause Models | Unloads Ollama models to free VRAM (/pause) |
Riverforge: Resume Models | Warms the main models again (/resume) |
Riverforge: Open Memory Visualizer | Launches the Memory Visualizer |
The server itself is started and stopped from the tray, not the extension — the extension only polls and reconnects when the server comes online.
Anatomy of the chat panel
The header
Across the top of the panel you’ll find a small toolbar:
| Control | Meaning |
|---|---|
| Server dot | Green = online, red = offline / unreachable |
| Memory (◎) | Opens the external Memory Visualizer |
| Index (⊕) | Indexes the current project into memory — asks to confirm, then shows progress |
| AI scan | Toggles the AI-comment watcher |
| Pause | Asks the server to unload models and free VRAM |
The composer
The bar under the message box is a single row of icon buttons; labels appear on hover or in each picker.
| Control | Meaning |
|---|---|
| + Attach | Attach files or folders |
| Mic | Reserved for the planned local speech input |
| Models | Opens the model panel — Planner, Executor, Thinking and the chat context-window size |
| Mode | Pick Chat, Ask or Agent — the icon reflects the current mode |
| Tool approval | Confirm or Autopilot. Takes effect live, even on a run already in flight |
| Context ring | Estimated context-window usage for the next turn; click it for a breakdown |
| Auto-correct | Rewrites your draft prompt before sending |
| Send | Sends the message; becomes Stop while a run is in flight |
The mode, tool-approval and model choices are remembered across VS Code restarts. The context size persists too and is applied after a server restart. Send a message with Ctrl+Enter; Stop cancels the wait and stops the run on the server.
The chat sidebar
A single shared chat-history sidebar lets you create, pin, archive, rename and delete chats. Threads are stored with your Riverforge data, so they survive restarts and can be backed up (see Data & Backup). When the server is offline the extension still shows your cached chats, and reconnects automatically when it comes back.
What renders in chat
Assistant replies are rendered as Markdown as they stream, plus a few richer surfaces:
| Output | Rendering |
|---|---|
| Markdown | Headings, lists, tables, links, inline code and fenced code blocks |
Fenced html block | Code block plus a sandboxed live preview — the agent can mock a UI and show it |
Markdown image  | Inline image preview for HTTP / data image URLs |
image_search result | Compact cards with preview, direct image link and source link |
::: details Title blocks | Collapsible sections for long structured output |
| Edit tool event | Expandable diff card with +N / −N counts |
| Tool result events | A live tool trace while the agent runs |
Agent-mode runs show live tool activity — every tool call appears as a card with its arguments, a result preview, and (for edits) a diff. Keep all / Undo all appear above the composer when a run changed files.
Attachments
You can attach context three ways: the + button, dragging from the VS Code Explorer, or dragging files and folders from Windows Explorer. The Attach button accepts images, audio and video.
| Attachment | Behaviour |
|---|---|
| Text / code file | Sent as readable context to Ask and Agent mode |
| Image | Sent to Ask mode as image data when the model supports vision; listed as context in Agent mode |
| Folder | Expanded into supported files, skipping .git, node_modules, .venv, dist, build |
| Very large file | Skipped or capped so the model isn’t flooded |
| Audio / video | Stored with the request; local transcription is a planned feature (the Mic button is reserved for it) |
The AI-comment watcher
Write small tasks directly in your source as comments, and let Riverforge pick them up:
# AI? explain this function
# AI! fix this edge case
# AI add validation here| Marker | Intended use |
|---|---|
AI? | Ask / explain / review |
AI! | Code / fix action |
AI | General agent task |
Press the AI button in the chat header to start the watcher, or run a one-off scan with /ai-comments. The watcher notifies you when it finds new markers — it never silently edits files on its own.
Settings
Open Settings → Extensions → Riverforge, or edit them in settings.json:
| Setting | Default | Purpose |
|---|---|---|
riverforge.serverUrl | http://127.0.0.1:8765 | Local server URL |
riverforge.agentRoot | auto-detect | Path to the Riverforge install folder; leave empty to detect from the workspace |
riverforge.defaultStepLimit | 1000 | A safety ceiling that catches a run stuck in a loop. The agent normally ends its own turn once your request is answered |
riverforge.preferHostTerminal | true | Prefer the visible VS Code terminal for commands the agent runs, when available |
The Models panel gives you Planner, Executor and Thinking controls plus the context-window size — that’s all you need to set; Riverforge handles the rest automatically. More on Models & Hardware.