Multi-Project Assignment

A single minion can be assigned to multiple projects as either a PM or an Engineer. This guide covers the trade-offs and recommended practices for multi-project assignments.

Project weight classification

Not all projects demand the same amount of resources. Understanding the “weight” of a project helps you decide whether a minion can handle multiple assignments.

Weight	Characteristics	Examples
Heavyweight	Local DB (Supabase, PostgreSQL), Docker containers, MCP servers with project-specific config, port-heavy services	Full-stack app with Supabase, microservice architecture
Lightweight	Static files, no local services, minimal tooling	Landing page, documentation site, simple scripts

Recommended assignment patterns

Pattern	Risk	Recommendation
Lightweight + Lightweight	Minimal	One minion can handle both comfortably
Heavyweight + Lightweight	Low	Works well with directory separation
Heavyweight + Heavyweight	High	Use separate minions

What can go wrong

1. Memory contamination

A minion’s long-term memory is stored in a single SQLite database. Without scoping, learnings from Project A (coding conventions, architecture decisions) can bleed into Project B as noise.

Mitigation: Memory entries support project_id scoping. Project-specific knowledge is tagged with its project ID, while universal know-how (user preferences, general skills) remains unscoped. When querying with a project_id, only that project’s memories plus universal entries are returned.

# Project-scoped memory search
curl -H "Authorization: Bearer $API_TOKEN" \
  "http://localhost:8080/api/memory?search=keyword&project_id=PROJECT_UUID"

# Universal memory (all projects)
curl -H "Authorization: Bearer $API_TOKEN" \
  "http://localhost:8080/api/memory?search=keyword"

2. MCP server configuration conflicts

The .mcp.json file is shared across the minion. If two heavyweight projects require different MCP server configurations (e.g., different Supabase connection strings), the last deployed configuration wins.

Mitigation: For heavyweight + lightweight combinations, this is rarely an issue since the lightweight project typically doesn’t need project-specific MCP servers. For heavyweight + heavyweight, use separate minions.

3. Environment variable and secret collisions

Minion secrets are loaded flat into process.env. If Project A and Project B both need SUPABASE_URL or DATABASE_URL with different values, they will collide.

Mitigation: Use distinct variable names per project (e.g., PROJECT_A_SUPABASE_URL), or assign separate minions for projects with overlapping secret names.

4. Port conflicts

Heavyweight projects often run local services (Supabase on port 54321, dev servers, Docker containers). Two heavyweight projects will compete for the same default ports.

Mitigation: Assign separate minions. Port reconfiguration is fragile and error-prone.

5. Skill name collisions

Skills are stored globally in ~/.claude/skills/<name>/. If two projects define a skill with the same name (e.g., deploy, test) but different content, the later deployment overwrites the earlier one.

Mitigation: Use project-prefixed skill names (e.g., projectA-deploy, projectB-deploy).

6. Docker and resource contention

Each heavyweight project may run its own set of Docker containers, consuming memory and CPU on what is typically a modestly sized VPS (Lightsail).

Mitigation: Monitor resource usage. If the minion’s VPS is struggling, split the projects across separate minions.

Best practices

Separate work directories

Always use distinct work directories per project:

~/projects/
  project-a/    # Heavyweight full-stack app
  project-b/    # Lightweight static site

Tag memories with project scope

When saving learnings that are project-specific (tech stack, conventions, architecture decisions), include the project_id. Keep user preferences and general know-how as universal (no project_id).

Memory type	Scope	Example
User preferences	Universal	”User prefers Japanese code reviews”
General technique	Universal	”Use FTS5 trigram tokenizer for Japanese search”
Project architecture	Project-scoped	”Project A uses Next.js 16 + Supabase”
Project conventions	Project-scoped	”Project A requires ESLint strict mode”

When in doubt, use a separate minion

The cost of running an additional Lightsail VPS is low compared to the debugging time lost to cross-project contamination. If two projects are both heavyweight, give each its own minion.