ada 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

ada workspace <subcommand> [options]

Subcommands

`ada workspace list`

List all available workspaces with their details.

Usage:

bash

ada workspace list [options]

Aliases: ls

Options:

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

Interactive Example:

$ ada 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:

$ ada workspace list

📁 No workspaces found

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

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

JSON output:

bash

$ ada 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"
  },
  ...
]

`ada workspace current`

Show the currently active workspace.

Usage:

bash

ada workspace current

Interactive Example:

$ ada 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:

$ ada workspace current

⚠️  No active workspace

Initialize a workspace in your project directory:
  ada workspace init

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

`ada workspace switch`

Switch to a different workspace.

Usage:

bash

ada workspace switch <workspace-name>

Arguments:

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

Interactive Example:

$ ada 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: ada chat
  • List agents: ada agents list
  • View sessions: ada sessions

Non-existent workspace:

$ ada workspace switch nonexistent

✗ Workspace not found: nonexistent

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

Create a new workspace with:
  ada workspace create nonexistent

`ada workspace create`

Create a new workspace with a specific name.

Usage:

bash

ada 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:

$ ada 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: ada workspace init
  3. Start working: ada chat

Name validation:

$ ada 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

`ada workspace init`

Initialize current directory as a workspace.

Usage:

bash

ada 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
$ ada 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:
  • ada chat "Explain this codebase"
  • ada agents list

With custom name:

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

✓ Workspace initialized: ecommerce-platform

Custom workspace name set (different from directory name)

Already initialized:

$ ada workspace init

⚠️  Workspace already initialized: my-new-project

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

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

Common Use Cases

Starting Fresh on a New Project

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

✓ Workspace initialized: new-project

$ ada 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

$ ada workspace current
Current: client-dashboard

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

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

Organizing Multiple Clients

$ ada workspace list

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

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

[All AI conversations stay isolated per client]

Team Collaboration

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

# Team member 2 (same project)
$ cd /path/to/shared/project
$ ada 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
$ ada 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
ada workspace current

# List available options
ada workspace list

# Switch quickly
ada 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

$ ada workspace switch nonexistent

Error: Workspace not found

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

Permission Issues

$ ada 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

$ ada workspace init

Warning: Directory already associated with workspace: old-name

Use --force to reassign directory to new workspace

Related Commands

ada chat - Start chat in current workspace context
ada agents - View agents for current workspace
ada 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

ada workspace

Overview

Usage

Subcommands

`ada workspace list`

`ada workspace current`

`ada workspace switch`

`ada workspace create`

`ada 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