Workspaces

When you run unfault review, Unfault identifies which project it’s analyzing through a workspace. Understanding this helps explain how Unfault detects your project, applies configuration, and displays results.

What a Workspace Is

A workspace is Unfault’s representation of a project or codebase. It determines:

• Which configuration files apply
• What the workspace is called in output
• How Unfault identifies the project for SLO linking

The workspace is derived from the directory you run Unfault from. Everything happens locally.

How Workspaces Are Identified

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

1. Git remote (most stable): If your project has a git remote configured, Unfault uses that URL to compute a consistent label. The same repo analyzed from different directories gets the same workspace identity.

2. 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.

3. Directory name (least stable): As a last resort, Unfault uses the current directory name. This is less reliable because renaming a directory changes the workspace identity.

Tip

For consistent identification across machines and CI, make sure your project has a git remote configured. This gives Unfault the most stable workspace identity.

Workspace Label

The workspace label is the human-readable name you see in analysis output. By default, it’s your directory name (e.g., payments-service).

1112ms - python / fastapi - 1 file   [payments-service]

The label is display-only. It doesn’t affect which files are analyzed or how rules apply.

Configuration and Workspaces

Each workspace can have its own configuration. Unfault looks for configuration in:

1. Current directory’s manifest file (pyproject.toml, Cargo.toml, package.json)
2. Parent directories up to the git root
3. .unfault.toml if no manifest contains Unfault configuration

This means running unfault review from different directories in the same repository applies different configuration. A monorepo with per-service config in each subdirectory works naturally.

See Configuration for the full reference.

Workspace-Level SLO Linking

When Unfault detects cloud credentials and links SLOs to your codebase, that mapping is stored locally at .unfault/ in your project directory:

.unfault/
└── cache/
    └── enrichment/
        └── slo_mapping.json

This file persists across runs. Future reviews remember which SLOs belong to this workspace without prompting again. To re-run discovery and update the mapping, force a cache refresh:

unfault review --refresh-cache

Enrichment Cache

To avoid fetching SLO and trace data on every run, Unfault caches observability data locally:

.unfault/cache/enrichment/

The cache has a 5-minute TTL. You’ll see cached or fetch Xms in the review footer accordingly. Force a cache refresh with:

unfault review --refresh-cache

Skip enrichment entirely (for CI or offline use) with:

unfault review --offline

Privacy

All workspace data stays on your machine:

• Stored locally: Workspace labels, SLO mappings, enrichment cache
• Never stored remotely: Your source code, string literals, comments, or variable values

Analysis runs entirely on your hardware. See How It Works for details.

Next Steps

Configuration

Customize behavior per workspace. Read more

SLO Discovery

Link cloud SLOs to your workspace. Read more

How It Works

The full local analysis pipeline. Read more