> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ComposioHQ/agent-orchestrator/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```yaml theme={null}
projects:
  my-app:
    repo: org/my-app
    path: ~/my-app
    defaultBranch: main
```

<ParamField path="projects.<id>" type="object" required>
  The project ID (key) becomes the internal identifier. Choose something short and memorable.
</ParamField>

## Required Fields

<ParamField path="repo" type="string" required>
  GitHub repository in `owner/repo` format.

  ```yaml theme={null}
  repo: ComposioHQ/agent-orchestrator
  ```
</ParamField>

<ParamField path="path" type="string" required>
  Local path to the repository. Supports `~` for home directory.

  ```yaml theme={null}
  path: ~/projects/my-app
  ```
</ParamField>

<ParamField path="defaultBranch" type="string" default="main">
  The main branch name. Usually `main` or `master`.

  ```yaml theme={null}
  defaultBranch: main
  ```
</ParamField>

## Optional Fields

<ParamField path="name" type="string">
  Display name for the project. Defaults to the project ID if not specified.

  ```yaml theme={null}
  name: "My Awesome App"
  ```
</ParamField>

<ParamField path="sessionPrefix" type="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.

  ```yaml theme={null}
  sessionPrefix: app
  ```
</ParamField>

<Warning>
  **Session prefixes must be unique** across all projects. If you have multiple projects with similar names, explicitly set different prefixes.
</Warning>

## Plugin Overrides

Override default plugins for a specific project:

<ParamField path="runtime" type="string">
  Override the runtime plugin for this project.

  ```yaml theme={null}
  runtime: docker  # Use Docker instead of tmux
  ```
</ParamField>

<ParamField path="agent" type="string">
  Override the agent plugin for this project.

  ```yaml theme={null}
  agent: codex  # Use Codex instead of Claude Code
  ```
</ParamField>

<ParamField path="workspace" type="string">
  Override the workspace plugin for this project.

  ```yaml theme={null}
  workspace: clone  # Use full clones instead of worktrees
  ```
</ParamField>

### Example: Different Runtimes per Project

```yaml theme={null}
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

<ParamField path="tracker" type="object">
  Configure the issue tracker for this project. Defaults to GitHub Issues if not specified.
</ParamField>

### GitHub Issues (Default)

```yaml theme={null}
projects:
  my-app:
    repo: org/my-app
    path: ~/my-app
    # tracker defaults to github
```

### Linear

```yaml theme={null}
projects:
  my-app:
    repo: org/my-app
    path: ~/my-app
    tracker:
      plugin: linear
      teamId: "your-team-id"
```

<Note>
  Linear requires `LINEAR_API_KEY` environment variable. Get your API key from [https://linear.app/settings/api](https://linear.app/settings/api)
</Note>

### 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

<ParamField path="scm" type="object">
  Source control management configuration. Usually auto-inferred from `repo`.
</ParamField>

For GitHub repositories, SCM is automatically set to `github`:

```yaml theme={null}
projects:
  my-app:
    repo: org/my-app  # SCM automatically set to github
    path: ~/my-app
```

Explicit configuration (rarely needed):

```yaml theme={null}
projects:
  my-app:
    repo: org/my-app
    path: ~/my-app
    scm:
      plugin: github
```

Source: `packages/core/src/config.ts:144-151`

## Workspace Customization

### Symlinks

<ParamField path="symlinks" type="array">
  Files or directories to symlink from the main repo into each workspace.

  Useful for sharing environment files, credentials, or config across sessions.
</ParamField>

```yaml theme={null}
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

<ParamField path="postCreate" type="array">
  Commands to run after workspace creation (after git worktree/clone).

  Commonly used for installing dependencies or setting up the environment.
</ParamField>

```yaml theme={null}
projects:
  my-app:
    repo: org/my-app
    path: ~/my-app
    postCreate:
      - "pnpm install"
      - "cp .env.example .env"
      - "pnpm build"
```

<Info>
  Commands run in the workspace directory. If any command fails, workspace creation fails.
</Info>

## Agent Configuration

<ParamField path="agentConfig" type="object">
  Agent-specific settings that control how the agent runs.
</ParamField>

<ParamField path="agentConfig.permissions" type="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)

  ```yaml theme={null}
  agentConfig:
    permissions: skip
  ```
</ParamField>

<ParamField path="agentConfig.model" type="string">
  Override the AI model for this project.

  ```yaml theme={null}
  agentConfig:
    model: opus  # For Claude
    # model: gpt-4  # For OpenAI-based agents
  ```
</ParamField>

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

<ParamField path="agentRules" type="string">
  Inline rules as a YAML multiline string.
</ParamField>

```yaml theme={null}
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

<ParamField path="agentRulesFile" type="string">
  Path to a file containing agent rules, relative to the project path.
</ParamField>

```yaml theme={null}
projects:
  my-app:
    repo: org/my-app
    path: ~/my-app
    agentRulesFile: .agent-rules.md
```

Example `.agent-rules.md`:

```markdown theme={null}
# 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
```

<Note>
  Rules are loaded once at agent spawn time. Changes to rule files don't affect running sessions.
</Note>

## Per-Project Reactions

<ParamField path="reactions" type="object">
  Override global reaction configs for this project.
</ParamField>

Enable auto-merge for a specific project:

```yaml theme={null}
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:

```yaml theme={null}
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](/configuration/reactions) for full details on reaction configuration.

## Multi-Project Setup

Manage multiple repositories in a single configuration:

```yaml theme={null}
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`

<Warning>
  Ensure each project has a unique `sessionPrefix` to avoid collisions.
</Warning>

## Project Uniqueness Validation

Agent Orchestrator validates that:

1. **Project IDs (directory basenames) are unique**
2. **Session prefixes are unique**

If you have duplicate basenames:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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

<CardGroup cols={2}>
  <Card title="Reactions" icon="bolt" href="/configuration/reactions">
    Configure auto-responses to CI failures, reviews, and events
  </Card>

  <Card title="Notifications" icon="bell" href="/configuration/notifications">
    Set up Slack, Discord, and custom notification routing
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.