Project Configuration

Configure projects with repositories, branches, trackers, and per-project overrides

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

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