Workspaces

A workspace is the execution root for an agent — where it reads files, runs commands, and applies patches. Every agent always has exactly one active workspace.

What a Workspace Defines

Concern	Set by workspace
Instruction root	Where `AGENTS.md` and policy files resolve
Execution root	Default working directory for commands
ApplyPatch target	Where file mutations land
Memory scope	Workspace-scoped episode records and indexes

Workspace vs Shell Directory

A workspace is not a shell cd. Shell cd changes the directory for that one command process. Changing the active workspace requires holon workspace attach or the UseWorkspace tool — this redefines where runtime tools operate.

Action	Effect
`cd /other` in shell	Only affects that command
`UseWorkspace`	Changes active workspace for all subsequent operations
`holon workspace attach /path`	CLI equivalent of UseWorkspace

Workspace Commands

Attach

Attach to a project directory as the active workspace:

holon workspace attach /path/to/project
holon workspace attach --agent my-agent /path/to/project

This discovers or creates a workspace record for the directory and makes it active for the agent. The workspace persists across sessions.

Exit

Return to the agent's home workspace:

holon workspace exit
holon workspace exit --agent my-agent

Detach

Remove a workspace record entirely:

holon workspace detach <workspace-id>

Detaching does not delete the directory — it removes the workspace record from Holon's index. Memory and episode records associated with the workspace are preserved.

Workspace Modes

Direct Mode

The default. All operations happen in-place on the real filesystem:

holon workspace attach /home/user/project

Use direct mode for normal development work where you want changes to persist on disk immediately.

Isolated Mode (Worktrees)

Isolated workspaces create a managed worktree — a separate checkout that can be modified without affecting the original:

# The runtime creates an isolated worktree
holon workspace attach /path/to/repo --mode isolated --isolation-label experiment

Isolated workspaces are useful for:

Safe experimentation without polluting the working copy
Parallel work on the same repository by different agents
PR review branches where changes should not leak

Agent Home vs Project Workspace

Workspace Type	Purpose	Example
Agent home	Agent-local state and memory	`~/.holon/agents/my-agent/`
Project workspace	Code and files being worked on	`/path/to/project`

Every agent starts with its agent home as the active workspace. Use workspace attach to switch to a project workspace, and workspace exit to return to agent home.

UseWorkspace Tool

Agents use the UseWorkspace tool during execution to switch workspaces programmatically:

UseWorkspace({ path: "/repo" }) — attach to a directory
UseWorkspace({ workspace_id: "agent_home" }) — return to agent home
UseWorkspace({ workspace_id: "ws-..." }) — switch to a known workspace
mode: "isolated" — request an isolated worktree
access_mode: "exclusive_write" — request write access