Workspaces and Sessions

When you run unfault review, Unfault creates a session within a workspace. Understanding these concepts helps you get more out of Unfault’s tracking and query features.

Workspaces

A workspace represents a project or codebase. It’s how Unfault groups analysis sessions together so you can track progress over time.

How Workspaces Are Identified

Unfault computes a stable workspace ID from your project. The ID source depends on what’s available:

Git remote (most stable): If your project has a git remote configured, Unfault uses that URL to compute a consistent ID. This means the same repo analyzed from different machines or directories gets the same workspace ID.
Project manifest (fallback): If there’s no git remote, Unfault looks at manifest files like pyproject.toml, package.json, or go.mod to identify the project.
Directory label (least stable): As a last resort, Unfault uses the directory name. This is less reliable because renaming a folder creates a new workspace.

What Workspaces Enable

Grouping sessions by workspace lets you:

Track changes: See how facts evolve across sessions
Query history: Ask questions about patterns across your project’s history
Compare runs: Understand what changed between any two sessions

Workspace Labels

The workspace label is the human-readable name you see in output and the dashboard. By default, it’s your directory name (e.g., payments-service). The label is for display only; the underlying workspace ID is what Unfault uses for tracking.

Sessions

A session represents a single analysis run. Every time you run unfault review, a new session is created.

Session Lifecycle

Each session moves through states:

Created: Session initialized, awaiting code submission
Analyzing: Unfault is processing your code graph
Completed: Analysis finished, facts available
Failed: Something went wrong (see error message)
Expired: Session timed out before completion

Most sessions complete in seconds. You’ll typically only see completed status.

What Sessions Contain

A session captures:

Input: Which workspace, which dimensions to analyze
Code graph: The structural representation of your code (not the source)
Facts: Observations about your code (findings, SLO state, and more)
Metadata: Languages detected, frameworks identified, timing information

Session IDs

Every session gets a unique ID. You’ll see this in output:

Session: 550e8400-e29b-41d4-a716-446655440000

Session IDs are useful when:

Referencing a specific analysis run
Querying facts from a particular point in time
Debugging issues with Unfault support

The Relationship

Workspace (payments-service)
├── Session (Jan 10, 2025) - 12 facts
├── Session (Jan 9, 2025)  - 15 facts
├── Session (Jan 8, 2025)  - 14 facts
└── Session (Jan 5, 2025)  - 18 facts

One workspace contains many sessions. Sessions are immutable; once completed, they don’t change. This gives you an audit trail of your project’s analysis history.

Practical Usage

Viewing Workspace History

List recent sessions for a workspace:

# Query recent analysis history
unfault ask "What were my recent findings?"

Scoping Queries

When you have multiple projects, scope queries to a specific workspace:

unfault ask "Stability issues" --workspace wks_abc123

Workspace Migration

If you add a git remote to a project that was previously analyzed without one, Unfault can migrate your session history to the new, more stable workspace ID:

unfault workspace migrate

This preserves your analysis history while upgrading to git-based identification.

Privacy Note

Workspace and session data follow the same privacy model as everything else in Unfault:

Stored on the API: Workspace IDs, session metadata, facts, and the code graph structure
Never stored: Your actual source code, string literals, comments, or variable values

See How It Works for details on what data Unfault collects.

Retention

Session data is retained based on your subscription:

Plan	Retention
Free	7 days
Pro	90 days
Team	1 year

After the retention period, session data is automatically deleted. You can also manually delete sessions or entire workspaces from the dashboard.