Workspaces

A workspace is one unit of work — a feature, a bug fix, a migration, a refactor. It gives you an isolated environment where you can work with AI agents without affecting anything else.

What a workspace gives you

When you create a workspace, Tracigo sets up:

• A git branch — your workspace gets its own branch, created from the source branch you choose
• A VS Code environment — a dedicated editor instance for this work
• An artifact folder — .tracigo/<workspace>/ where your YAML artifacts live
• Agent configuration — instruction files that teach your AI agents about this workspace's artifacts

Everything is isolated. Changes in one workspace don't affect another. You can have five workspaces running in parallel, each on its own branch, each with its own agents, all visible in the sidebar.

Creating a workspace

From the project page, click New Workspace. You'll provide:

• Name — describes the work: "payment-retry", "auth-migration", "fix-checkout-bug"
• Branch name — defaults to the workspace name. This is the git branch.
• Source branch — where to branch from (typically main)

Tracigo creates git worktrees (not just branch checkouts), so your original main branch is never modified.

Single-repo vs multi-repo

Single repository

Most common setup. Your project has one repo. The workspace is a worktree of that repo.

your-project/
├── main-repo/                    ← original clone (untouched)
└── payment-retry/                ← workspace worktree
    ├── .tracigo/
    │   └── payment-retry/        ← artifacts
    │       ├── requirements.yaml
    │       └── design.yaml
    ├── .claude/rules/            ← agent instructions (auto-generated)
    └── src/                      ← your code

Multiple repositories

For projects with a frontend and backend (or more). Each repo gets its own worktree inside the workspace folder. Artifacts live at the workspace level, shared across repos.

your-project/
├── frontend/                     ← original clone (untouched)
├── backend/                      ← original clone (untouched)
└── payment-retry/                ← workspace folder
    ├── .tracigo/                 ← artifacts (shared across repos)
    │   ├── requirements.yaml
    │   └── design.yaml
    ├── frontend/                 ← frontend worktree
    │   ├── .claude/rules/        ← agent instructions
    │   └── src/
    └── backend/                  ← backend worktree
        ├── .claude/rules/        ← agent instructions
        └── src/

In multi-repo workspaces, artifacts are committed into each repo on your next commit via a git hook — so they're portable and visible in code review.

Workspace lifecycle

Workspaces have a lifecycle status that reflects where the work stands:

Change the status from the project page. The daily digest uses these statuses to surface what needs attention — a workspace stuck in "In Progress" with no activity gets flagged.

Opening and closing

Opening a workspace starts the VS Code environment and makes it available in the sidebar. You can have multiple workspaces open simultaneously.

Closing a workspace gives you two options:

• Keep files — the worktree stays on disk, ready to reopen later
• Remove files — cleans up the worktree. The branch stays in git, so nothing is lost.

Closed workspaces can always be reopened. The git branch and any pushed artifacts remain available.

Parallel work

The sidebar shows all your open workspaces. Each workspace has its own:

• VS Code instance
• Terminal sessions with AI agents
• Artifact state

Switch between them by clicking in the sidebar. Your terminal sessions keep running in the background — you can start an agent in one workspace and check on another while it works.

Agent sessions

Tracigo tracks AI agent sessions across your workspaces. When you run Claude Code, Codex, Gemini, or any supported agent in a workspace terminal, Tracigo discovers the session and displays it in the workspace view.

You can see:

• Which agents have been used in this workspace
• Session history with the first message as a title
• Resume commands to continue previous sessions

This gives you a clear trail of every AI interaction that contributed to the workspace.

Next steps

• Artifacts — What artifacts are and how to write them
• Agent integration — How agents discover your workspace context
• Getting started — Create your first workspace