BLXCode Documentation
BLXCode Documentation — BLXCode documentation.
Welcome to the BLXCode docs. User guides explain how to run and use the app; developer guides explain how to build, extend, and contribute.
Published copy: GitHub Wiki (auto-synced from this folder on pushes to main that touch docs/**). Edit documentation here in the repository, not in the wiki web UI.
Doc map
Start here: Getting Started → Workspaces → Agent Harness
| Topic | Guide |
|---|---|
| Settings (API Keys, BLXCode Agent (text/image/voice, MCP, HeartBeat, Memory, Code Editor), Workspace, Appearance / themes, Help/About, App log) | Settings · Appearance & Themes |
| Workbench, terminals, sidebar, Git diff/sync, handoff, app status line, sidebar context drag-and-drop | Workspaces |
| Remote workspaces over SSH (connections, terminals, file/git, resume) | Remote (SSH) |
| File preview (images, video, Markdown, Mermaid, Vim mode) | File Preview |
| Memory, learnings, architecture map, graph, Memory Indexer (HeartBeat), Memory settings pane | Memory And Tasks |
| Markdown plans, plan-linked tasks, Multi-Kanban, Mermaid diagram gallery | Plans |
| Workspace rules and skills | Rules And Skills |
| Core skills (incl. MCP, prompt-generating), shell/git/web tools | Agent Harness |
| Coordinated subagents (scout/review/security) | Subagents |
| Tmux vs legacy shortcuts, Create Workspace, Push-to-Talk | Keyboard Shortcuts |
| Image generation mode | Image Mode |
| Providers, API keys, context, hooks, MCP servers, agent nickname, onboarding | Agent Providers |
| Voice STT/TTS, Push-to-Talk (local Whisper / cloud) | Voice |
| UI language and EULA | UI Language |
| Build from source | Building |
| Common issues | Troubleshooting |
User docs
- Getting Started — prerequisites, run BLXCode, first workspace, where data lives, welcome-screen Create Workspace, per-agent model/effort fleet.
- Settings — docked center-tab settings, API Keys, BLXCode Agent (text/image/voice), MCP, HeartBeat, Memory, Code Editor (Vim), Workspace, Appearance / themes, Help/About, App log, Notifications.
- Appearance & Themes — theme picker, presets, persistence, exceptions, font size.
- Workspaces — creation, terminal grids, sidebar explorer, File Diff (stage/commit/push), Git graph (fetch/pull), handoff, persistence, app status line, sidebar context drag-and-drop (Files / Folders / Diffs / Commits), hook install dialog, named terminals.
- Remote (SSH) — Settings → Remote connection presets (password / key / agent, encrypted secrets), creating remote workspaces, remote terminals + file/git + session resume (tmux vs keepalive).
- File Preview — center-tab previews for images (incl. SVG), video, rendered Markdown, syntax-highlighted source code, and Mermaid diagrams. Vim mode via
@replit/codemirror-vim. Repository policy docs (LICENSE,CONTRIBUTING,SECURITY,CHANGELOG, …) render as Markdown with a kind-specific hero banner — with or without a.mdextension. - Memory And Tasks — Memory panel (Files, Graph, Search), architecture map, dynamic categories, tasks, agent memory tools, Memory Indexer (HeartBeat), Memory settings pane.
- Plans —
.agents/plans/<slug>/plan.md, auto-maintainedPLANS.mdindex, workspace Multi-Kanban, Mermaid diagram gallery, task syntax, Plans panel, agent tools. - Rules And Skills — expandable rule/skill cards, core vs user skills, install dialog.
- Agent Harness — core skills (incl. MCP, prompt-generating), slim prompt, environment/shell/git/web, web API keys.
- Subagents — parallel runs, roles, timeline, tool groups, limits.
- Keyboard Shortcuts — tmux prefix vs legacy chords, notification toasts, Create Workspace, Push-to-Talk.
- Image Mode — generate images from the agent panel, settings, limits, persistence.
- Agent Providers — OpenRouter, Anthropic, OpenAI-compatible + Ollama / LM Studio / Hugging Face / Cloudflare / Together / Portkey / custom, MCP servers, agent nickname, onboarding, sidebar context kinds.
- Voice — STT, TTS, microphone, Push-to-Talk (local Whisper / cloud).
- UI Language — locales, language picker, EULA localization.
- Building — Linux, macOS, Windows release builds.
- Troubleshooting — startup, build, browser, keyring, terminal issues.
Developer docs
- Setup — local environment and verification commands.
- Architecture — frontend/backend split, agent, memory, plans, handoff, diagrams, HeartBeat, Memory Indexer, MCP, Kanban, Mermaid, Notifications, App log, App status line, sidebar context drag-and-drop.
- Agent Harness — core skills (incl. MCP, prompt-generating), tool dispatch, web settings, text-provider registry, MCP module, extension guide.
- Subagents —
subagents.run, runner, protocol, tool groups, new roles. - Tauri IPC — command registration, wrappers, command groups, HeartBeat / Memory Indexer / MCP / Kanban / Mermaid / Notifications / App log commands.
- SSH Remote Transport — wrapped-
sshterminals, persistent exec channel, fs/git remote routing, secrets, resume, teardown, russh follow-up. - Voice Architecture — STT/TTS modules and flows.
- Internationalization — locales, EULA content, translation workflow.
- Themes — tokens,
ThemeService, adding themes, lint rules. - Contributing — code style, rules, testing, pull request checklist.
Project principles
BLXCode is a local-first desktop workbench. Workspaces, terminals, memory, plans, tasks, and agent context stay close together without hiding where data lives on disk. When behavior changes, update the docs beside the code so users and contributors can move forward without reverse-engineering the app.
Release notes
User-facing notes for each version live in docs/releases/ (for example v0.5.0.md). Prereleases use their exact tag filename as well, such as v0.5.1-pre.ed4dc.md. They power the in-app What's new dialog after updates and should stay non-technical. The technical changelog remains in CHANGELOG.md at the repository root.