Understanding projects, processes, and sections

Solo organizes your workspace around projects. Each project can hold todos, agents, terminals, commands, and scratchpads in sidebar sections.

Projects#

A project is a folder on your filesystem. It can be a repository root, an plain folder, an empty folder, a monorepo, or any another type of workspace folder. Projects show up as collapsible blocks in the sidebar.

Solo uses the project path to:

• Set the working directory for commands it runs.
• Watch and sync a solo.yml file when one exists.
• Detect common project types and suggest commands during onboarding.

The free tier allows up to 4 primary projects; linked checkout/worktree projects do not count toward this quota. After four primary projects, adding another primary project opens the license prompt.

Processes#

Solo uses "process" as the shared term for anything it launches and manages:

• commands
• agents
• terminals

The free tier allows up to 20 processes. Starting or adding more requires a license.

Commands#

Think of commands as your local dev stack.

They are a named shell command that Solo manages for you, such as npm run dev, ./gradlew build, or a worker script.

Commands:

• Start, stop, and restart independently.
• Appear in the Commands section of their project in the sidebar.
• Can be saved in solo.yml or kept local to Solo.
• Can auto-start or auto-restart when configured.
• Must be trusted before Solo runs repo-derived command details.

When command details change in solo.yml, Solo may require you to trust the new command variant before it can run.

Agents#

Agents are terminal-backed AI CLI tools, such as Claude Code, Gemini CLI, OpenCode, Codex CLI, or a similar tool. Solo uses the local binaries on your machine and does not interfere, change, or capture any of your auth tokens or configurations.

Solo groups agents separately from commands and terminals:

• Agents appear in the Agents section.
• Solo shows live agent activity in the sidebar; unread attention notifications appear in both the sidebar and title bar.
• Closing any agent terminates its running execution. Stopping an agent terminates its PTY process.

Terminals#

A terminal is a plain interactive shell session you can type in freely. Terminals appear in the Terminals section.

Use terminals for one-off tasks, running commands manually, or exploring a project directory interactively without adding a permanent command entry.

Todos and scratchpads#

Todos and scratchpads are project-scoped workspace items. In Settings -> Notes & todos, the Todos and Scratchpads Show in sidebar controls determine whether their respective sections appear; Enabled in MCP is separate.

Sections#

Within each project, items are grouped into sections: Todos, Agents, Terminals, Commands, and Scratchpads.

Sections are collapsible and reorderable. Empty sections are shown by default, sidebar settings can hide empty sections, and Settings -> Notes & todos can hide the Todos and Scratchpads sections altogether.

How they relate#

Project (a folder)
├── Todos section
├── Agents section
│   └── Claude Code (agent)
├── Terminals section
│   └── shell (terminal)
├── Commands section
│   ├── dev server (command)
│   └── worker (command)
└── Scratchpads section
    └── notes (scratchpad)

Naming clarification#

When documentation says "process," it means a command, agent, or terminal. When it says "command," it means a non-agent, non-terminal shell command.