Multi-Repo Projects

Many platforms are not a single repository — they’re a root directory holding N service repos (auth-service/, billing-service/, …), with or without git at the root itself. Archon models this as a folder project: a directory for which Archon applies no git machinery (no managed worktree, branch or pull request), whether or not it is a git repository. Folder projects also fit a single repository you want to run in place, or a business-operations folder with no git at all. They get identity, per-project env vars, run history and artifact storage like repo projects. Register the root once, and every workflow and chat runs in place at that root by default, so the agent sees all contained repos at once. Opt into overlay-isolated, approval-gated container execution with --container (see the Container isolation guide).

Register the root

From the multi-repo root, run any workflow with --folder. The first run registers the folder project; later runs from the root or ordinary subdirectories need no flag. For cross-service runs, start at the registered folder root or pass --cwd ~/platform. Running from inside a nested Git service repository resolves that service as its own repository project and registers it on first use.

cd ~/platform          # contains auth-service/, billing-service/, ... — with or without git at the root
archon workflow run archon-investigate --folder "How do these services call each other?"
# → Registered folder project "platform" (~/platform)
# → Folder project — running in place (no worktree isolation).

You can also register from chat (/register-project --folder platform ~/platform) or the web console’s Add Project (choose Local path, paste the path and select Register as a folder project). These choices work for git roots too. Without an explicit choice, web and chat auto-detect non-git paths as folders and git paths as repos. An existing repo registration is not converted.

How work happens across repos

The agent’s working directory is the root, so it can cd into any child repo, read across services, and make coordinated changes in one run.
Per-service git is the agent’s job. Archon does not create a worktree or manage branches/PRs for a folder project — the agent runs git/gh itself inside each service repo (branch, commit, push, open PR). Your workflow prompts should instruct it to do so per service.
The chat /status command and archon doctor list the contained repos so you can confirm what’s in scope:
```
Contains 20 git repos: auth-service, billing-service, … (+10 more)
```
Artifacts and logs are stored under ~/.archon/workspaces/_folder/<slug>/, and per-project env vars work exactly as for repo projects.

When you want isolation for one service

Folder projects intentionally run in the live checkout — --branch and --from are rejected, and /worktree reports “not applicable”. If you want Archon-managed worktree isolation for a single service (an isolated branch per run, auto PR flow), register that service repo as its own project:

cd ~/platform/auth-service       # a real git repo
archon workflow run archon-implement --branch fix-auth "Fix the token refresh bug"
# → normal repo project: isolated worktree + branch, no --folder

The two models compose: keep the root registered as a folder project for cross-service work, and register individual services as repo projects when you want per-run isolation for just that service.

Not a fit for

Archon-managed branching/PRs spanning child repos — the agent coordinates git across services itself; Archon does not create a composed multi-repo worktree (a future isolation backend may).
A repo you want isolated per run — register that repo directly (repo project), not the parent folder.