User scope
Run sessions, Loops, terminals, tasks, and automations that belong to no project — in your home folder, without registering it as a project.
Not every piece of work belongs to a repository. Planning your week, triaging an inbox, asking an agent to compare two projects, or running an always-on assistant: none of that has a project folder.
The User scope is where that work lives. Each profile has one. Work in it runs in your home folder (configurable), loads your personal configuration, and never registers a project. It shows up under User in the workspace switcher and is labeled User wherever lists mix projects.
New here? Start your first User session. It takes about five minutes.
What runs in User
| Works in User | Not available in User |
|---|---|
| Sessions: create, prompt, resume, fork, child sessions, and Goals | Worktrees |
| Loop runs and requests | Workspace settings and workspace removal |
| Terminals and their journal | Workspace and workspace-profile config layers |
| Tasks and automations that target no project | |
| Heartbeat and soul of User sessions |
User work reads configuration from the bundled, marketplace, user, profile, and agent-local layers. Project overlays never apply, even when the work directory contains a project.
Where User work runs
[user_scope]
work_dir = "~"The work directory defaults to your home folder. A profile overlay can give each profile its own. The
value must be an existing absolute folder after ~ is expanded; otherwise new User work fails with
user_scope_work_dir_invalid, while existing User work stays listed. Changes apply to the next start.
See [user_scope].
Addressing User: @user
@user is the explicit name of the User scope. Use it anywhere a workspace is accepted.
| Surface | Form |
|---|---|
| CLI | --workspace @user, or compozy session new --user |
| HTTP/UDS paths | /api/workspaces/@user/... |
| HTTP/UDS query | workspace_id=@user or workspace=@user |
| Native tools | "workspace": "@user" |
| Session create | {"scope": "user"} on POST /api/sessions |
@user always means the User scope of the profile you are acting as. An empty workspace value never
means User. In responses, User items have an empty or absent workspace_id; sessions also carry
"scope": "user". Task and automation scope inputs accept user, @user, or global; rows keep reporting
"scope": "global" for the same thing. Scope is set at creation and cannot be changed by an update.
Who can reach User
User is a scope of its own. A User session's own scope is User of its profile; every registered project is foreign to it, including folders inside the work directory. A project session that lists User sessions, spawns into User, or opens a User terminal is crossing too. Both directions follow the session's permission mode, unless the agent holds the unrestricted grant. You, the operator, reach everything.
Errors
| Code | When |
|---|---|
session_create_scope_conflict | scope: "user" was sent together with a workspace, path, or worktree field. |
user_scope_worktree_unsupported | A worktree route or worktree parameter was addressed with @user. |
user_scope_unsupported | @user was sent to a route that only makes sense for a project. |
user_scope_work_dir_invalid | [user_scope] work_dir is missing, relative, or not a folder. |
workspace_home_forbidden | You tried to register your home folder or COMPOZY_HOME as a project. |
workspace_name_reserved | A new project name is user, global, or starts with @. |
Upgrading from v0.3
Earlier releases ran personal work inside a hidden project at COMPOZY_HOME (usually ~/.compozy).
The first v0.4.0 start moves that work into the User scope of each profile that owns it, copies its
terminal history and desktop layouts, and then removes the hidden project. Nothing is deleted:
anything that cannot move is kept in an archive table. If the hidden project had worktrees, or a
Loop-targeting automation points at it, it stays an ordinary project instead. Projects named user,
global, or starting with @ are renamed, and the old name keeps working with a warning until
v0.5.0. The migration guide has the details.
In this section
- Start your first User session — Web and CLI walkthrough with expected output.
- Give an agent access to everything — the
workspace_access: unrestrictedgrant.
Related pages
- All projects — see User work next to every project.
- Permissions — how sessions cross scopes.
- Profiles — each profile has its own User scope.
Read every project from the CLI and HTTP
List sessions, Loops, Goals, tasks, automations, worktrees, terminals, and agents across every project with --all-workspaces and all_workspaces=true.
Overview
Run sessions, Loops, terminals, tasks, and automations that belong to no project — in your home folder, without registering it as a project.