Docs

sporemind feature guide: from install and setup to workflow orchestration.

Quick start

First launch opens the onboarding guide automatically. Complete these steps in order to get started.

Download & install
Download the Windows x64 build from the home page, unzip and run. First launch opens the onboarding guide; no account required.
Configure a model provider
Onboarding step 1. Pick a preset provider (OpenAI, Anthropic, DeepSeek, Zhipu GLM, Doubao, Kimi, 30+), paste the API key, fetch the model list, check the models you want and save. For local models pick the Ollama or LM Studio preset — no key needed.
Create your assistant
Onboarding step 2. Give the coordinator a nickname and pick a model, then create. The coordinator is your global entry-point agent, callable by nickname.
Send your first message
Type in the composer and send with Ctrl+Enter. Default permission mode is "Ask first" — tool calls pop a confirmation before running.
Launch a workflow
Type /workflow followed by your goal. The agent factory breaks it into task cards with dependency edges, activates on confirmation, worker agents run in parallel, and you review and merge each result.

Agents & Projects

A project is the container agents work in. File reads, writes and command execution all happen within a project. Each agent has its own model, tool permissions and session.

New project: Click "Add project" in the sidebar. Open an existing folder or start from scratch. Projects are isolated from each other.
New agent: Inside a project, click "New agent". Pick an agent kind (e.g. coder), a display name and a model to create.
Advanced config: Expand "Advanced" to set the allowed-callable whitelist, auto-allowed tools, compaction toggle and token budget.
Clone & fork: Existing agents can be cloned (copy config) or forked (create an independent branch from the config) for quick reuse.

Chat & permission modes

Permission modes control how autonomously an agent runs tool calls. The button on the right side of the Composer switches modes, at two levels: current agent and global default.

Five modes: Ask first (default): confirmation popup on every tool call. Autopilot: autonomous, fast-model guards calls. Auto: fast model decides. Allow all: auto-approve tool calls. YOLO: auto-approve plans, goals and tool calls, no questions.
Dangerous mode confirmation: Switching to "Allow all" or "YOLO" pops a confirmation dialog; you must confirm manually for it to take effect.
Sending messages: Ctrl+Enter to send. The composer supports up/down arrows to browse input history.

Modes

A mode is a mountable card: mounting changes how the agent works and grants the mode dedicated tool set. Each mode covers one way of driving work — orchestration, goals, scheduling, memory.

Usage: Type the mode slash command (/workflow, /goal, …) to mount, or mount/unmount manually in agent settings. Mounting takes effect immediately: the composer switches to the mode placeholder and shows a mode badge.
Mutual exclusion: Orchestration-group modes (workflow / goal / scheduler) are mutually exclusive: mounting one automatically unloads the others in the group. Non-orchestration modes like memory stack freely with any mode.
Unload & cleanup: Unmounting withdraws the dedicated tools; built-in-scope dependencies are preserved, user-scope ones removed with it. You can unload all modes to reset agent behavior — session data is unaffected.

workflow · Orchestration

A workflow is a task graph: task cards connected by dependency edges. Ready tasks are dispatched to worker agents automatically. Best for exploratory tasks whose goal is clear but the path to it is unknown — complex and requiring dynamic planning.

Starting a workflow: Type /workflow followed by your goal in the composer. The agent factory generates a workflow map (task cards + dependency edges), activates on confirmation, and the agent becomes the map owner.
Auto dispatch: Frontier tasks whose dependencies are all done are dispatched to worker agents automatically. Each worker runs in its own git worktree without conflicts; projects without git fall back to no-Git mode, running directly in the project root.
Review & merge: Finished workers enter pending_review. Click review to inspect the changeset (file changes, commits, untracked files), merge the branch or reject with feedback. When all workers are reviewed and the goal is met, call workflow_stop to finish and merge.
Pause & resume: Workflows can pause. While paused you can adjust the task tree (add/remove cards, change dependencies), then continue. Orphaned tasks (pending review whose owner is gone) are detected and re-disposed automatically.

goal · Goal mode

Goal mode keeps the agent pushing toward one explicit goal until acceptance criteria are met — for long-running work across many turns, not a single Q&A.

Mount & describe: Type /goal to mount; the composer switches to "Describe what you want to achieve…". Write the goal and acceptance criteria — the more concrete, the better.
Goal confirmation: The agent turns the goal into an executable interpretation and plan, and starts after your confirmation; under auto-approve / YOLO permission modes plans and goals are approved automatically.
Assign goal: Right-click a card in the topology view → "Assign goal" to hand an existing card to an agent as its goal — turning settled knowledge into action.
Progress & completion: The agent progresses across turns, writing milestones into cards; when the goal is achieved or abandoned it exits the mode and returns to normal chat.

scheduler · Scheduler mode

Scheduler mode runs tasks on a time plan: prompt tasks and agent tasks triggered at fixed times or intervals, with plans and execution records in a dedicated schedule view.

Mount: Type /scheduler to mount (or mount in agent settings); the agent session binds to the active scheduler.
Scheduled tasks: Two task types fire on schedule: prompt tasks (inject a prompt at the scheduled time) and agent tasks (drive the agent to execute).
Idempotent execution: Scheduled runs are strictly scoped to the task body: no spread, idempotent, results recorded — repeated triggers cause no side effects.
Schedule view: Open the schedule view in the sidebar to see all plans, next trigger times and execution records in one place.

memory · Memory mode

Memory is an agent mode (Memory Mode). Once mounted, the agent accumulates memory nodes through conversations and knows your project better over time; unmounting permanently deletes all memories.

Three layers: Memory nodes fall into three layers: session (current-session detail), experience (distilled experience), ontology (core knowledge). Layers are ranked by RecallScore and injected into different parts of the agent context, recalled automatically when relevant.
Mount & unmount: Mount Memory Mode in agent settings to start accumulating. Unmounting permanently deletes all of that agent memories — irreversible; deleting an agent warns that its memories go with it.
Mind map: With Memory Mode mounted, open the mind map to visualize memory structure (unmounted prompts you to mount first). Nodes support custom icons and colors.
Consolidation: Type /dream to trigger memory consolidation: merge redundant nodes, promote layers (session → experience → ontology) and connect nodes. Low-energy nodes decay naturally over time.

Model providers

Manage model providers in Settings → Model providers. Each agent specifies its own model, switchable at runtime.

Provider presets: 30+ built-in presets: OpenAI, Anthropic, DeepSeek, Qwen, Kimi, Zhipu GLM, Z.ai, Gemini, Mistral, xAI, Doubao, Hunyuan, ERNIE, MiniMax and more. Pick preset → paste key → fetch models → check → save.
Custom endpoints: Any OpenAI / Anthropic / Gemini-compatible endpoint. Enter the URL; the protocol is inferred from the endpoint.
Local models: Ollama and LM Studio have ready-made presets with no API key required. Models run on your machine.
Aggregators & units: Aggregators merge multiple providers into one entry point. A model unit = (model, provider) tuple, the smallest selectable primitive. Each agent picks its own unit, switchable at runtime.

Capability bundles

A bundle (tool pack) is a mountable card that packages a set of tools: mounting grants the agent that tool set. 28 built-in bundles cover screen, browser, search, files, shell, Git, knowledge, planning, forking, apps, UI, media, MCP, native dev and more. Mode-shipped bundles (e.g. workflow mode carries workflow-tools) mount with the mode.

Usage: Mount/unmount tool packs in agent settings; modes also bring their required packs (mounting the mode grants its capabilities). Browse and filter packs under the sidebar "Bundles" category.
Runtime self-mount: The bundle-use bundle lets the agent discover available capabilities and self-mount on demand in conversation, filling in tools needed for the current task — no need to pre-configure everything.

Computer Use

Agents can capture the screen and operate the desktop: see the interface like a human, use the mouse and keyboard to work with application windows.

Screen capture & windows: Capture the full screen or a region; screenshots carry coordinate grid labels. Capture specific windows, list current windows and displays.
Desktop operation: Move the mouse, click, type text and press keys to operate desktop windows — filling forms, clicking buttons, installing software.
Element recognition & OCR: Recognize controls and text (OCR) to precisely locate interface elements, combining with screenshots for stable operation.

Browser operation

Three sets of browser capabilities: open pages, structured DOM automation, and resumable crawling.

Open pages (browser-tools): Open URLs or local files in the shared browser tab for visual viewing; does not operate the DOM.
DOM automation (browser-use): Observe page elements → click → type → scroll → navigate. Precise web page operation for forms, data extraction and flows; pages open in the embedded browser window, fully visible.
Resumable crawl (browser-crawl): Start a crawl task for paginated scraping with pause/resume and result handoff, suited for large-scale collection.

Web search

Web-connected search: search, fetch page text and download files as a complement to local knowledge.

Search: Return structured results (title, URL, snippet, source, publish date) ready to consume.
Fetch & download: Fetch page visible text and metadata; download files by URL to disk.

File system

Project file read/write and search; all operations are scoped to the project root.

Read/write/edit: read / write / edit with offset, pagination, append and tail; edit uses exact-text replacement.
Search: grep (regex search file content), glob (file name matching), list / list_json (directory tree).
Delete: rm removes files or directories (recursive).

Shell & Git

Run shell commands in the project directory and full Git operations.

Shell (shell-tools): Run builds, tests and scripts; supports working directory and timeout.
Git (git-tools): status / log / diff / add / commit / push / pull / branch / checkout; shares source with the Git panel.

Project knowledge

Read/write project knowledge cards and semantic graph snapshots.

Knowledge cards (project-wiki): create / edit / search / delete cards, summary & constraints, open & save tabs, dispatch plans.
Semantic graphs (graph-tools): read/write project graph snapshots (charter / target / phase / reality / diff / moves / projection), read nodes by concept ID.

Planning & tasks

Planning and task tracking: submit plans, create and update tasks for multi-step work.

Plan: plan_submit submits a structured plan for approval; once approved it becomes executable.
Task: task_create creates a task, task_update updates its status (pending / in_progress / completed).

Agent forking

Spawn child agents to handle independent subtasks, each executes in isolation and reports back.

Explore (fork-explore): Read-only child for complex code, dependency or runtime investigation; returns a summary.
General (fork-general): Child with full tool surface for self-contained implementation / editing / verification tasks.
Review (fork-review): Independent reviewer child that checks the codebase against acceptance criteria and returns a factual summary.
Memory dream (fork-dream): Internal memory consolidation route, not directly exposed.

Workspace & apps

Manage the workspace and registered applications.

Workspace (workspace-tools): List projects, agents and accounts.
Apps (app-tools): list / get / invoke / register / reload applications.

UI control

Control frontend UI elements and query interaction state for UI automation and guidance.

Interface control (interface-controls): control dispatches commands, query_interactions queries interactions; pairs with workspace.create / create_agent to create projects and agents.

Media generation

Text-to-image and text-to-video generation.

Text-to-image (image-gen): Generate or edit images from prompts.
Text-to-video (video-gen): Generate videos from prompts.

Capability discovery

Discover available capabilities and self-mount at runtime — the agent "meta-capability".

Discovery & self-mount: List mountable bundles; self-mount on demand in conversation to fill in tools needed for the current task.
MCP server management: list / add MCP servers; dynamic tools appear as bundles.

MCP tools

Plug into the external tool ecosystem via Model Context Protocol. Configure once — every agent can invoke tools from your MCP servers.

Add a server: Settings → MCP → Add server. Enter the launch command (e.g. npx -y @modelcontextprotocol/server-everything), args and env vars; HTTP servers also support custom headers.
Connection management: Connect/disconnect manually; check "Enabled" to auto-connect on app startup. The server list manages all MCP instances in one place.
Agent invocation: Once connected, MCP tools appear in the agent tool list automatically ("MCP tools") and can be invoked in conversation without extra setup.

Native app development

Native plugin/app lifecycle: register, reload, load/unload for developing and debugging your own native plugins.

Lifecycle: Register projects, reload, plugin load / unload (native-app-dev).
Use case: Develop, hot-reload and debug your own native plugins in-app, without a separate toolchain.

SSH remote management

Manage remote hosts inside the app: connect over SSH, run commands, browse and edit remote files. Agents can also open SSH sessions to work on remote machines for you.

Host management: Settings → SSH management → Add host. Group hosts into folders; the list stores addresses and auth config, ready to connect or disconnect anytime.
Built-in terminal: After connecting you get a terminal with command history, in-terminal search and command favorites; one-click reconnect on disconnect.
FTP file browser: Browse remote files in a directory-tree view: create/delete/rename, edit file contents, change file permissions.
Agent remote execution: Ask an agent to open an SSH session: it can run commands on the remote host and read results — deployment, troubleshooting and log inspection all work remotely.

Git panel

A built-in visual Git panel: commit history, branch graph, stage/commit/push — everyday Git without opening a terminal.

History & branch graph: Graphical branch topology; filter commits by author/date/message; click a commit or file to view the full diff.
Stage & commit: Review changes, stage or unstage files individually or all at once; commit with a required summary; create new branches.
Push & pull: Fetch, pull, push and refresh from the panel; remote and local branches are listed separately.
No-Git mode: Settings → Git → No-Git mode: workflows run directly in the project root without creating a git worktree. Activates automatically when the project has no git repository.
Identity & proxy: Settings → Git configures the commit username/email, HTTP/HTTPS proxy and remote repository URLs.

Mobile sync & remote access

Connect to your desktop instance from a phone browser or client: direct LAN access or FRP tunnel, scan a QR code to start.

LAN access: Settings → Mobile sync → enable LAN access. The gateway binds to the LAN IP; phones on the same Wi-Fi scan the QR to connect (takes effect after restart; only enable on trusted networks).
FRP tunnel: Configure the FRP server host, port, remote port and token, then create and start the tunnel for public-network access; quick config and history management supported.
Connection QR: The page shows a connection QR — phone browser or client scans to connect; the started FRP public address takes priority, falling back to the LAN address. A separate QR downloads the Android client APK.

Native plugins

Native plugins are written in compiled languages like Go, providing capabilities that need native ABI or existing local libraries. Tile badges indicate isolation and trust level.

Isolation badges: Launcher tile corner badges: green dot = subprocess (crash-isolated), amber dot = in-process (shares the host), red ring = untrusted third-party. Safety boundaries at a glance.
Theme mirroring: Plugin UI automatically mirrors the host dark/light theme and font size, effective instantly on switch.
Two run modes: Subprocess: separate OS process, crashes do not affect the host. In-process: shares the host process; unloading requires an app restart to fully remove (the UI prompts).

Slash commands & Omnibox

Type / in the composer to summon the command list. Cmd+K opens the Omnibox for global search.

Built-in commands: /help: list all commands. /clear: reset current conversation. /compact: manually compress context. /recompact: discard old summaries and re-compact from scratch. /dream: trigger memory consolidation (merge and promote memory nodes).
Mode commands: /workflow, /goal and others are mode commands: typing one mounts the corresponding mode, giving the agent its dedicated tool set and behavior constraints. Modes in the same orchestration flow group are mutually exclusive (mounting workflow unloads goal).
Skills as commands: Skill cards you create auto-register as slash commands; type /skill-name to invoke.
Omnibox: Cmd+K to open. Search and jump across projects, agents, cards and conversations.

Cards & topology

A card (mono card) is the basic information unit in sporemind: markdown body + YAML frontmatter (type, tags, status). The sidebar "Cards" tab browses all cards.

Card types: Wiki, concept, task, callable, skill, prompt, capability module, scheduler. Each type has its own filter entry in the sidebar.
Card status: Todo, doing, done, pending review, blocked, cancelled. Workflow task cards flow through these statuses.
Topology mode: Switch the sidebar to "Topology" to view the project card relationship graph. Right-click a card: add child card, add tag, assign goal, chat about this card (MiniComposer), copy path, delete.
WikiWord links: In card body, [[card-id]] creates an explicit link; CamelCase is auto-recognized as a card link. Cards form a bidirectional link network.