agents-workspace

One root for every agents domain.

AGENTS_HOME grew from a memory override into a de-facto workspace root, but six domains never followed it. This package makes the root explicit and resolves every domain from it in one place.

from agents_workspace import Workspace

ws = Workspace.from_env()
ws.root          # AGENTS_WORKSPACE_ROOT, else AGENTS_HOME, else ~/.agents
ws.workdir       # AGENTS_WORKDIR, else AGENTS_WORKSPACE_DIR, else root/workspace
ws.memory        # AGENTS_MEMORY_PATH, else root/memory
ws.traces        # AGENTS_TRACES_DIR, else root/traces
ws.schedules     # AGENTS_SCHEDULES_DIR, else root/schedules
ws.personas      # AGENTS_PERSONAS_DIR, else root/personas

Domains

Precedence is always: explicit env, then the workspace default, then the global fallback. AGENTS_HOME and AGENTS_WORKSPACE_DIR stay readable as legacy aliases; new code writes AGENTS_WORKSPACE_ROOT and AGENTS_WORKDIR.

Registry

Additional workspaces live under AGENTS_WORKSPACES_DIR (default ~/.agents-workspaces). Workspace.list_all() returns the default workspace plus every child with a workspace.json. Workspace.resolve(ref) matches an id, label, directory name, or path. Workspace.create(label) mints a slug directory and initializes it.

CLI

agents-workspace info
agents-workspace path traces
agents-workspace init --label personal
agents-workspace list
agents-workspace create --label personal
agents-workspace migrate --dry-run

migrate moves legacy ~/.agents/<domain> directories into the workspace when the workspace root is not ~/.agents and the target does not exist yet.

What this is not

• No daemon, no network, no keyring.
• No persona logic. Personas are a domain path.
• No config schema beyond workspace.json.