Project Integration & Context Paths

Project Integration & Context Paths#

NEW in v0.0.21 - Directory-level context paths ENHANCED in v0.0.26 - File-level context paths

Work directly with your existing projects! Context paths allow you to share specific directories or individual files with all agents while maintaining granular permission control.

Quick Start#

For coding projects (recommended - auto-detects context from current directory):

# Run from your project directory - MassGen will offer to add it as context
cd /path/to/your-project
uv run massgen "Enhance the website with dark/light theme toggle and interactive features"

Using explicit config (for predefined setups):

massgen \
  --config @examples/tools/filesystem/gpt5mini_cc_fs_context_path.yaml \
  "Enhance the website with dark/light theme toggle and interactive features"

Configuration#

Context Paths Setup#

Share directories or individual files with all agents using context_paths:

agents:
  - id: "code-reviewer"
    backend:
      type: "claude_code"
      cwd: "workspace"          # Agent's isolated work area

orchestrator:
  # Required for file operations
  snapshot_storage: "snapshots"
  agent_temporary_workspace: "temp_workspaces"

  # Context paths - directories OR individual files
  context_paths:
    - path: "/home/user/my-project/src"           # Directory access
      permission: "read"                          # Agents can analyze your code
    - path: "/home/user/my-project/docs"          # Directory access
      permission: "write"                         # Final agent can update docs
    - path: "/home/user/my-project/config.yaml"   # Single file access (v0.0.26+)
      permission: "read"                          # Access only this file

Configuration Parameters#

Parameter	Required	Description
`context_paths`	Yes	List of shared directories or files for all agents
`path`	Yes	Absolute path to directory OR file (both supported as of v0.0.26)
`permission`	Yes	Access level: `"read"` or `"write"`
`snapshot_storage`	Yes	Directory for workspace snapshots (required for file operations)
`agent_temporary_workspace`	Yes	Parent directory for temporary workspaces (required for file operations)

Note

v0.0.26+: Context paths can now point to individual files in addition to directories. This allows you to grant agents access to specific configuration files or reference documents without exposing the entire directory.

File-level access: When a file path is provided, agents can only access that specific file - sibling files in the same directory are blocked for security.

Permissions Model#

Context vs Final Agent Permissions#

Different permission levels during different phases:

During Coordination (Context Agents):: All context paths are READ-ONLY, regardless of configuration. This protects your files during multi-agent discussion.
Final Presentation (Winning Agent):: The winning agent gets the configured permission (read or write) for final execution.

Example:

orchestrator:
  context_paths:
    - path: "/home/user/project/src"
      permission: "write"

What happens:

Coordination phase → All agents have READ access to /src
Final presentation → Winning agent has WRITE access to /src

Read Permission#

Agents can:

Read all files in the directory
Analyze code structure
Extract information
Reference content in responses

Agents cannot:

Create new files
Modify existing files
Delete files

Use cases:

Code review and analysis
Documentation generation from source code
Data extraction and reporting
Pattern detection and recommendations

Write Permission#

Final agent can:

Read all files
Create new files
Modify existing files
Delete files (with read-before-delete safety)

Use cases:

Code refactoring and updates
Documentation updates
Test generation
Project modernization

Multi-Agent Project Collaboration#

Advanced Example#

agents:
  - id: "analyzer"
    backend:
      type: "gemini"
      cwd: "analysis_workspace"

  - id: "implementer"
    backend:
      type: "claude_code"
      cwd: "implementation_workspace"

orchestrator:
  # Required for file operations
  snapshot_storage: "snapshots"
  agent_temporary_workspace: "temp_workspaces"

  # Context paths - mix of directories and files
  context_paths:
    - path: "/home/user/legacy-app/src"              # Directory access
      permission: "read"                             # Read existing codebase
    - path: "/home/user/legacy-app/.env.example"    # Single file access (v0.0.26+)
      permission: "read"                             # Access only env template
    - path: "/home/user/legacy-app/tests"            # Directory access
      permission: "write"                            # Write new tests
    - path: "/home/user/modernized-app"              # Directory access
      permission: "write"                            # Create modernized version

This configuration:

All agents can read the legacy codebase directory
Agents can access the .env.example template but not other config files
All agents can discuss modernization approaches
Winning agent can write tests and create modernized version

Clean Project Organization#

The .massgen/ Directory#

All MassGen working files are organized under .massgen/ in your project root:

your-project/
├── .massgen/                          # All MassGen state
│   ├── sessions/                      # Multi-turn conversation history
│   │   └── session_20250108_143022/
│   │       ├── turn_1/                # Results from turn 1
│   │       ├── turn_2/                # Results from turn 2
│   │       └── SESSION_SUMMARY.txt    # Human-readable summary
│   ├── workspaces/                    # Agent working directories
│   │   ├── analysis_workspace/        # Analyzer's isolated workspace
│   │   └── implementation_workspace/  # Implementer's workspace
│   ├── snapshots/                     # Workspace snapshots for coordination
│   └── temp_workspaces/               # Previous turn results for context
├── src/                               # Your actual project files
├── tests/                             # Your tests
└── docs/                              # Your documentation

Benefits#

✅ Clean Projects: All MassGen files contained in one directory
✅ Easy .gitignore: Just add .massgen/ to your .gitignore
✅ Portable: Move or delete .massgen/ without affecting your project
✅ Multi-Turn Sessions: Conversation history preserved across sessions

Configuration Auto-Organization#

You specify simple names, MassGen organizes under .massgen/:

orchestrator:
  snapshot_storage: "snapshots"         # → .massgen/snapshots/ (REQUIRED)
  agent_temporary_workspace: "temp"     # → .massgen/temp/ (REQUIRED)

agents:
  - backend:
      cwd: "workspace1"                 # → .massgen/workspaces/workspace1/

Note

snapshot_storage and agent_temporary_workspace are required when using file operations or context paths.

Adding to .gitignore#

# MassGen state and working files
.massgen/

This excludes all MassGen temporary files, sessions, and workspaces from version control while keeping your project clean.

Use Cases#

Code Review#

Agents analyze your source code and suggest improvements:

orchestrator:
  snapshot_storage: "snapshots"
  agent_temporary_workspace: "temp_workspaces"

  context_paths:
    - path: "/home/user/project/src"
      permission: "read"
    - path: "/home/user/project/review-notes"
      permission: "write"

# Run from project directory - recommended for coding
cd /home/user/project
uv run massgen "Review the authentication module for security issues and best practices"

# Or with explicit config
massgen \
  --config code_review.yaml \
  "Review the authentication module for security issues and best practices"

Documentation Generation#

Agents read project code to understand context and generate/update documentation:

orchestrator:
  snapshot_storage: "snapshots"
  agent_temporary_workspace: "temp_workspaces"

  context_paths:
    - path: "/home/user/project/src"
      permission: "read"
    - path: "/home/user/project/docs"
      permission: "write"

# Run from project directory - recommended for coding
cd /home/user/project
uv run massgen "Update the API documentation to reflect recent changes in the auth module"

# Or with explicit config
massgen \
  --config doc_generator.yaml \
  "Update the API documentation to reflect recent changes in the auth module"

Data Processing#

Agents access shared datasets and generate analysis reports:

orchestrator:
  snapshot_storage: "snapshots"
  agent_temporary_workspace: "temp_workspaces"

  context_paths:
    - path: "/home/user/datasets"
      permission: "read"
    - path: "/home/user/reports"
      permission: "write"

# Run from project directory - recommended
cd /home/user
uv run massgen "Analyze the Q4 sales data and create a comprehensive report with visualizations"

# Or with explicit config
massgen \
  --config data_analysis.yaml \
  "Analyze the Q4 sales data and create a comprehensive report with visualizations"

Project Migration#

Agents examine existing projects and create modernized versions:

orchestrator:
  snapshot_storage: "snapshots"
  agent_temporary_workspace: "temp_workspaces"

  context_paths:
    - path: "/home/user/old-project"
      permission: "read"
    - path: "/home/user/new-project"
      permission: "write"

# Run from project directory - recommended for coding
cd /home/user/old-project
uv run massgen "Migrate the Flask 1.x application to Flask 3.x with modern best practices"

# Or with explicit config
massgen \
  --config migration.yaml \
  "Migrate the Flask 1.x application to Flask 3.x with modern best practices"

Project Instructions (CLAUDE.md / AGENTS.md)#

NEW in v0.1.36 - Automatic discovery of project instruction files

MassGen automatically discovers and includes project instruction files (CLAUDE.md or AGENTS.md) when they exist in your context paths. This follows the agents.md standard for coding agent instructions.

Quick Example#

Create a CLAUDE.md or AGENTS.md file in your project root:

# MyProject Instructions

## Build & Test
- Run `npm install` before testing
- Tests use pytest: `pytest tests/`

## Code Style
- Use TypeScript strict mode
- Follow ESLint configuration in `.eslintrc`

Then run MassGen with your project as a context path:

cd /path/to/myproject
uv run massgen "@. Add dark mode toggle to the settings page"

The contents of CLAUDE.md will automatically be included in the agent’s system prompt.

Supported Files#

MassGen supports both standard formats:

File	Description
`CLAUDE.md`	Claude Code specific instructions (takes precedence)
`AGENTS.md`	Universal standard for coding agents (agents.md, 60k+ projects)

Priority: If both files exist, CLAUDE.md takes precedence.

How Discovery Works#

MassGen uses hierarchical discovery with “closest wins” semantics:

Starts at your context path
Walks up to workspace root looking for CLAUDE.md or AGENTS.md
Returns the closest file found
CLAUDE.md is preferred over AGENTS.md at the same directory level

Example structure:

/myproject/                   # Root
├── AGENTS.md                 # Project-wide instructions
├── src/
│   ├── CLAUDE.md             # Source-specific instructions (closest wins for src/)
│   └── api/
│       └── handler.py
└── docs/
    └── AGENTS.md             # Docs-specific instructions

If you specify @/myproject/src/api:

MassGen finds /myproject/src/CLAUDE.md (closest to api/)
Root AGENTS.md is ignored (src/CLAUDE.md is closer)

Configuration Examples#

Option 1: Directory with instruction file

orchestrator:
  context_paths:
    - path: "/Users/me/myproject"
      permission: "read"

If /Users/me/myproject/CLAUDE.md or AGENTS.md exists, it’s automatically included.

Option 2: Explicit file reference

massgen "@CLAUDE.md @src/ Review the authentication module"

Option 3: Using @path syntax (CLI)

# Discovers CLAUDE.md from project root
cd /Users/me/myproject
massgen "@. Add user profile page"

Important Notes#

Note

Context, not strict instructions: The contents of CLAUDE.md/AGENTS.md are provided as reference context that may or may not be relevant to the current task. Agents use these as helpful guidelines when applicable but are not required to follow every instruction.

This differs from operational system prompt instructions - think of it like README.md for agents.

Static loading:: Instruction files are read once at session start. Changes during execution require restarting the session.
Workspace boundary:: Discovery stops at your workspace root - files outside the workspace are not searched.
Deduplication:: If multiple context paths resolve to the same instruction file, it’s only included once.

Real-World Example#

# CLAUDE.md

# Acme Web App

## Build Process
```bash
npm install
npm run build
npm test
```

## Architecture
- Frontend: React 18 + TypeScript
- Backend: FastAPI + PostgreSQL
- Tests: Jest for frontend, pytest for backend

## Code Style
- Use TypeScript strict mode
- Follow Airbnb style guide
- 100% test coverage required for API endpoints

## Testing
- Run `npm test` for frontend tests
- Run `pytest` for backend tests
- CI runs both on every PR

Usage:

cd acme-web-app
massgen "@. Add pagination to the users list endpoint"

Agents will receive the build instructions, architecture context, and testing requirements automatically.

Best Practices#

Keep it concise: Agents receive this as context, so focus on essential information
Include build steps: How to set up the development environment
Document conventions: Code style, naming patterns, testing requirements
Use both if needed: CLAUDE.md for Claude-specific optimizations, AGENTS.md for universal compatibility
Update regularly: Keep instructions current as your project evolves

Security Considerations#

Warning

Agents can autonomously read/write files in context paths with write permission.

Before granting write access:

✅ Backup your code - Ensure you have version control or backups
✅ Test first - Try with read-only permission first
✅ Isolated projects - Consider testing on a copy of your project
✅ Review permissions - Double-check which paths have write access
✅ Use version control - Git/VCS allows easy rollback

Path Validation#

MassGen validates all context paths at startup:

✅ Paths must exist
✅ Paths must be directories (not files)
✅ Paths must be absolute (not relative)

Error messages:

Error: Context path '/home/user/project/file.txt' is not a directory
Error: Context path '/home/user/missing' does not exist
Error: Context path must be absolute, got 'relative/path'

Best Practices#

Start with read-only - Analyze before modifying
Granular permissions - Only grant write where needed
Use .gitignore - Exclude .massgen/ from version control
Review agent work - Check .massgen/workspaces/ before accepting changes
Backup important projects - Use Git or other VCS
Test configurations - Try on sample projects first

Example: Complete Project Setup#

agents:
  - id: "analyzer"
    backend:
      type: "gemini"
      model: "gemini-2.5-flash"
      cwd: "analyzer_workspace"

  - id: "developer"
    backend:
      type: "claude_code"
      model: "claude-sonnet-4"
      cwd: "developer_workspace"

orchestrator:
  # Required for file operations
  snapshot_storage: "snapshots"
  agent_temporary_workspace: "temp"

  # Project integration - mix of directories and files
  context_paths:
    - path: "/Users/me/myproject/src"                  # Directory: analyze existing code
      permission: "read"
    - path: "/Users/me/myproject/pytest.ini"           # File: read test config (v0.0.26+)
      permission: "read"
    - path: "/Users/me/myproject/tests"                # Directory: generate tests
      permission: "write"
    - path: "/Users/me/myproject/docs"                 # Directory: update documentation
      permission: "write"

ui:
  display_type: "rich_terminal"
  logging_enabled: true

Project structure after running:

myproject/
├── .massgen/                    # All MassGen state
│   ├── workspaces/
│   │   ├── analyzer_workspace/
│   │   └── developer_workspace/
│   ├── snapshots/
│   ├── sessions/
│   └── temp/
├── src/                         # Your source (read access)
├── tests/                       # Generated tests (write access)
├── docs/                        # Updated docs (write access)
└── .gitignore                   # Contains .massgen/

Protected Paths#

Protected paths allow you to make specific files or directories read-only within writable context paths, preventing agents from modifying or deleting critical reference files while allowing them to edit other files.

Note

Use Case: You want agents to modify some files in a directory but keep certain reference files, configurations, or templates untouched.

Basic Configuration#

Protect specific files within a writable context path:

orchestrator:
  snapshot_storage: "snapshots"
  agent_temporary_workspace: "temp_workspaces"

  context_paths:
    - path: "/absolute/path/to/directory"
      permission: "write"
      protected_paths:
        - "important_file.txt"
        - "config.json"

Result:

Agents can read and modify all files except important_file.txt and config.json
Protected files are readable but not writable

Protected Paths Syntax#

Protected paths are relative to the context path:

orchestrator:
  context_paths:
    - path: "/Users/me/project"
      permission: "write"
      protected_paths:
        - "src/config.py"          # Protects /Users/me/project/src/config.py
        - "tests/fixtures/"        # Protects /Users/me/project/tests/fixtures/
        - "README.md"              # File protection
        - "docs/"                  # Directory protection

Common Use Cases#

1. Protect Reference Files: Keep test fixtures unchanged while agents modify code

context_paths:
  - path: "/project"
    permission: "write"
    protected_paths:
      - "tests/fixtures/"
      - "tests/expected_outputs/"

2. Protect Configuration: Allow code changes but prevent config modifications

context_paths:
  - path: "/app"
    permission: "write"
    protected_paths:
      - "config.yaml"
      - ".env.example"
      - "docker-compose.yml"

3. Protect Templates: Generate content without modifying templates

context_paths:
  - path: "/website"
    permission: "write"
    protected_paths:
      - "templates/"
      - "layouts/"

4. Mixed Permissions: Different protection levels across context paths

context_paths:
  # Source code - most files writable, some protected
  - path: "/project/src"
    permission: "write"
    protected_paths:
      - "core/constants.py"
      - "version.py"

  # Docs - completely read-only (no protected_paths needed)
  - path: "/project/docs"
    permission: "read"

  # Temp folder - fully writable
  - path: "/project/temp"
    permission: "write"

How Protection Works#

Protected paths are enforced by the PathPermissionManager:

Startup validation: Checks that protected paths exist within their context path
Runtime enforcement: Blocks write/delete operations on protected paths
Clear error messages: Agents receive descriptive errors when blocked

Agent: Edit /project/config.json
Error: Cannot modify /project/config.json - path is protected

Read Operations: Agents can always read protected files for reference:

Agent: Read config.json        # ✅ Allowed
Agent: Edit config.json         # ❌ Blocked
Agent: Delete config.json       # ❌ Blocked

Directory Protection: Protecting a directory protects all contents recursively:

protected_paths: ["tests/fixtures/"]

✅ Read tests/fixtures/data.json
❌ Write tests/fixtures/data.json
❌ Delete tests/fixtures/
❌ Create tests/fixtures/new_file.txt

Best Practices#

Be explicit: List all critical files rather than assuming default protection
Test first: Run with a test directory to verify protection works

Document: Add comments explaining why files are protected

protected_paths:
  - "schema.sql"        # Database schema - don't modify structure
  - "LICENSE"           # Legal file - must not change

Use read-only when appropriate: If entire directory should be read-only, use permission: "read" instead of protecting all paths

# If everything should be read-only:
- path: "/reference_docs"
  permission: "read"     # Simpler than listing all files

# If you want selective protection:
- path: "/working_dir"
  permission: "write"
  protected_paths: [...]  # Mixed permissions

Combine with planning mode: Use protected paths with planning mode for maximum safety

orchestrator:
  context_paths:
    - path: "/project"
      permission: "write"
      protected_paths: ["config.json"]
  coordination:
    enable_planning_mode: true  # Prevents modifications during coordination

Troubleshooting#

Problem: Agent is modifying a file you marked as protected.

Check:

Verify relative path is correct:

context_paths:
  - path: "/Users/me/project"
    protected_paths:
      - "config.json"         # ✅ Relative to /Users/me/project
      # NOT: "/Users/me/project/config.json"  # ❌ Would be treated as relative

Check the file exists: Protected paths must exist when MassGen starts
Verify write permission: Protection only applies to writable context paths

Problem: “Protected path ‘file.txt’ not found”

Solution: Ensure the file exists before starting MassGen:

ls /project/file.txt  # Check if file exists

Security Note#

Warning

Protected paths are a convenience feature, not a security boundary. For security-critical files:

Use file system permissions (chmod)
Run MassGen with limited user accounts
Store sensitive data outside agent-accessible directories
Review all agent operations before deploying

Next Steps#

File Operations & Workspace Management - Learn more about workspace management and file operation safety
MCP Integration - Additional tools for project work
Planning Mode - Combine with planning mode for safer coordination
Interactive Multi-Turn Mode - Iterative project development across turns
Running MassGen - More examples

Project Integration & Context Paths

Contents

Project Integration & Context Paths#

Quick Start#

Configuration#

Context Paths Setup#

Configuration Parameters#

Permissions Model#

Context vs Final Agent Permissions#

Read Permission#

Write Permission#

Multi-Agent Project Collaboration#

Advanced Example#

Clean Project Organization#

The .massgen/ Directory#

Benefits#

Configuration Auto-Organization#

Adding to .gitignore#

Use Cases#

Code Review#

Documentation Generation#

Data Processing#

Project Migration#

Project Instructions (CLAUDE.md / AGENTS.md)#

Quick Example#

Supported Files#

How Discovery Works#

Configuration Examples#

Important Notes#

Real-World Example#

Best Practices#

Security Considerations#

Path Validation#

Best Practices#

Example: Complete Project Setup#

Protected Paths#

Basic Configuration#

Protected Paths Syntax#

Common Use Cases#

How Protection Works#

Best Practices#

Troubleshooting#

Security Note#

Next Steps#