Workspace

Local workspaces, optional SQLite index, sessions, and bundles.

The workspace turns a project's local AgentInspect output into one coherent, local-first workbench: traces, reports, artifacts, bundles, an optional index, and notes — described by a small manifest at .agent-inspect/workspace.json.

It is opt-in and additive. Existing trace directories keep working exactly as before; the workspace is a layout + config layer, not a schema change. Trace files are never deleted by workspace commands.

• Added in: v4.0.0
• Stability: experimental
• Non-goals: no daemon, no database dependency, no cloud sync, no default migration of existing traces.

Quick start

# Create (or adopt) a workspace in the current project
agent-inspect workspace init --project my-agent

# See what's inside
agent-inspect workspace status

# Validate config, permissions, and index freshness
agent-inspect workspace doctor

# Preview generated content that could be cleaned (dry-run)
agent-inspect workspace clean
# Actually remove generated content (traces are always preserved)
agent-inspect workspace clean --yes

# Print resolved paths
agent-inspect workspace path

All commands accept --json for deterministic machine-readable output.

Layout

.agent-inspect/
  workspace.json
  runs/        # JSONL traces
  reports/     # generated reports
  artifacts/   # CI artifacts
  bundles/     # share-safe bundles
  index/       # optional local index (v4.1+)
  notes/       # decision notes

Manifest: workspace.json

{
  "schemaVersion": "1.0",
  "project": "my-agent",
  "createdAt": "2026-07-08T00:00:00.000Z",
  "traceDirs": ["runs"],
  "reportsDir": "reports",
  "artifactsDir": "artifacts",
  "bundlesDir": "bundles",
  "notesDir": "notes",
  "redactionProfile": "share",
  "index": { "enabled": false, "type": "none" }
}

All directory fields are relative to the .agent-inspect workspace directory and must resolve inside it (absolute paths and .. traversal are rejected). redactionProfile sets the default share-safety posture used by later bundle/export flows.

Adoption and compatibility

• New project: workspace init creates workspace.json and the standard folders.
• Existing .agent-inspect directory: detected and adopted without rewriting or moving existing traces. Top-level *.jsonl traces are preserved and included via a "." trace directory.
• Existing manifest: left untouched; missing folders are created.
• No manifest: existing commands continue to operate against explicit trace directories.

Programmatic API

The same model is available on the agent-inspect/workspace subpath (experimental):

import {
  createWorkspace,
  getWorkspaceStatus,
  readWorkspaceManifestFile,
  resolveWorkspaceLocation,
} from "agent-inspect/workspace";

const result = await createWorkspace({ project: "my-agent" });
const status = await getWorkspaceStatus(result.location, result.manifest);
console.log(status.traceFiles, status.reports);

Helpers are local-only, never perform network I/O, and never delete trace files.

Safety

• Manifest parsing validates shape and bounds input size; invalid input is rejected with clear messages rather than throwing.
• All manifest-derived paths are resolved and confirmed to stay within the workspace directory.
• workspace clean is a dry-run by default and never targets trace directories.