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

# Contributing

> How to contribute to Agent Orchestrator - development setup, plugin development, and submission guidelines

Contributions are welcome! The plugin system makes it straightforward to add support for new agents, runtimes, trackers, and notification channels.

## Getting Started

### Prerequisites

* Node.js 20+
* pnpm 9.15+
* Git 2.30+

### First-Time Setup

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/ComposioHQ/agent-orchestrator.git
    cd agent-orchestrator
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    pnpm install
    ```
  </Step>

  <Step title="Build all packages">
    ```bash theme={null}
    pnpm build
    ```

    <Info>
      Building is required before running the dev server.
    </Info>
  </Step>

  <Step title="Copy example config">
    ```bash theme={null}
    cp agent-orchestrator.yaml.example agent-orchestrator.yaml
    ```
  </Step>

  <Step title="Configure your settings">
    ```bash theme={null}
    $EDITOR agent-orchestrator.yaml
    ```
  </Step>
</Steps>

### Running the Dev Server

<Warning>
  The web dashboard depends on built packages. Always build before running the dev server.
</Warning>

```bash theme={null}
# Build all packages
pnpm build

# Start dev server
cd packages/web
pnpm dev

# Open http://localhost:3000 (or your configured port)
```

## Project Structure

```
agent-orchestrator/
├── packages/
│   ├── core/              # Core types, services, config
│   ├── cli/               # CLI tool (ao command)
│   ├── web/               # Next.js dashboard
│   ├── plugins/           # All plugins
│   │   ├── runtime-*/     # Runtime plugins (tmux, docker, k8s)
│   │   ├── agent-*/       # Agent adapters (claude-code, codex, aider)
│   │   ├── workspace-*/   # Workspace providers (worktree, clone)
│   │   ├── tracker-*/     # Issue trackers (github, linear)
│   │   ├── scm-github/    # SCM adapter
│   │   ├── notifier-*/    # Notification channels
│   │   └── terminal-*/    # Terminal UIs
│   └── integration-tests/ # Integration tests
├── agent-orchestrator.yaml.example
├── .gitleaks.toml         # Secret scanning config
├── .husky/                # Git hooks
└── docs/                  # Documentation
```

## Development Workflow

### Making Changes

<Steps>
  <Step title="Create a feature branch">
    ```bash theme={null}
    git checkout -b feat/your-feature
    ```
  </Step>

  <Step title="Make your changes">
    * Follow [CLAUDE.md](https://github.com/ComposioHQ/agent-orchestrator/blob/main/CLAUDE.md) conventions
    * Add tests for new features
    * Update documentation
  </Step>

  <Step title="Build and test">
    ```bash theme={null}
    pnpm build
    pnpm test
    pnpm lint
    pnpm typecheck
    ```
  </Step>

  <Step title="Commit">
    ```bash theme={null}
    git add .
    git commit -m "feat: add your feature"
    ```

    <Note>
      * Pre-commit hook will scan for secrets
      * Use [Conventional Commits](https://www.conventionalcommits.org/)
    </Note>
  </Step>

  <Step title="Push and open PR">
    ```bash theme={null}
    git push origin feat/your-feature
    ```
  </Step>
</Steps>

## Code Conventions

### TypeScript

* **ESM modules** - `.js` extensions in imports
* **`node:` prefix** for builtins (`node:fs`, `node:path`)
* **Strict mode** enabled
* **`type` imports** for type-only imports
* **No `any`** - use `unknown` + type guards
* **Semicolons, double quotes, 2-space indent** - enforced by Prettier

```typescript theme={null}
// Good
import type { Runtime } from "@composio/ao-core";
import { readFileSync } from "node:fs";
import { foo } from "./bar.js";

// Bad
import { Runtime } from "@composio/ao-core"; // Should be type import
import { readFileSync } from "fs"; // Missing node: prefix
import { foo } from "./bar"; // Missing .js extension
```

### Shell Commands

<Warning>
  **Security critical**: Always follow these rules to prevent shell injection vulnerabilities.
</Warning>

* **Always use `execFile`** (or `spawn`) - NEVER `exec`
* **Always add timeouts** - `{ timeout: 30_000 }`
* **Never interpolate user input** - pass as array args
* **Do NOT use `JSON.stringify` for shell escaping**

```typescript theme={null}
// GOOD
import { execFile } from "node:child_process";
import { promisify } from "node:util";
const execFileAsync = promisify(execFile);
const { stdout } = await execFileAsync("git", ["branch", "--show-current"], { 
  timeout: 30_000 
});

// BAD - shell injection risk
exec(`git checkout ${branchName}`); // branchName could contain ; rm -rf /
```

## Plugin Development

Every plugin implements one of the core interfaces defined in `packages/core/src/types.ts`.

### Plugin Pattern

```typescript theme={null}
import type { PluginModule, Runtime } from "@composio/ao-core";

export const manifest = {
  name: "my-plugin",
  slot: "runtime" as const,
  description: "My plugin",
  version: "0.1.0",
};

export function create(): Runtime {
  return {
    name: "my-plugin",
    async create(config) {
      /* ... */
    },
    // ... implement interface
  };
}

export default { manifest, create } satisfies PluginModule<Runtime>;
```

### Adding a New Plugin

<Steps>
  <Step title="Create plugin package">
    ```bash theme={null}
    mkdir -p packages/plugins/runtime-myplugin
    cd packages/plugins/runtime-myplugin
    ```
  </Step>

  <Step title="Set up package.json">
    ```json theme={null}
    {
      "name": "@composio/ao-runtime-myplugin",
      "version": "0.1.0",
      "type": "module",
      "main": "dist/index.js",
      "types": "dist/index.d.ts",
      "scripts": {
        "build": "tsc",
        "typecheck": "tsc --noEmit",
        "test": "vitest"
      },
      "dependencies": {
        "@composio/ao-core": "workspace:*"
      }
    }
    ```
  </Step>

  <Step title="Create src/index.ts">
    Implement the appropriate interface (Runtime, Agent, Workspace, Tracker, etc.).
  </Step>

  <Step title="Register in core">
    Add to `packages/core/src/services/plugin-registry.ts`.
  </Step>

  <Step title="Add tests">
    Create `src/index.test.ts` with test cases.
  </Step>

  <Step title="Build and test">
    ```bash theme={null}
    pnpm --filter @composio/ao-runtime-myplugin build
    pnpm --filter @composio/ao-runtime-myplugin test
    ```
  </Step>
</Steps>

### Plugin Slots

Eight slots available for plugins:

| Slot | Interface | Default | Examples |
| - | - | - | - |
| Runtime | `Runtime` | tmux | docker, k8s, process |
| Agent | `Agent` | claude-code | codex, aider, opencode |
| Workspace | `Workspace` | worktree | clone |
| Tracker | `Tracker` | github | linear |
| SCM | `SCM` | github | — |
| Notifier | `Notifier` | desktop | slack, composio, webhook |
| Terminal | `Terminal` | iterm2 | web |
| Lifecycle | (core) | core | — |

<Info>
  All interfaces are defined in `packages/core/src/types.ts` - read this file first!
</Info>

## Testing

```bash theme={null}
# Run all tests
pnpm test

# Run tests for specific package
pnpm --filter @composio/ao-core test

# Run tests in watch mode
pnpm --filter @composio/ao-core test -- --watch

# Run integration tests
pnpm test:integration
```

### Test Coverage

The project has **3,288 test cases** ensuring reliability and correctness.

## Security

### Secret Scanning

A **pre-commit hook** automatically scans for secrets:

```bash theme={null}
🔒 Scanning staged files for secrets...
✅ No secrets detected
```

<Warning>
  If secrets are detected:

  1. Remove the secret from the file
  2. Use environment variables: `${SECRET_NAME}`
  3. Add to `.env.local` (in `.gitignore`)
  4. Update example configs with placeholders
</Warning>

### What Triggers the Scanner

* API keys: `lin_api_*`, `ghp_*`, `gho_*`, `sk-*`, `AKIA*`
* Tokens: `xoxb-*`, `xoxa-*`, etc.
* Webhooks: `https://hooks.slack.com/*`, `https://discord.com/api/webhooks/*`
* Private keys: `-----BEGIN PRIVATE KEY-----`
* Database URLs: `postgres://user:pass@host`
* Generic patterns: `api_key=...`, `token=...`, `password=...`

### False Positives

If you get a false positive:

<Steps>
  <Step title="Verify it's not a real secret">
    Double-check the detected pattern is actually safe.
  </Step>

  <Step title="Update allowlist">
    Edit `.gitleaks.toml`:

    ```toml theme={null}
    [allowlist]
    regexes = [
      '''your-pattern-here''',
    ]
    ```
  </Step>

  <Step title="Commit the change">
    ```bash theme={null}
    git add .gitleaks.toml
    git commit -m "chore: update gitleaks allowlist"
    ```
  </Step>
</Steps>

## Working with Worktrees

If using git worktrees for parallel development:

```bash theme={null}
# Create worktree
git worktree add ../ao-feature-x feat/feature-x
cd ../ao-feature-x

# Install and build
pnpm install
pnpm build

# Copy config
cp ../agent-orchestrator/agent-orchestrator.yaml .

# Start dev server
cd packages/web
pnpm dev
```

## Debugging

### Enable Verbose Logging

```bash theme={null}
DEBUG=* pnpm dev
```

### Attach to tmux Session

```bash theme={null}
tmux attach -t session-name
# Detach: Ctrl-b d
```

### Inspect Session Metadata

```bash theme={null}
cat ~/.agent-orchestrator/my-app-3
```

### Check Session Status

```bash theme={null}
curl http://localhost:3000/api/sessions/my-app-3
```

## Submission Guidelines

### Pull Request Process

<Steps>
  <Step title="Ensure all tests pass">
    ```bash theme={null}
    pnpm build && pnpm test && pnpm lint && pnpm typecheck
    ```
  </Step>

  <Step title="Write a clear description">
    * What does this PR do?
    * Why is it needed?
    * How does it work?
    * Any breaking changes?
  </Step>

  <Step title="Link related issues">
    Use `Fixes #123` or `Closes #123` in the PR description.
  </Step>

  <Step title="Request review">
    Tag relevant maintainers or wait for automatic review assignment.
  </Step>
</Steps>

### Commit Message Format

Use [Conventional Commits](https://www.conventionalcommits.org/):

```
feat: add support for Docker runtime
fix: resolve memory leak in session cleanup
chore: update dependencies
docs: improve plugin development guide
test: add integration tests for Linear tracker
```

### Code Review

Expect feedback on:

* Code quality and style
* Test coverage
* Documentation updates
* Security considerations
* Performance implications

## Resources

* [CLAUDE.md](https://github.com/ComposioHQ/agent-orchestrator/blob/main/CLAUDE.md) — Code conventions and architecture
* [SECURITY.md](https://github.com/ComposioHQ/agent-orchestrator/blob/main/SECURITY.md) — Security best practices
* [packages/core/README.md](https://github.com/ComposioHQ/agent-orchestrator/tree/main/packages/core) — Core architecture
* [agent-orchestrator.yaml.example](https://github.com/ComposioHQ/agent-orchestrator/blob/main/agent-orchestrator.yaml.example) — Config reference

## Getting Help

Need help contributing?

1. Check existing issues and discussions
2. Review the [troubleshooting guide](/resources/troubleshooting)
3. Ask questions in GitHub Discussions
4. Join the community channels

Thank you for contributing to Agent Orchestrator!


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