Docs
GitHubBlog

Search Documentation

Search for a page in the docs

Structure

A Workspace is a git-backed desk plus one or more durable agent Sessions. The repo gives agents a place to read, write, commit, and leave artifacts; each Session gives one particular conversation a stable identity that can continue through an interactive terminal, WebPi, or headless turns.

Launcher layout

The default launcher root is <OPENALICE_HOME>/workspaces:

~/.openalice/workspaces/
├── workspaces.json                 # active runtime registry
├── workspaces/                     # active Workspace checkouts only
│   └── <wsId>/
│       ├── .git/
│       ├── CLAUDE.md
│       ├── AGENTS.md
│       ├── .agents/skills/
│       ├── .claude/skills/
│       └── .alice/issues/
├── departed-workspaces/            # retained offboarded checkouts
├── auto-quant-mirror/
└── state/
    ├── workspace-catalog.json
    ├── resume-identities.json
    ├── sessions/
    ├── scrollback/
    ├── schedule-markers.json
    ├── headless-tasks.json
    ├── headless-logs/
    └── artifact-provenance.json

workspaces.json lists desks Alice can run now. workspace-catalog.json retains lifecycle history, including departed and purged desks. Filesystem discovery under workspaces/ therefore means “active Workspaces,” not “everything that has ever existed.”

The launcher-owned Workspace Manager uses the active workspaces/ directory as its floor view but is deliberately absent from workspaces.json. Its durable Sessions use the reserved workspace-manager identity, preventing the control plane from appearing as another business desk in its own inventory.

The wsId is opaque, stable, and never reused. A human-readable tag can change without changing Workspace identity.

Product Sessions

One Workspace can host many Sessions. Their identities are deliberately separate:

  • resumeId identifies one durable product Session across interactive and headless turns.
  • taskId identifies one headless execution.
  • the Session record id identifies one interactive tab/PTY materialization.
  • the native Claude/Codex/opencode/Pi session id stays backend-only.

Opening the same resumeId again reuses its existing interactive materialization when possible. A finished headless run becomes interactive without losing the Session that produced it. See Sessions & Collaboration.

Terminal and WebPi

Claude Code, Codex, opencode, Pi, and shell normally run in OpenAlice's persistent terminal surface. You can read it, type into it, scroll back, pause it, and reattach later.

A running Pi Session can switch to WebPi · Beta, which renders Pi's own RPC messages in the browser. The terminal and WebPi are two surfaces over the same resumeId and Pi JSONL conversation, not separate histories.

Lifecycle

  1. Create — bootstrap the checkout, write instructions and skills, inject settings, and initialize git.
  2. Run — create Sessions that use the Workspace's files and CLIs.
  3. Iterate — agents write files, update Issues, commit, schedule work, and publish to Inbox.
  4. Pause — stop an interactive process while retaining its Session identity and scrollback.
  5. Offboard — inventory active work, write .alice/HANDOFF.md, move the complete checkout to departed-workspaces/, and retire its signatures.
  6. Restore or purge — restore the exact path and Sessions, or irreversibly remove the checkout while retaining historical attribution.

There is no “delete the registry row and leave the folder behind” path. See Lifecycle & Offboarding.

Template Upgrade reconciles managed assets in place without changing Workspace identity. Workspace Absorb copies reviewed source files into a target audit commit, then moves the intact source checkout to departed-workspaces/ with an absorbedIntoWorkspaceId catalog link. See Upgrades & Absorb.

Headless runs

A scheduled Issue or explicit headless request launches an enabled agent CLI against the same Workspace. The run receives its own taskId and belongs to a product resumeId. OpenAlice records normalized assistant text, tool/error blocks, bounded diagnostics, timing, status, and lineage.

Runs appear newest-first in the Automation surface. Opening a completed run continues its resumeId instead of treating the run id as a conversation id.

Next Steps