Skip to main content
Projects are the core organizational unit in Agent Orchestrator. Each project represents a repository that agents can work on.

​
Basic Project Configuration

Every project requires at minimum: 
projects:
  my-app:
    repo: org/my-app
    path: ~/my-app
    defaultBranch: main
​
projects.<id>
object
required
The project ID (key) becomes the internal identifier. Choose something short and memorable.

​
Required Fields

​
repo
string
required
GitHub repository in owner/repo format.
repo: ComposioHQ/agent-orchestrator
​
path
string
required
Local path to the repository. Supports ~ for home directory.
path: ~/projects/my-app
​
defaultBranch
string
default:"main"
The main branch name. Usually main or master.
defaultBranch: main

​
Optional Fields

​
name
string
Display name for the project. Defaults to the project ID if not specified.
name: "My Awesome App"
​
sessionPrefix
string
Prefix for session IDs (e.g., app → app-1, app-2). Must match [a-zA-Z0-9_-]+.If not specified, automatically generated from the project path basename.
sessionPrefix: app
Session prefixes must be unique across all projects. If you have multiple projects with similar names, explicitly set different prefixes.

​
Plugin Overrides

Override default plugins for a specific project:
​
runtime
string
Override the runtime plugin for this project.
runtime: docker  # Use Docker instead of tmux
​
agent
string
Override the agent plugin for this project.
agent: codex  # Use Codex instead of Claude Code
​
workspace
string
Override the workspace plugin for this project.
workspace: clone  # Use full clones instead of worktrees

​
Example: Different Runtimes per Project

defaults:
  runtime: tmux
  agent: claude-code
  workspace: worktree

projects:
  frontend:
    repo: org/frontend
    path: ~/frontend
    # Uses default: tmux runtime

  backend:
    repo: org/backend
    path: ~/backend
    runtime: docker  # Override: Use Docker for backend

​
Issue Tracker Configuration

​
tracker
object
Configure the issue tracker for this project. Defaults to GitHub Issues if not specified.

​
GitHub Issues (Default)

projects:
  my-app:
    repo: org/my-app
    path: ~/my-app
    # tracker defaults to github

​
Linear

projects:
  my-app:
    repo: org/my-app
    path: ~/my-app
    tracker:
      plugin: linear
      teamId: "your-team-id"
Linear requires LINEAR_API_KEY environment variable. Get your API key from https://linear.app/settings/api

​
Custom Trackers

You can implement custom tracker plugins for Jira, Asana, or any other system. See packages/plugins/tracker-* for examples. Source: packages/core/src/types.ts:899-907

​
SCM Configuration

​
scm
object
Source control management configuration. Usually auto-inferred from repo.
For GitHub repositories, SCM is automatically set to github: 
projects:
  my-app:
    repo: org/my-app  # SCM automatically set to github
    path: ~/my-app
Explicit configuration (rarely needed): 
projects:
  my-app:
    repo: org/my-app
    path: ~/my-app
    scm:
      plugin: github
Source: packages/core/src/config.ts:144-151

​
Workspace Customization

​
symlinks
array
Files or directories to symlink from the main repo into each workspace.Useful for sharing environment files, credentials, or config across sessions.
projects:
  my-app:
    repo: org/my-app
    path: ~/my-app
    symlinks:
      - .env
      - .claude
      - credentials/
Symlinks are created after workspace setup, pointing back to the main repository.

​
Post-Creation Commands

​
postCreate
array
Commands to run after workspace creation (after git worktree/clone).Commonly used for installing dependencies or setting up the environment.
projects:
  my-app:
    repo: org/my-app
    path: ~/my-app
    postCreate:
      - "pnpm install"
      - "cp .env.example .env"
      - "pnpm build"
Commands run in the workspace directory. If any command fails, workspace creation fails.

​
Agent Configuration

​
agentConfig
object
Agent-specific settings that control how the agent runs.
​
agentConfig.permissions
enum
default:"skip"
How to handle Claude Code’s permission prompts:
  • skip — Use --dangerously-skip-permissions (recommended for automation)
  • default — Use default behavior (interactive prompts)
agentConfig:
  permissions: skip
​
agentConfig.model
string
Override the AI model for this project.
agentConfig:
  model: opus  # For Claude
  # model: gpt-4  # For OpenAI-based agents
Source: packages/core/src/config.ts:54-59

​
Agent Rules

Agent rules are instructions included in every agent prompt for a project. Use them to enforce coding standards, testing requirements, or project-specific conventions.

​
Inline Rules

​
agentRules
string
Inline rules as a YAML multiline string.
projects:
  my-app:
    repo: org/my-app
    path: ~/my-app
    agentRules: |
      Always run tests before pushing.
      Use conventional commits (feat:, fix:, chore:).
      Link issue numbers in commit messages (#123).
      Follow TypeScript strict mode.

​
External Rules File

​
agentRulesFile
string
Path to a file containing agent rules, relative to the project path.
projects:
  my-app:
    repo: org/my-app
    path: ~/my-app
    agentRulesFile: .agent-rules.md
Example .agent-rules.md: 
# Agent Rules for My App

## Code Style
- Use TypeScript strict mode
- Prefer functional components in React
- Use named exports

## Testing
- Write unit tests for all new functions
- Run `pnpm test` before pushing
- Maintain 80% code coverage

## Commits
- Use conventional commits: feat:, fix:, chore:
- Link issue numbers: "fix: resolve auth bug (#123)"
- Keep commits atomic and focused
Rules are loaded once at agent spawn time. Changes to rule files don’t affect running sessions.

​
Per-Project Reactions

​
reactions
object
Override global reaction configs for this project.
Enable auto-merge for a specific project: 
projects:
  my-app:
    repo: org/my-app
    path: ~/my-app
    reactions:
      approved-and-green:
        auto: true  # Enable auto-merge for this project only
        action: auto-merge
More aggressive CI retry for a flaky project: 
projects:
  flaky-tests:
    repo: org/flaky-tests
    path: ~/flaky-tests
    reactions:
      ci-failed:
        auto: true
        action: send-to-agent
        retries: 5  # Retry up to 5 times instead of default 2
See Reactions for full details on reaction configuration.

​
Multi-Project Setup

Manage multiple repositories in a single configuration: 
defaults:
  runtime: tmux
  agent: claude-code
  workspace: worktree
  notifiers: [desktop, slack]

projects:
  frontend:
    name: Frontend
    repo: org/frontend
    path: ~/frontend
    defaultBranch: main
    sessionPrefix: fe
    
    tracker:
      plugin: github
    
    agentRules: |
      Use TypeScript strict mode.
      Follow React best practices.
      Always run `pnpm test` before pushing.

  backend:
    name: Backend API
    repo: org/backend
    path: ~/backend
    defaultBranch: main
    sessionPrefix: api
    
    tracker:
      plugin: linear
      teamId: "your-team-id"
    
    agentRules: |
      All endpoints require auth middleware.
      Add OpenAPI docs for new routes.
      Run `pnpm test` and `pnpm lint` before pushing.

  mobile:
    name: Mobile App
    repo: org/mobile
    path: ~/mobile
    defaultBranch: develop
    sessionPrefix: mob
    
    agentConfig:
      model: opus  # Use more powerful model for complex mobile work
Source: examples/multi-project.yaml
Ensure each project has a unique sessionPrefix to avoid collisions.

​
Project Uniqueness Validation

Agent Orchestrator validates that:
  1. Project IDs (directory basenames) are unique
  2. Session prefixes are unique
If you have duplicate basenames: 
projects:
  app-frontend:
    path: ~/repos/app  # basename: "app"
  
  app-backend:
    path: ~/projects/app  # basename: "app" — CONFLICT!
You’ll get an error: 
Duplicate project ID detected: "app"
Multiple projects have the same directory basename.
Solution: Use unique directory names or explicit session prefixes: 
projects:
  app-frontend:
    path: ~/repos/app-frontend
    sessionPrefix: fe
  
  app-backend:
    path: ~/projects/app-backend
    sessionPrefix: be
Source: packages/core/src/config.ts:157-212

​
Complete Example

A fully-configured project with all options: 
projects:
  my-app:
    name: "My Application"
    repo: org/my-app
    path: ~/projects/my-app
    defaultBranch: main
    sessionPrefix: app
    
    # Plugin overrides
    runtime: docker
    agent: claude-code
    workspace: worktree
    
    # Issue tracker
    tracker:
      plugin: linear
      teamId: "abc123"
    
    # SCM (auto-inferred, shown for completeness)
    scm:
      plugin: github
    
    # Workspace setup
    symlinks:
      - .env
      - .claude
    
    postCreate:
      - "pnpm install"
      - "pnpm build"
    
    # Agent configuration
    agentConfig:
      permissions: skip
      model: opus
    
    # Agent rules
    agentRules: |
      Always run tests before pushing.
      Use conventional commits.
      Link issue numbers in commits.
    
    # Per-project reactions
    reactions:
      approved-and-green:
        auto: true
        action: auto-merge

​
Next Steps

Reactions

Configure auto-responses to CI failures, reviews, and events

Notifications

Set up Slack, Discord, and custom notification routing

Build docs developers (and LLMs) love

Get started for freeTalk to us