Workspace setup

A workspace is a parent directory containing several git repos that repowise indexes and analyzes together. Each repo gets its own .repowise/wiki.db (the same as single-repo mode), plus a workspace layer adds cross-repo signals on top: co-changes, API contracts, and package dependency mapping.

When to use a workspace#

• Backend and frontend in separate repos.
• Microservices that talk over HTTP, gRPC, or topics.
• A monorepo split into sub-repos (Git submodules, sister projects).
• Anywhere you want to understand cross-repo dependencies and co-change patterns.

Directory layout#

my-workspace/
  .repowise-workspace.yaml         # workspace config
  .repowise-workspace/             # shared cross-repo data
    cross_repo_edges.json          # co-change pairs and package deps
    contracts.json                 # extracted API contracts and links
    system_graph.json              # service-granular system graph + diagnostics
    breaking_changes.json          # breaking provider changes vs the last index
    conformance.json               # architecture rule violations + dependency cycles
  .claude/
    CLAUDE.md                      # workspace-level CLAUDE.md
  backend/
    .repowise/                     # per-repo index
      wiki.db
      lancedb/
  frontend/
    .repowise/
      wiki.db
      lancedb/

Each subdirectory must be its own git repo.

Initialise#

cd my-workspace/
repowise init .

repowise init . scans for git repos up to 3 levels deep (linked git worktrees are skipped) and opens the plan screen with the repos listed. By default every repo is selected and its documentation is built from code; r chooses the repos and the primary repo (the default for MCP queries), and m adds a model. It then indexes each repo, runs the cross-repo analysis, and writes .repowise-workspace.yaml.

repowise init . --yes --repos api,web   # skip the screen, index two repos

--repos takes aliases, directory names, or paths relative to the folder. In a new workspace the first one listed is primary; an existing workspace keeps its primary. --yes, --all or a piped stdin take every repo and print which ones. Picking fewer repos on a re-run keeps the others in .repowise-workspace.yaml: an interactive run asks before dropping them, and --yes never drops them.

To add a repo later:

repowise workspace add ../shared-libs --alias shared   # indexed, documentation built from code
repowise workspace scan        # discover newly-cloned repos

To remove a repo from the workspace (the repo's .repowise/ directory is preserved on disk):

repowise workspace remove backend

See the workspace CLI page for the full subcommand list.

Updating#

repowise update --workspace      # update every stale repo
repowise update --repo backend   # update one specific repo
repowise watch --workspace       # auto-update on file change
repowise hook install --workspace

What you get on top of single-repo#

• Cross-repo co-changes: files that change together across repos without an import link.
• API contract extraction: HTTP routes, gRPC services, message topics, and app-to-database contracts matched provider-to-consumer.
• Package dependency mapping: when one repo declares another as a dependency in its manifest.
• Federated MCP: pass repo="backend" to any of the core MCP tools, or repo="all" to the four that merge across the workspace, plus two workspace-only tools enabled by default, blast radius and architecture metrics, and a third, conformance, available opt-in.
• Workspace dashboard: aggregate stats and contract / co-change views.
• Workspace CLAUDE.md: auto-generated context covering every repo and the relationships between them.

Detail: Cross-repo intelligence, the system graph and map, blast radius, breaking-change guard, architecture conformance, architecture metrics, and Workspace MCP mode.