@elizaos/plugin-workspace

Workspace management for elizaOS - create, switch, and manage isolated code workspaces.

Why This Plugin?

Workspaces are a shared concept across multiple plugins:

• plugin-code: File operations happen within a workspace
• plugin-git: Git operations happen within a workspace

Rather than each plugin managing its own "working directory" concept, this plugin provides a single source of truth for "where am I working?".

Installation

bun add @elizaos/plugin-workspace

Usage

import { workspacePlugin } from '@elizaos/plugin-workspace';

const project = {
  plugins: [workspacePlugin],
  // ...
};

Configuration

Variable	Description
WORKSPACE_ROOT	Override default workspace directory
ELIZA_DATA_DIR	Parent directory (uses $ELIZA_DATA_DIR/workspaces)

Default: ~/.eliza/workspaces

Actions

Action	Description	Example
CREATE_WORKSPACE	Create from git/zip/local	"Clone https://github.com/user/repo"
LIST_WORKSPACES	Show all workspaces	"List my workspaces"
SWITCH_WORKSPACE	Change active workspace	"Switch to react"
DELETE_WORKSPACE	Remove workspace	"Delete workspace old-project yes delete"

Providers

Provider	Description
WORKSPACE_STATUS	Injects current workspace context (active workspace, path, framework)
WORKSPACE_HELP	Usage instructions for the agent to guide users
WORKSPACE_SETTINGS	Current configuration (non-sensitive: directories, counts)

Why Three Providers?

• STATUS: For LLM context during operations ("You are working in react/...")
• HELP: For the agent to answer "how do I use workspaces?"
• SETTINGS: For users to understand their current configuration

Progressive Enhancement

This plugin enables progressive enhancement for other plugins:

Without plugin-workspace

plugin-code: Uses CODER_ALLOWED_DIRECTORY setting
plugin-git:  Uses GIT_ALLOWED_PATH setting or user-provided path

With plugin-workspace

plugin-code: Uses active workspace path (falls back to setting)
plugin-git:  Uses active workspace path (falls back to setting)

User: "Clone facebook/react"
→ Creates workspace, activates it

User: "Read package.json"
→ plugin-code reads from active workspace

User: "Commit changes"
→ plugin-git commits in active workspace

User: "Switch to my-other-project"
→ All operations now use new workspace

Workspace Sources

Workspaces can be created from:

Source	Example
Git	"Clone https://github.com/user/repo"
Zip	"Import https://example.com/project.zip"
Local	"Create workspace called my-project"

Per-Conversation Isolation

Each conversation has its own active workspace. User A in conversation 1 can work on "react" while User B in conversation 2 works on "vue" - they don't interfere with each other.

API for Other Plugins

Other plugins can use WorkspaceService:

const workspaceService = runtime.getService<WorkspaceService>('workspace');

// Get active workspace for this conversation
const workspace = workspaceService?.getActiveWorkspace(conversationId);
if (workspace) {
  // Use workspace.path for operations
  const targetPath = workspace.path;
} else {
  // Fall back to user-provided path or setting
  const targetPath = userProvidedPath || defaultSetting;
}

Directory Structure

~/.eliza/workspaces/
├── .metadata/
│   └── workspaces.json     # Registry of all workspaces
├── facebook-react/         # Git clone
├── my-python-project/      # Extracted zip
└── local-experiment/       # Local workspace

License

MIT