# 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](../account/free-tier.md) 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](../commands/adding-removing.md)
* [agents](../agents/what-are-agents.md)
* [terminals](../terminal/basics.md)

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](../commands/auto-start.md) or [auto-restart](../commands/auto-restart.md) when configured.
- Must be [trusted](../commands/trust-security.md) 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. On **Settings > Features > Todos** and **Settings > Features > Scratchpads**, the **Show in sidebar** controls determine whether their respective sections appear; **Enabled in MCP** is separate. Each page also has an on/off switch that hides the feature throughout Solo while keeping its data.

## 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](../settings/sidebar-settings.md) can hide empty sections, and **Settings > Features > Todos** and **Settings > Features > Scratchpads** can hide those 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.

---

Are you a human? Read this doc on the web: https://soloterm.com/docs/getting-started/concepts