Setting up Space Command
Space Command lives in the menu bar, the Dock, and a panel at the edge of your screen. It reads the folders you choose and finds the projects, tasks, ideas, and posts in them. This guide takes you from opening the app to a panel full of your own work.
You need macOS 26 or later.
1. Open the app
To open the app:
- Move Space Command to your Applications folder.
- Open it.
The mark appears in the menu bar, and the app's icon in the Dock.
| To | Do this |
|---|---|
| Show the panel | Click the mark. |
| Hide the panel | Click the mark again. |
| Open the app's menu | Right-click the mark. |
The app's menu has Show Panel, Quiet Mode, Settings…, About Space Command, Space Command Help (these pages), and Quit Space Command.
2. Choose your folders
Space Command reads nothing until you choose a folder. Until then, the panel says "Add a folder to see its tasks."
To add a folder:
- Click Open Settings… in the panel, or press ⌘,.
- Click the Folders tab.
- Click +.
- Choose a folder you keep your work in, such as
~/projects,~/writing, or an Obsidian vault. - Click Add.
You can also drop folders from the Finder onto the Folders list.
Each folder shows "Scanning…" while the app reads it. When the first scan is done, the panel opens on Tasks: on the folder's project if it holds just one, otherwise on Today. The folder's row shows what it found: projects, an Obsidian vault, symlinked folders, or files not downloaded from iCloud.
A good first choice is the one folder that holds your repos. You can add more later.
To stop watching a folder:
- In Settings › Folders, select the folder.
- Click −.
Nothing in the folder changes.
What counts as a project
Space Command finds Git repos, Obsidian vaults, and Hugo sites. A folder you choose can be a project itself.
Some folders look like projects without being one, such as a folder with a PLAN.md or numbered chapters. Space Command suggests these under the All projects board, and they only become projects if you say so.
To answer a suggestion:
- In the Tasks tab, choose All projects from the scope menu.
- Find the suggestion under the board, such as "essays looks like a project".
- Click Treat as Project to make it one, or Not Now to put it away.
Press ⌘Z to take back a promotion you just made. Later, a project's right-click menu offers Stop Treating as Project.
Settings › Advanced › Hidden brings back a suggestion you put away.
Leaving folders out
Dot folders, node_modules, .build, and DerivedData are skipped everywhere, and so is anything your .gitignore names.
To skip more in one folder:
- In Settings › Folders, select the folder.
- Under "Ignored in", click +.
- Choose the folders inside it to leave out.
- Click Ignore.
The list is kept in a .spacecommand.toml file in that folder, so it travels with the folder. The same file can name test sites to keep out of projects, with not_sites (see Posts).
To skip a Git submodule:
- In Settings › Folders, select the folder.
- Find the submodule, marked "A submodule, from .gitmodules".
- Click Ignore.
Symlinked folders
Space Command doesn't follow symlinked folders on its own.
To watch where a link points:
- In Settings › Folders, select the folder that holds the link.
- Under "Symlinked folders", click Follow beside the link.
- Approve its target in the dialog that opens.
The target is listed under the folder it's linked from, marked "Followed from". To stop, click Unfollow beside the link.
3. Choose your editors
Items open at their line in the editor that fits where they live. Space Command tries these in order, and the first match wins:
| Order | Opens in |
|---|---|
| First | A project override from Settings › Open In |
| Then | The editor the folder's .spacecommand.toml names |
| Then | Obsidian, for Markdown in a vault |
| Then | Xcode, for source files in an Xcode project or Swift package |
| Then | VS Code, or another editor in its family, for a project with a .vscode folder |
| Then | A JetBrains IDE, for a project with an .idea folder |
| Then | Your code and Markdown editors from Settings › Open In |
| Last | The system default |
With Space Command for Obsidian on in a vault, a note opens with the cursor on the item's line. Without it, or with Warped Command older than 0.60.0, Obsidian opens the note at its top. The first time that happens, a card at the top of Tasks or Posts suggests the plugin: Get Plugin opens its page, and Not Now puts the card away.
To choose your editors:
- Open Settings › Open In.
- Pick your Code editor. The one Space Command found is marked "Detected".
- Pick a Markdown editor, or leave it as "Same as code editor".
To give one project its own editor:
- Open Settings › Open In.
- Under Project overrides, click +.
- Choose the project.
- Pick its editor.
4. Set a hotkey for the panel
The panel has no hotkey until you set one.
To set one:
- Open Settings › General.
- Under Panel, click the recorder beside "Show or hide the panel".
- Press the keys you want, such as ⌃⌥Space, which is free on most Macs.
The hotkey shows the panel, brings it forward when other windows cover it, and hides it when it's in front.
5. Mark your first focus
Space Command is built around one thing at a time. The focus leads every view, on the focus card at the top of the panel.
To set a focus in your files:
- Open a file with a task in any editor.
- Add #focus to the task's line.
- Save the file.
- [ ] Draft the chapter on starters #focus
If nothing has a focus, the card asks "What is your focus today?" once a day.
To pick a focus from the card:
- Click Select a #todo.
- Click the task you want.
Later puts the question away until tomorrow.
See Focus and calm for queueing several, and Tasks and ideas for the tags Space Command reads.
6. Allow the clipboard (optional)
The Clipboard tab cleans up what you copy. macOS asks every time an app reads the clipboard, until you allow it. Space Command only appears in macOS's list after the first time it asks, so start with a copy.
To allow access:
- Copy some text.
- Open the panel's Clipboard tab.
- Click the copy.
- Answer macOS's alert.
- Click Open System Settings on the card that appears.
- In Privacy & Security › Paste from Other Apps, set Space Command to Allow.
The tab notices the change right away. Until you allow it, each copy is read only when you click it. Text you copy shows on the tab while the panel is open, on any tab, or all the time with Settings › Clipboard › Keep copies while the panel is closed.
Menu bar or Dock
Space Command shows in the Dock and the app switcher, like any app, until you say otherwise.
With Settings › Appearance › Show in Dock and app switcher on:
- Clicking the Dock icon, or choosing the app with ⌘Tab, shows the panel.
- The menu bar has the app's own menus: Space Command, Edit, View, Window, and Help.
- Hiding the panel hides the app too, so you land back where you were.
Turn it off to keep Space Command to the menu bar alone. The mark and your hotkey still show the panel.
Settings › Appearance › Menu bar icon picks how the mark looks:
| Icon | Looks |
|---|---|
| Monochrome | The menu bar's own colour (the default) |
| Colour | The ␣ in Sage, the ⌘ in the menu bar's colour. With Increase Contrast on, it draws as Monochrome |
| Hidden | No mark. Offered only while Space Command is in the Dock or has a panel hotkey, so you can always reach the panel |
If you turn off the last of those while the icon is hidden, the mark comes back, and Settings says so.
Window buttons
The panel has two window buttons at its top left, red and green, as other Mac windows do.
| Button | Does |
|---|---|
| Red | Hides the panel, as ⌘W does. Space Command keeps running. |
| Green, on a docked panel | Floats it, in from its edge, at about two-thirds of the screen's height |
| Green, on a floating panel | Docks it to the nearer edge |
| ⌥-click green, on a floating panel | Makes it full height where it is |
A docked panel always stays over other apps' windows, on every desktop. A floating one stays over them only with Settings › General › Keep panel in front on.
The buttons are coloured while the panel is in front, and grey while it isn't. With them showing, About Space Command is in the ⋮ menu, in place of the 
badge. To turn them off, clear Settings › Appearance › Window buttons.
Other settings to know
| Setting | Does |
|---|---|
| Settings › General › Launch at login | Opens Space Command when you log in |
| Settings › General › Keep panel in front | Keeps a floating panel over other apps' windows. A docked panel always stays over them (off by default) |
| Settings › General › Show over full-screen apps | Lets the panel follow you into a full-screen app's Space. Off, it stays on your desktops, though the hotkey or the mark still shows it in a full-screen Space (on by default) |
| Settings › Appearance › Appearance | Picks System, Light, or Dark |
| Settings › General › Quiet Mode | Folds away projects with no recent activity (off by default; see Quiet Mode) |
| Settings › Appearance › Show a dot in the menu bar for #p0 tasks | Shows the Terracotta dot beside the mark, and a badge on the Dock icon, while any #p0 is open (on by default; see The menu bar dot) |
| Settings › Appearance › Show fewer animations | Fades the panel in place instead of sliding it, as with the system's Reduce Motion, without changing other apps (off by default) |
| Settings › General › Stale after and Docs may be out of date | Set when a project reads as stale, and when its docs may be out of date (30 days each, by default) |
| Settings › Appearance › Window buttons | Shows red and green buttons at the panel's top left: red hides it, green floats or docks it (on by default; see Menu bar or Dock) |
| Settings › Appearance › Dates | Picks how dates are written, and for how many days a date reads as relative, such as "2 days ago" (or always absolute) |
| Settings › Tasks › Add new tasks to | Names the file new tasks go to (TODO.md, by default) |
| Settings › Clipboard › Save references to | Names the file saved references go to (REFERENCE.md, by default) |
| Settings › Clipboard › Unindent ▸ On by default | Opens a copy with an indent to take out with Unindent on (on, by default) |
| Settings › Clipboard › Unindent ▸ Starts at | Picks the mode Unindent opens in (Flush, by default) |
| Settings › Clipboard › Keep copies while the panel is closed | Keeps copies with the panel hidden, once Paste from Other Apps is set to Allow (off, by default) |
| Settings › Clipboard › Latest copy in Today | Shows your latest copy under Today's focus card (on, by default) |
| Settings › Tasks › Task files | Turns well-known task files on or off, and adds a folder's own task formats (all well-known files on, by default) |
| Settings › Tasks › Clear finished items | Sets how long finished items stay in the list (until the next day, by default) |
| Settings › Advanced › Space Command for Obsidian | Shows how many vaults have the Obsidian plugin on, and whether any need an update |
| Settings › Advanced › Reset panel state | Starts the panel over, as on first launch, keeping your folders and settings |
Your files stay yours
Space Command reads your folders and never writes to them on its own. When you tick off a task or set a priority, it checks that the file hasn't changed since it read it, and changes only that line. Press ⌘Z to undo.
Nothing leaves your Mac. There's no account, no cloud, and no tracking. If you allow it, the app checks space-command.ca for updates, sending only its version number.