Session Management

The session watcher monitors your Contox project for new sessions and tracks the enrichment pipeline progress. It runs alongside the git watcher and provides real-time feedback through VS Code notifications and the status bar.

Session polling

The session watcher polls the Contox API every 30 seconds to check for new sessions. On each poll, it:

1. Fetches the 5 most recent sessions for your project
2. Updates the status bar with the last save time
3. Detects new sessions that were not seen before
4. Tracks whether the active session has been closed externally

New session notifications

When a new session is detected (saved via MCP, CLI, or the dashboard), the extension shows a VS Code notification:

Contox: Session saved (MCP) — Built JWT authentication with refresh tokens

The notification includes:

• The source of the session (MCP, CLI, or unknown)
• A truncated summary (up to 120 characters)
• A View Pipeline button to track enrichment progress
• A Dismiss button

Pipeline tracking

After a new session is detected, the extension automatically starts polling the enrichment pipeline every 5 seconds. The pipeline processes your session through four jobs:

The status bar shows the current pipeline status with animated icons:

• Spinning sync icon for running jobs
• Check icon for completed jobs
• Error icon for failed jobs
• Clock icon for pending jobs

Pipeline completion

When the pipeline finishes, the extension shows a completion notification:

Success:

Contox pipeline complete: ✓ Enrichment  ✓ Embedding  ✓ Deduplication  ✓ Drift Check

Failure:

Contox pipeline failed: ✓ Enrichment  ✗ Embedding  ○ Deduplication  ○ Drift Check — error message

After completion, the status bar returns to showing the last save time.

External session closure

When you close a session from the Contox dashboard (for example, by clicking "Generate Memory"), the extension detects this automatically:

1. The session watcher notices the active session is no longer present
2. The git watcher's capture buffer is reset
3. A new session is created automatically
4. A notification confirms: "Session closed externally -- new session started."

This ensures the extension always has an active session to capture events into, even when sessions are managed from the dashboard.

Ending a session manually

You can end the current session from VS Code using the Contox: End Session & Start New command (contox.endSession). This:

1. Flushes any pending capture events
2. Finds the active session for your project
3. Closes the session via the API
4. Resets the capture buffer
5. Creates a new session immediately

Disconnect and reconnect

If you need to temporarily pause all background activity:

• Contox: Disconnect (Pause Sync) (contox.desync) -- Stops the session watcher and git watcher. The status bar shows a disconnected state. This preference persists across VS Code restarts.
• Contox: Reconnect (Resume Sync) (contox.connect) -- Restarts both watchers. Resumes normal operation.

These commands can also be triggered via deep links:

vscode://contox.contox-vscode/desync
vscode://contox.contox-vscode/connect

Next steps

• Auto Capture -- Details on git commit and diff capture
• Commands -- All 11 extension commands