# Workspace setup

Index related git repos as one repowise workspace for cross-repo co-changes, API contract matching and federated MCP queries on top of per-repo intelligence.

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

```text
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

```bash
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](https://docs.repowise.dev/cli/indexing#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`.

```bash
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:

```bash
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):

```bash
repowise workspace remove backend
```

See the [`workspace` CLI page](https://docs.repowise.dev/cli/workspace) for the full
subcommand list.

## Updating

```bash
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
```

An update with one changed repo rewrites only that repo's store and editor
files, and an update with nothing changed refreshes only the repos that
moved. Unchanged repos are reused, and the cross-repo analysis re-runs when
the `contracts:` or `conformance:` block (or a declared repo tag) changed,
even with every repo up to date. Editing `service_bases` or `manual_links`
re-links stored contracts without re-reading any repo. The per-repo summary
shows each repo's stored file and symbol counts.

From a workspace root, a single-repo command (`health`, `dead-code`,
`events`) reads one repo and prints which one; pass `--repo ALIAS` to pick
it, or `--no-workspace` on `events` to skip workspace mode.

## 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](https://docs.repowise.dev/mcp/overview), or `repo="all"` to the four
  that merge across the workspace, plus two workspace-only
  tools enabled by default, [blast radius](https://docs.repowise.dev/multi-repo/blast-radius)
  and [architecture metrics](https://docs.repowise.dev/multi-repo/architecture-metrics), and
  a third, [conformance](https://docs.repowise.dev/multi-repo/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](https://docs.repowise.dev/multi-repo/cross-repo),
the [system graph and map](https://docs.repowise.dev/multi-repo/system-map),
[blast radius](https://docs.repowise.dev/multi-repo/blast-radius),
[breaking-change guard](https://docs.repowise.dev/multi-repo/breaking-changes),
[architecture conformance](https://docs.repowise.dev/multi-repo/conformance),
[architecture metrics](https://docs.repowise.dev/multi-repo/architecture-metrics), and
[Workspace MCP mode](https://docs.repowise.dev/multi-repo/workspace-mcp).

> **Note**
>
> **One MCP server, every repo.** The MCP server knows about the whole
> workspace. You don't need to spin up one server per repo: your editor
> talks to a single endpoint and the tools route by `repo`.

On Hosted, a workspace groups repos you have already indexed, with the system map, contracts and co-change views in the dashboard, and on Pro and Teams one MCP URL that answers across every member.

[Hosted workspace MCP](https://docs.repowise.dev/hosted/connecting-ide#across-a-whole-workspace)

[Try hosted](https://repowise.dev/login?mode=signup)