Modular projects

A modular project lets you run one coordinated swarm across multiple folders. Example: an API repo, a web app, and a read-only protos package, without merging them into a single git root.

At a glance

• One project manifest under ~/.pytxo/projects/<id>.toml
• Each folder is a root with a short label (api, web, protos)
• Tasks in pytxo.toml can set root = "web" to run on that folder
• Read-only roots contribute context but never receive writes
• Each writable root can use its own permission tier

Create a project

pytxo project init my-platform \
  --add ~/dev/api \
  --add ~/dev/web \
  --add ~/dev/protos

List roots:

pytxo project list --id my-platform

Run across roots

pytxo project run --id my-platform --cmd "echo pytxo" --agents 3

One run_id spans all writable roots. The scheduler warns when two roots claim overlapping paths in the same wave.

Pytxo Desktop Workspaces

In Desktop, a modular project is a Workspace:

• Workspaces home lists recent projects and folders
• Workspace folders panel lists each root (primary, read-only, permission tier)
• Topology and agents can show per-root labels when a multi-root Workspace is open

Configuration

In the project manifest:

[project]
id = "my-platform"
name = "My Platform"

[[roots]]
path = "/home/dev/api"
label = "api"
primary = true

[[roots]]
path = "/home/dev/web"
label = "web"

[[roots]]
path = "/home/dev/protos"
label = "protos"
read_only = true
permission_profile = "deep_space"

Per-root permission_profile overrides the repo default for agents executing on that root.

Fleet vs modular project

See Fleet runs.

Back: Execution domains