Concepts
mocante organizes your work with five ideas: hosts, projects, workspaces, sessions and tabs. Knowing how they fit together helps you decide where to put things and read what the app shows you.
The five building blocks
Section titled “The five building blocks”| Concept | What it is |
|---|---|
| Host | A machine that runs sessions: your own machine, or one you reach over SSH. |
| Project | A group for one client or product. It has a name, a base directory and a default host. It exists only in mocante. |
| Workspace | One directory on one host, usually a git checkout. The same repository on two hosts is two workspaces. |
| Session | One tmux session that belongs to a workspace. On a git workspace it usually works in its own worktree and branch. |
| Tab | One window inside a session: a shell, or an agent that mocante detected in it. |
A project holds workspaces, a workspace holds sessions, and a session holds tabs. Each workspace sits on exactly one host.
Your own machine is always a host. You add remote hosts on the Hosts page with an SSH address, and mocante uses your ~/.ssh/config to reach them. Every host needs tmux. See remote hosts.
A host is in one of these states:
- connected: mocante can reach it and see its sessions.
- connecting: mocante is trying to reach it.
- unreachable: mocante cannot reach it over the network.
- needs you: the host answers, but SSH needs something from you, such as a changed host key, a locked SSH agent, or a missing tmux. The Hosts page shows the SSH output and offers Log in over ssh… so you can fix it.
While a host is unreachable or needs you, its sessions show host offline. They are still running on the host if the host is up; mocante just cannot see them.
Projects and workspaces
Section titled “Projects and workspaces”A project is only a label for a group of workspaces. Creating or deleting a project changes nothing on disk.
A workspace points to a directory that already exists on its host. When that directory is inside a git repository, the workspace is a git workspace and you get worktrees, the git panel and the code view. Git is optional: a plain folder works too, and its sessions simply take a name.
Paths are stored as absolute paths on the host. A ~ you type means the home directory of that host, not of the machine you type on.
Sessions
Section titled “Sessions”A session is a real tmux session on the workspace’s host. That is why it survives when you quit mocante, when your laptop sleeps, or when an SSH connection drops. Open the app again and mocante finds it.
On a git workspace, a new session gets its own worktree: a separate directory with its own branch. Several agents can work on the same repository at the same time without changing each other’s files. A session on the main branch runs in the checkout itself.
tmux sessions that you started outside mocante show on the Hosts page, and you can adopt them into a project.
Each tab is a tmux window in the session. A new tab is a shell. When you start an agent such as claude, codex, opencode or pi in a tab, mocante detects it and shows the agent and its status on the tab. See agents and terminals.
Status
Section titled “Status”Each agent tab has one of five statuses, from most to least urgent:
- needs input: the agent waits for you, for example to approve a tool call or answer a question.
- error: the agent stopped with an error.
- working: the agent is busy.
- completed: the agent finished its task.
- idle: nothing is happening.
A session shows the most urgent status of its tabs. If one tab needs input and another is working, the session shows needs input. The sidebar counts the sessions that wait in each project, and the fleet view sorts agents in this order so the ones that need you come first.
What syncs between devices
Section titled “What syncs between devices”If you use mocante on more than one device, your projects, workspaces and hosts can sync between them. Sessions and their status do not sync: each device reads them live from the hosts. Settings stay on each device. See multi-device.