lovelace workspace

Manage workspaces for organized AI-powered development

Workspaces are organizational containers that group related projects, sessions, and AI context together. They provide isolated environments for different projects, clients, or experiments while maintaining persistent AI memory and project-specific settings.

Overview

Workspaces in Lovelace help you:

Organize projects - Group related codebases and sessions
Isolate context - Keep AI conversations and memory separate between projects
Switch easily - Move between different projects quickly
Persist settings - Maintain project-specific configurations
Track history - Review workspace-specific chat sessions and agent runs

Each workspace has its own:

Chat session history
Agent execution records
Project context and file associations
Configuration overrides
Memory and conversation context

Usage

bash

lovelace workspace <subcommand> [options]

Subcommands

`lovelace workspace list`

List all available workspaces with their details.

Usage:

bash

lovelace workspace list [options]

Aliases: ls

Options:

Option	Description	Default
`--format <format>`	Output format (table, json)	`table`

Interactive Example:

$ lovelace workspace list

Name          │ Title                  │ Path                        │ Created    │ Last Opened
──────────────────────────────────────────────────────────────────────────────────────────────────
my-project    │ E-commerce Platform    │ /Users/dev/ecommerce        │ 2025-10-01 │ 2025-10-19
team-api      │ Team API Service       │ /Users/dev/team-api         │ 2025-09-15 │ 2025-10-18
experiments   │ ML Experiments         │ /Users/dev/ml-experiments   │ 2025-08-20 │ 2025-10-10

3 workspaces total

Empty state:

$ lovelace workspace list

📁 No workspaces found

Get started by creating your first workspace:
  lovelace workspace init
  (in your project directory)

Or create a named workspace:
  lovelace workspace create my-project

JSON output:

bash

$ lovelace workspace list --format json

[
  {
    "name": "my-project",
    "title": "E-commerce Platform",
    "path": "/Users/dev/ecommerce",
    "created": "2025-10-01T00:00:00.000Z",
    "lastOpened": "2025-10-19T00:00:00.000Z"
  },
  ...
]

`lovelace workspace current`

Show the currently active workspace.

Usage:

bash

lovelace workspace current

Interactive Example:

$ lovelace workspace current

Current Workspace
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Name: my-project
Title: E-commerce Platform
Path: /Users/dev/ecommerce
Created: 2025-10-01
Last Opened: 2025-10-19 (now)

Chat Sessions: 47
Agent Runs: 12
Context Files: 234 files tracked

No active workspace:

$ lovelace workspace current

⚠️  No active workspace

Initialize a workspace in your project directory:
  lovelace workspace init

Or switch to an existing workspace:
  lovelace workspace switch my-project

`lovelace workspace switch`

Switch to a different workspace.

Usage:

bash

lovelace workspace switch <workspace-name>

Arguments:

Argument	Description	Required
`workspace-name`	Name of workspace to activate	Yes

Interactive Example:

$ lovelace workspace switch team-api

✓ Switched to workspace: team-api

Workspace Details:
  Title: Team API Service
  Path: /Users/dev/team-api
  Chat Sessions: 23
  Agent Runs: 5

Workspace context loaded. You can now:
  • Start a chat: lovelace chat
  • List agents: lovelace agents list
  • View sessions: lovelace sessions

Non-existent workspace:

$ lovelace workspace switch nonexistent

✗ Workspace not found: nonexistent

Available workspaces:
  • my-project
  • team-api
  • experiments

Create a new workspace with:
  lovelace workspace create nonexistent

`lovelace workspace create`

Create a new workspace with a specific name.

Usage:

bash

lovelace workspace create <workspace-name> [options]

Arguments:

Argument	Description	Required
`workspace-name`	Name for the new workspace	Yes

Options:

Option	Description
`--description <desc>`	Workspace description
`--skip-init`	Don't initialize project directory

Interactive Example:

$ lovelace workspace create client-dashboard --description "Client Analytics Dashboard"

Creating workspace: client-dashboard
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Workspace created successfully

Details:
  Name: client-dashboard
  Title: Client Analytics Dashboard
  Path: /Users/dev/client-dashboard
  Created: 2025-10-19

Next steps:
  1. Navigate to your project: cd /Users/dev/client-dashboard
  2. Initialize workspace context: lovelace workspace init
  3. Start working: lovelace chat

Name validation:

$ lovelace workspace create "Invalid Name!"

✗ Invalid workspace name

Workspace names must:
  • Start with a letter
  • Contain only letters, numbers, hyphens, and underscores
  • Be between 3 and 50 characters

Valid examples:
  • my-project
  • client_dashboard
  • api-v2

`lovelace workspace init`

Initialize current directory as a workspace.

Usage:

bash

lovelace workspace init [options]

Options:

Option	Description
`--force`	Force initialization even if workspace exists
`--name <name>`	Workspace name (defaults to directory name)
`--description <desc>`	Workspace description

Interactive Example:

$ cd /Users/dev/my-new-project
$ lovelace workspace init

Initializing workspace...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Detected project:
  Directory: my-new-project
  Type: Node.js (package.json found)
  Git: Yes (main branch)

✓ Workspace initialized successfully

Details:
  Name: my-new-project
  Path: /Users/dev/my-new-project
  Created: 2025-10-19

Workspace context includes:
  • 47 TypeScript files
  • 8 configuration files
  • Git history (234 commits)

Ready to use! Try:
  • lovelace chat "Explain this codebase"
  • lovelace agents list

With custom name:

$ lovelace workspace init --name ecommerce-platform --description "E-commerce Platform"

✓ Workspace initialized: ecommerce-platform

Custom workspace name set (different from directory name)

Already initialized:

$ lovelace workspace init

⚠️  Workspace already initialized: my-new-project

Current workspace details:
  Created: 2025-10-15
  Sessions: 23
  Agents: 5

To reinitialize, use --force:
  lovelace workspace init --force

Common Use Cases

Starting Fresh on a New Project

$ cd /path/to/new-project
$ lovelace workspace init

✓ Workspace initialized: new-project

$ lovelace chat "Explain the architecture of this codebase"

🤖 I can see this is a Next.js 14 project with...
[AI provides context-aware explanation]

Switching Between Projects

$ lovelace workspace current
Current: client-dashboard

$ lovelace workspace switch team-api
✓ Switched to: team-api

$ lovelace chat
🤖 Welcome back to team-api workspace!
[Chat context automatically loaded]

Organizing Multiple Clients

$ lovelace workspace list

client-a-frontend
client-a-backend
client-b-api
client-b-web
internal-tools

$ lovelace workspace switch client-a-frontend
✓ Switched to: client-a-frontend

[All AI conversations stay isolated per client]

Team Collaboration

# Team member 1
$ lovelace workspace create team-shared
$ lovelace workspace init
✓ Team workspace created

# Team member 2 (same project)
$ cd /path/to/shared/project
$ lovelace workspace init
✓ Connected to team-shared workspace

[Shared context, separate sessions]

Workspace Data

Each workspace stores:

~/.lovelace/workspaces/
├── my-project/
│   ├── workspace.json          # Workspace metadata
│   ├── sessions/               # Chat session history
│   │   ├── session_abc123.json
│   │   └── session_xyz789.json
│   ├── agents/                 # Agent execution records
│   │   ├── agent_001.json
│   │   └── agent_002.json
│   ├── context/                # Project context cache
│   │   └── file-index.json
│   └── config/                 # Workspace-specific config
│       └── overrides.json

Workspace Naming

Valid names:

Must start with a letter
Can contain: letters, numbers, hyphens, underscores
Length: 3-50 characters
Case-sensitive

Examples:

✅ my-project
✅ client_dashboard
✅ api-v2
✅ ML-experiments-2025

❌ 123-project (starts with number)
❌ my project (contains space)
❌ my@project (invalid character)
❌ ab (too short)

Tips & Best Practices

Workspace Organization

By project type:

personal-website
work-api-service
client-acme-web
experiment-ml-models

By lifecycle:

production-api
staging-web
dev-experiments
archived-old-project

Context Management

Initialize early:

# Right after cloning
$ git clone repo.git
$ cd repo
$ lovelace workspace init

Keep workspaces focused:

# Instead of one huge workspace
my-monorepo

# Use separate workspaces
frontend-app
backend-api
shared-lib

Switching Efficiency

Check before switching:

bash

# See what's currently active
lovelace workspace current

# List available options
lovelace workspace list

# Switch quickly
lovelace workspace switch <name>

Environment Variables

Variable	Description	Default
`LOVELACE_WORKSPACE`	Default workspace name	-
`LOVELACE_WORKSPACES_DIR`	Workspaces storage directory	`~/.lovelace/workspaces`
`LOVELACE_AUTO_INIT`	Auto-initialize workspace in directories	`false`

Exit Codes

Code	Meaning
`0`	Command succeeded
`1`	Error (workspace not found, init failed, etc.)
`2`	Invalid arguments (bad workspace name, missing directory)

Troubleshooting

Workspace Not Found

$ lovelace workspace switch nonexistent

Error: Workspace not found

Solution:
$ lovelace workspace list  # See available workspaces
$ lovelace workspace create nonexistent  # Or create it

Permission Issues

$ lovelace workspace init

Error: Permission denied

Solution:
# Check directory permissions
ls -la

# Ensure you have write access to ~/.lovelace
chmod -R u+w ~/.lovelace

Multiple Workspaces Same Directory

$ lovelace workspace init

Warning: Directory already associated with workspace: old-name

Use --force to reassign directory to new workspace

Related Commands

lovelace chat - Start chat in current workspace context
lovelace agents - View agents for current workspace
lovelace sessions - View workspace chat sessions
lovelace config - Configure workspace settings

Related Guides

Workspace Management Guide - Complete workspace features
Project Organization Example - Organizing files and workspaces

See the Command Reference for all available commands.

Lovelace Developer Portal

lovelace workspace

Overview

Usage

Subcommands

`lovelace workspace list`

`lovelace workspace current`

`lovelace workspace switch`

`lovelace workspace create`

`lovelace workspace init`

Common Use Cases

Starting Fresh on a New Project

Switching Between Projects

Organizing Multiple Clients

Team Collaboration

Workspace Data

Workspace Naming

Tips & Best Practices

Workspace Organization

Context Management

Switching Efficiency

Environment Variables

Exit Codes

Troubleshooting

Workspace Not Found

Permission Issues

Multiple Workspaces Same Directory

Related Commands

Related Guides

Lovelace Developer Portal