Skip to main content
Workspaces let you maintain separate configurations for different contexts - personal projects, work, client projects, or different environments. Each workspace has its own sources, skills, statuses, and session history.

​
Understanding Workspaces

A workspace is a self-contained configuration unit stored at: 
~/.craft-agent/workspaces/{workspace-id}/
Each workspace contains:
ComponentDescription
SourcesMCP servers, APIs, and local filesystems connected to this workspace
SkillsReusable instructions invoked with @mention
StatusesWorkflow states for organizing sessions
SessionsChat history specific to this workspace

​
Adding a Workspace

During initial setup, you create your first workspace automatically. To add more:
  1. Click the workspace dropdown in the sidebar (shows your current workspace name)
  2. Select Add Workspace…
  3. Enter a name for the new workspace
  4. The workspace is created with default settings

​
Switching Workspaces

To switch between workspaces:
  1. Click the workspace dropdown in the sidebar
  2. Select the workspace you want to switch to
The sidebar shows your current workspace name. Switching workspaces loads that workspace’s sources, skills, statuses, and sessions.

​
Workspace-Specific Configuration

Each workspace maintains its own:
DataDescription
SourcesMCP servers, APIs, and local filesystems
SkillsReusable instructions defined in skills/
StatusesWorkflow states defined in statuses/config.json
SessionsChat history stored in sessions/
PermissionsOptional Explore mode rules in permissions.json
ThemeOptional color theme override (configured in Settings → Appearance)
Default LLM ConnectionOptional default AI connection for new sessions

​
Directory Structure

~/.craft-agent/
  workspaces/
    {workspace-id}/
      config.json           # Workspace configuration
      .claude-plugin/       # Plugin manifest (Claude Code SDK compatibility)
        plugin.json         # Plugin manifest with skills and agents
      sources/
        {source-slug}/
          config.json       # Source configuration
          guide.md          # Usage documentation
      skills/
        {skill-slug}/
          SKILL.md          # Skill definition
      statuses/
        config.json         # Status definitions
        icons/              # Custom status icons
          todo.svg
          done.svg
      sessions/
        {session-id}/
          session.jsonl     # Conversation in JSONL format
          attachments/      # Uploaded files
          plans/            # Implementation plans
      permissions.json      # Optional Explore mode rules
      icon.png              # Optional workspace icon (png/jpg/svg)

​
Workspace Defaults

Workspaces can override app defaults for AI connection and theme: 
{
  "defaults": {
    "defaultLlmConnection": "claude-max",
    "colorTheme": "nord"
  }
}
Resolution order for connections:
  1. Session connection
  2. Workspace default (defaults.defaultLlmConnection)
  3. Global default (defaultLlmConnection in config.json)
  4. First connection in the list

​
Use Cases

Keep your personal projects separate from work. Each workspace has its own sources, skills, and session history - no mixing of contexts.
Consultants and freelancers can set up separate workspaces for each client, with dedicated sources and custom skills per project.
Maintain separate workspaces for development, staging, and production - each with appropriate API endpoints and permissions.
Share workspace configurations with team members by copying the workspace directory structure.

​
Tips

Use descriptive names that make it easy to identify the context at a glance.
Get comfortable with the basics before adding multiple workspaces. You can always add more later.
Add a permissions.json file to allow additional operations in Explore mode. See Permissions for details.