Workspaces and tasks

This page explains workspaces (registered git repositories) and tasks (one worktree and branch each) in sMind by Spacing Mind, plus chat, attachments, the prompt queue, spaces, pinning and archiving. It is for everyday users of the web app and CLI.

sMind by Spacing Mind, version 0.17.0. This page describes the 0.17.0 release.

A workspace is a git repository you registered with smind. A task is one unit of work inside it: smind gives each task its own git worktree and branch, so agents never touch your main checkout. You talk to the agent in a chat on the task.

Workspaces

The repository must already exist and be a git repository.

In the web UI, click the New workspace (+) button in the sidebar header, enter the Path (or use Browse…), optionally a Title, and click Create workspace. Without a title, smind uses the folder name.

From the command line:

smind workspace create ~/code/my-app my-app hard
smind workspace ls

workspace create takes the repository path, a name and a policy word. It prints the new workspace id. You need the id for the other commands.

A workspace can also run setup and teardown scripts in each task worktree. See smind workspace setup show|set|clear in the CLI reference, or Worktree settings in the workspace's row menu in the sidebar.

To see whether a repository is set up for agents, run smind workspace readiness [workspaceId] (or open Worktree settings and read Agent readiness). It reads the repo's files only, and never runs any of its scripts or touches the network. It lists what is there (agent instructions, a test and a lint command, a setup script, a .gitignore, CI, docs, lockfiles) and what is missing, with a one-line hint for each gap. In a monorepo it also looks one level into package folders (apps/*, packages/*, workspaces entries) for test scripts and lockfiles. Type checking alone does not count as a lint or format command. Warnings are advice; they never block a task.

To remove a workspace, use Delete workspace in the same menu. This only removes it from smind. Files on disk stay, and uncommitted work in task worktrees is saved to each task's branch first.

Tasks

Create a task in the web UI with Add task in the workspace's row menu (or New task in the command palette). Give it a Title. The dialog also asks where to start from:

• Workspace HEAD: a new branch off the workspace's default base.
• Branch…: pick a branch, then New branch from it or Check it out.
• Pull request…: build from a GitHub pull request.
• Issue…: start from a GitHub issue. Its title and link are put in the first prompt for you to edit.

The pull request and issue pickers need the GitHub CLI (gh) on the daemon's machine.

From the command line:

smind task new 1 "Fix the login bug"
smind task new 1 "Try the new API" --base origin/main
smind task new 1 "Review the fix" --branch fix/login
smind task new 1 "Pick up the PR" --pr 42
smind task new 1 "Sub-task" --parent 3
smind task new 1 "Cheap experiment" --budget 5
smind task ls 1

Flag	What it does
--space <spaceId>	Put the task in a space.
--parent <parentTaskId>	Make it a sub-task of another task. By default a sub-task branches from the parent's branch (see Git and pull requests).
--base <ref>	Fork a new branch at this ref. Use origin/<name> to start from the remote branch; the daemon fetches it first.
--branch <existingBranch>	Check out an existing branch with no new branch.
--pr <number>	Build from a GitHub pull request.
--budget <usd>	Cap the reported cost of the task and its sub-tasks. Root tasks only.

Use at most one of --base, --branch and --pr. smind task new prints the task id, its branch and its worktree path. smind task ls lists live tasks; add --archived or --all for archived ones, or --json for scripts.

To see the hierarchy with run state and cost, run smind task tree <workspaceId>.

Chat

Each task starts with one chat. In the web UI, type in the composer at the bottom of the task and press Enter to send. The composer lets you pick the provider, model, thinking level and permission mode for the run. Esc stops the running turn.

A task can have more than one chat. Use New chat in the tab bar to start another, so side questions do not clutter the main thread. Archiving a chat keeps its history on the task.

From the command line:

smind task send 1 claude-native "Add a unit test for the parser"
smind task send 1 claude-native "Now fix the failures" --chat <chatId>
smind task runs 1
smind task logs <runId> --tail 50

task send starts a run and streams its output. Press Ctrl+C to detach; the run keeps going. Add --detach to start the run and return right away. Other useful flags are --mode <permissionMode>, --auto-accept, --model <model> and --thinking off|standard|extended. The provider names are the ones listed under Settings → Providers. See Providers.

Attachments

The composer takes images, files and references.

• Attach button (paperclip), then Image or file…: choose files from disk. You can also drag files onto the task pane ("Drop to attach") or paste a screenshot.
• Attach → Mention a file, or type @ in the composer: pick a file in the task's worktree. The agent gets the path, not a copy.
• Attach → GitHub pull request… and GitHub issue…: search, or paste a number or URL. These entries need gh; without it they show as disabled with the reason.

Each attachment shows as a pill above the text box. The composer marks a pill that breaks a limit, and Send stays disabled until you remove it. The daemon's default limits:

• Up to 10 attachments per message.
• Images: PNG, JPEG, GIF or WebP, up to 5 MB each.
• Files: up to 10 MB each.
• 10 MB in total per message.

When you re-run a message, its earlier attachments go along.

Queue and when-busy

A chat runs one turn at a time. When you send a prompt while a run is active, the when-busy mode decides what happens:

Mode	Behavior
reject	The send fails. This is the default for smind task send.
queue	The prompt waits and runs when the current run finishes, in order.
interrupt	The prompt goes first and stops the running turn.

smind task send 1 claude-native "Also update the docs" --when-busy queue
smind task queue ls --chat <chatId>
smind task queue cancel <itemId>

In the web UI, the send button becomes Queue while a run is active, and Enter queues the prompt. Send now (⌘/Ctrl+Enter) interrupts the running turn and sends. Queued prompts are listed above the composer; cancel one from its row.

Right after you create a task, its workspace setup script may still be running. smind task send then queues the prompt for you and starts it when setup finishes.

Continue a failed run

A run can stop before it is done: at the output limit, at the tool-turn limit, at the budget limit, or when the daemon restarted under it. The run footer says so ("Stopped at the output limit", "Hit the tool-turn limit", "Stopped at the budget limit", "Interrupted when the daemon restarted") and shows a Continue button on the chat's latest run.

Continue sends the prompt "Continue" with the run's own provider, model and thinking level. It is queued if the chat is busy.

Spaces

A space groups tasks inside a workspace. It is not a separate repository.

smind space create 1 "Release 2"
smind space ls 1
smind task new 1 "Write changelog" --space 1

In the web UI, use Add space in the workspace's row menu. Move a task with Move to space in its menu; Ungrouped takes it out of a space. Delete space keeps its tasks and makes them top-level.

Pin and archive

Pin puts a task in the Pinned section at the top of the sidebar. Use Pin or Unpin in the task's menu. Pins are stored in your browser, so they do not follow you to another device. A pin is dropped when the task is archived.

Archive removes the task's worktree and hides the task. In the web UI use Archive task in the task's menu. From the command line:

smind task archive 3
smind task archive 3 --delete-branch
smind task archive 3 --delete-branch --force

Before it archives, smind lists what is at risk (the CLI prints the same lines as the web dialog):

• Uncommitted changes. They are saved to the branch first.
• Commits that are not pushed, or only on this machine because the branch was never pushed.
• A branch that is not merged anywhere.
• Files git ignores (such as node_modules and .env). They are not kept.
• The workspace's teardown script, if there is one, runs first.

Archiving does not delete the branch unless you ask. --delete-branch (or the Delete branch checkbox) removes the local branch when it is merged, clean and checked out nowhere else. --force (the Delete the branch anyway option) also deletes a branch that is not merged or has uncommitted changes. A branch that smind did not create is never deleted, and branches on the remote are never touched.

If the task has sub-tasks, the web dialog offers Archive parent only and lists the children. To bring an archived task back, see Archive and restore.

Scratch directories

Every agent run gets a private scratch directory, $SMIND_HOME/scratch/<task id>/, and smind points TMPDIR (and TMP and TEMP on Windows) at it. Anything the agent creates with mktemp -d, such as a temporary HOME for a hermetic test run, then lands there and belongs to that task. If you pin TMPDIR in a provider's env, your value wins.

Archiving or deleting a task removes its scratch directory. smind never follows a symlink out of it, and a task with a running run is left alone. At startup, and every ten minutes after, smind also removes scratch directories of tasks that are archived, deleted or unknown.

smind scratch usage     # total size, and how much belongs to closed tasks
smind scratch clean     # remove the scratch of archived tasks now

Settings -> General has a Scratch space card with the same numbers: disk used, how many task folders and files that is, and how much of it belongs to archived, deleted or unknown tasks. Clean up removes those. It frees what it can and tells you how much; a folder whose task still has a run is skipped and the card says how many were kept, so clean up again once that run ends. See agents.sharedCaches in Configuration for the shared build caches.