Session Management Guide

Sessions in the Lovelace Neovim extension provide context for your tasks and track your work within specific workspaces. This guide explains how sessions work and how to view session information.

Viewing Session Information

Display current session and workspace details:

vim

:LovelaceSession

Session Output

# Session Information

**Session ID**: sess_abc123def456
**Workspace**: my-project (ws_def456ghi789)
**Created**: 2025-12-28 09:00:00
**Tasks Submitted**: 12

Session Components

Session ID

Format: sess_ + unique identifier

Purpose: Tracks your current editor session

Lifetime: Duration of Neovim instance or daemon connection

Example: sess_abc123def456

Workspace

Components:

Workspace Name: Human-readable project name (my-project)
Workspace ID: Unique identifier (ws_def456ghi789)

Purpose: Associates tasks with specific project context

Detection: Automatically detected from:

Git repository root
Project configuration files
Current working directory

Created Timestamp

When this session was established.

Typical session lifetime:

Short session: Minutes to hours (quick edits)
Long session: Hours to days (extended development)

Tasks Submitted

Total number of tasks submitted in this session.

What it tracks:

All tasks from this Neovim instance
Includes completed, running, and queued tasks
Resets on Neovim restart or session reconnection

How Sessions Work

Session Lifecycle

1. Open Neovim
   ↓
2. Plugin connects to daemon
   ↓
3. Daemon creates session
   ↓
4. Session associated with workspace
   ↓
5. All tasks linked to session
   ↓
6. Close Neovim
   ↓
7. Session ends

Session Persistence

During Neovim Session:

Session ID remains constant
Tasks accumulate in task count
Workspace association maintained

After Neovim Restart:

New session created
New session ID assigned
Task count resets to 0
Previous session history preserved in daemon

Note: Task results persist across sessions - you can review completed tasks from previous sessions.

Workspace Detection

Automatic Workspace Discovery

The daemon automatically detects your workspace from:

1. Git Repository

bash

# Daemon checks for .git directory
my-project/
├── .git/           ← Workspace root detected here
├── src/
└── tests/

Workspace name: Derived from repository name

2. Project Configuration Files

bash

# Checks for project markers
my-project/
├── package.json    ← Node.js project
├── Cargo.toml      ← Rust project
├── pyproject.toml  ← Python project
└── tsconfig.json   ← TypeScript project

3. Current Working Directory

If no project markers found, uses current directory:

bash

cd ~/projects/my-project
nvim src/file.js
# Workspace: ~/projects/my-project

Manual Workspace Configuration

Override automatic detection:

lua

require("lovelace").setup({
  tasks = {
    default_workspace = "my-workspace-id"  -- Force specific workspace
  }
})

Use when:

Working on multiple related projects
Daemon workspace detection is incorrect
Consolidating tasks across directories

Session Context in Tasks

All tasks submitted inherit session context:

Task Metadata

When you submit a task:

vim

:LovelaceTask

The task includes:

Session ID: Links task to current session
Workspace ID: Associates with project
Timestamp: When task was created
User ID: Your authentication identity

Why Sessions Matter

Task Organization:

Group tasks by development session
Track productivity (tasks per session)
Analyze workflows

Context Preservation:

Tasks know which project they're for
Results associated with correct workspace
History maintained across sessions

Collaboration:

Multiple developers, separate sessions
Tasks identified by session
No cross-session interference

Session Information Use Cases

Before Starting Work

Check you're in the right workspace:

vim

:LovelaceSession
# Verify workspace matches your project

Productivity Tracking

Monitor tasks submitted this session:

vim

:LovelaceSession
# Tasks Submitted: 12

Indicates active development session.

Troubleshooting

Verify session is active:

vim

:LovelaceSession
# Should show valid session ID

If session information is missing or stale:

vim

:LovelaceHealth
# Check daemon connection

Multi-Project Development

When switching between projects:

bash

# Project 1
cd ~/projects/frontend
nvim src/app.tsx
:LovelaceSession  # Workspace: frontend

# Project 2
cd ~/projects/backend
nvim src/server.ts
:LovelaceSession  # Workspace: backend

Each Neovim instance has separate session.

Session vs Workspace

Aspect	Session	Workspace
Duration	Current Neovim instance	Permanent (project lifetime)
Scope	One editor instance	All sessions for project
ID Format	`sess_abc123`	`ws_def456`
Reset	On Neovim restart	Never (unless manually deleted)
Purpose	Track current editing session	Organize project tasks

Advanced: Session API

Access session data programmatically:

lua

local lovelace = require("lovelace")
local connection = lovelace.get_connection()

connection:call("session.info", {}, function(result, error)
  if result then
    print("Session ID: " .. result.session_id)
    print("Workspace: " .. result.workspace.name)
    print("Tasks: " .. result.task_count)
  end
end)

Session Persistence Across Daemon Restarts

What Persists

Survives daemon restart:

Workspace definitions
Task history
Completed task results
User authentication

Does NOT survive:

Current session IDs (new sessions created)
Live task progress (running tasks cancelled)
Real-time notifications

Recovery After Daemon Restart

Daemon restarts (for upgrades, crashes)
Neovim detects disconnection
Plugin attempts reconnection
New session created on successful connection
Previous completed tasks still accessible

Check status after reconnection:

vim

:LovelaceHealth
# Verify connection restored

:LovelaceSession
# New session ID assigned

Troubleshooting Sessions

"No active session"

Symptom: :LovelaceSession shows error or empty response

Solutions:

Check daemon connection:
vim
```
:LovelaceHealth
```
Verify authentication:
vim
```
:LovelaceAuth
```
Reconnect to daemon:
bash
```
localhost-ctl restart
```
Then reopen Neovim

Wrong Workspace Detected

Symptom: Session shows incorrect workspace name

Solutions:

Change directory to correct project root:
vim
```
:cd ~/projects/correct-project
```
Restart Neovim from project root:
bash
```
cd ~/projects/correct-project
nvim
```
Manually set workspace in config:
lua
```
require("lovelace").setup({
  tasks = {
    default_workspace = "correct-workspace-id"
  }
})
```

Tasks Not Counting

Symptom: Task count doesn't increase after submitting tasks

Solutions:

Verify task submission succeeded:
vim
```
:messages
# Look for "Task submitted" confirmation
```
Check session is active:
vim
```
:LovelaceSession
# Should show valid session ID
```
Refresh session info (may be cached)

Next Steps

Task Submission - Submit tasks in session context
Configuration - Configure workspace settings
:LovelaceSession Reference - Full command documentation
Task Monitoring - View session tasks

Lovelace Developer Portal

Session Management Guide

Viewing Session Information

Session Output

Session Components

Session ID

Workspace

Created Timestamp

Tasks Submitted

How Sessions Work

Session Lifecycle

Session Persistence

Workspace Detection

Automatic Workspace Discovery

1. Git Repository

2. Project Configuration Files

3. Current Working Directory

Manual Workspace Configuration

Session Context in Tasks

Task Metadata

Why Sessions Matter

Session Information Use Cases

Before Starting Work

Productivity Tracking

Troubleshooting

Multi-Project Development

Session vs Workspace

Advanced: Session API

Session Persistence Across Daemon Restarts

What Persists

Recovery After Daemon Restart

Troubleshooting Sessions

"No active session"

Wrong Workspace Detected

Tasks Not Counting

Next Steps

Related Documentation

Lovelace Developer Portal