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

# Changelog

> Recent changes, releases, version history, and breaking changes for Agent Orchestrator

This page tracks the evolution of Agent Orchestrator, including new features, improvements, and breaking changes.

## Recent Changes

### Hash-Based Architecture Migration (2026-02-17)

<Warning>
  **Breaking Change**: This release requires manual migration for existing users.
</Warning>

Agent Orchestrator migrated from flat, configurable directories to a **hash-based project isolation** architecture.

#### What Changed

**Before**:

```yaml theme={null}
# agent-orchestrator.yaml
dataDir: ~/.ao-sessions
worktreeDir: ~/.ao-worktrees
```

**After**:

```yaml theme={null}
# agent-orchestrator.yaml
# No dataDir or worktreeDir needed!
projects:
  my-app:
    path: ~/repos/my-app
```

#### Benefits

* **Zero configuration** - Paths auto-derived from config location
* **Complete isolation** - Each config gets unique namespace
* **Collision-free** - SHA256 hash prevents conflicts
* **Clean codebase** - No backwards compatibility code

#### New Directory Structure

All orchestrator data now lives under `~/.agent-orchestrator/`:

```
~/.agent-orchestrator/
├── {hash}-{projectId}/        # Unique per config+project
│   ├── .origin                # Stores config path (collision detection)
│   ├── sessions/              # Session metadata
│   └── worktrees/             # Git worktrees
```

#### Hash Generation

The hash is the first 12 characters of `SHA256(realpath(dirname(configPath)))`:

```typescript theme={null}
// Config at: ~/projects/acme/agent-orchestrator.yaml
// Hash of:   /Users/you/projects/acme
// Result:    a3b4c5d6e7f8

// Final path: ~/.agent-orchestrator/a3b4c5d6e7f8-my-app/
```

<Info>
  **Why 12 chars?** Balance between uniqueness (collision probability \~1 in 16 billion) and path length.
</Info>

#### Migration Required

<Accordion title="Migration Steps">
  <Steps>
    <Step title="Clean up config file">
      Remove `dataDir` and `worktreeDir` from your config:

      ```bash theme={null}
      vim ~/path/to/agent-orchestrator.yaml
      ```

      Remove these lines:

      ```yaml theme={null}
      dataDir: ~/.ao-sessions
      worktreeDir: ~/.ao-worktrees
      ```
    </Step>

    <Step title="Kill existing sessions">
      ```bash theme={null}
      # List all tmux sessions
      tmux ls

      # Kill all orchestrator sessions
      tmux ls | grep -E '^(int|ao|app)-[0-9]+:' | cut -d: -f1 | xargs -I{} tmux kill-session -t {}

      # Or kill all tmux sessions (nuclear option)
      tmux kill-server
      ```
    </Step>

    <Step title="Clean up old directories">
      ```bash theme={null}
      # For each project, remove old worktrees
      cd ~/repos/integrator
      git worktree list
      git worktree remove ~/.ao-worktrees/integrator/int-1 --force
      git worktree prune

      # Archive old metadata (optional)
      mv ~/.ao-sessions ~/.ao-sessions-backup-$(date +%Y%m%d)

      # Remove old worktree directory
      rm -rf ~/.ao-worktrees
      ```
    </Step>

    <Step title="Update to latest version">
      ```bash theme={null}
      git pull origin main
      pnpm install
      pnpm build
      ```
    </Step>

    <Step title="Start fresh">
      ```bash theme={null}
      # Start orchestrator (creates new directory structure)
      ao start

      # Spawn new sessions (uses hash-based paths)
      ao spawn my-app INT-1234
      ```
    </Step>

    <Step title="Verify new structure">
      ```bash theme={null}
      # Check that new directories were created
      ls -la ~/.agent-orchestrator/

      # Check tmux sessions have hash prefix
      tmux ls
      # Should show: a3b4c5d6e7f8-int-1, a3b4c5d6e7f8-int-2, etc.
      ```
    </Step>
  </Steps>
</Accordion>

#### Breaking Changes

<Accordion title="Config File Changes">
  **REMOVED fields** (will cause validation errors if present):

  * `dataDir`
  * `worktreeDir`

  **REQUIRED field**:

  * `configPath` (automatically set by `loadConfig()`)
</Accordion>

<Accordion title="API Changes (Plugin Developers)">
  **Removed from `OrchestratorConfig`**:

  ```typescript theme={null}
  interface OrchestratorConfig {
    dataDir: string; // REMOVED
    worktreeDir: string; // REMOVED
    configPath: string; // NOW REQUIRED
  }
  ```

  **New Path Utilities**:

  ```typescript theme={null}
  import {
    getSessionsDir,
    getWorktreesDir,
    getProjectBaseDir,
    generateConfigHash,
    generateInstanceId,
    validateAndStoreOrigin,
  } from "@composio/ao-core";

  // Calculate paths dynamically
  const sessionsDir = getSessionsDir(configPath, projectPath);
  const worktreesDir = getWorktreesDir(configPath, projectPath);
  ```
</Accordion>

<Accordion title="FAQ">
  **Q: Why can't I use my old sessions?**

  A: The metadata file structure changed. Old sessions point to flat directories but the new code expects hash-based paths. You must kill old sessions and spawn new ones.

  **Q: Will my PRs be lost?**

  A: No! PRs are on GitHub, not in local sessions. Check `gh pr list` to see all open PRs.

  **Q: What about in-progress work?**

  A: Commit or stash changes in each worktree before migration. After migration, spawn new sessions and continue work.

  **Q: Can I migrate metadata files manually?**

  A: Not recommended. The manual process is error-prone. Better to kill old sessions and spawn fresh ones.

  **Q: What if two configs have the same hash?**

  A: The `.origin` file detects collisions and throws an error with instructions. Collision probability is \~1 in 16 billion.
</Accordion>

#### Expected Downtime

* **Time**: \~10 minutes
* **Risk Level**: Low (PRs are safe, code is in git, only local sessions affected)
* **Benefit**: Cleaner architecture, zero config, collision-free multi-instance support

## Version History

### Current Release

* **Hash-based architecture** for improved isolation
* **Auto-detection** in `ao start <url>`
* **3,288 test cases** for reliability
* **Security scanning** with pre-commit hooks

### Core Features

#### Plugin System

Eight plugin slots make every abstraction swappable:

* **Runtime**: tmux, docker, k8s, process
* **Agent**: claude-code, codex, aider, opencode
* **Workspace**: worktree, clone
* **Tracker**: github, linear
* **SCM**: github
* **Notifier**: desktop, slack, composio, webhook
* **Terminal**: iterm2, web
* **Lifecycle**: core

#### Reactions System

Auto-handle routine events:

* **CI failures** - Automatically retry with failure logs
* **Review comments** - Send to agent for addressing
* **PR approval** - Optional auto-merge
* **Agent stuck** - Escalate to human

#### Dashboard

* Real-time session monitoring
* Web-based terminal access
* Session lifecycle management
* Status tracking and logs

#### CLI

Comprehensive command-line interface:

```bash theme={null}
ao status              # Overview of all sessions
ao spawn <project>     # Spawn an agent
ao send <session>      # Send instructions
ao session ls          # List sessions
ao session kill        # Kill a session
ao dashboard           # Open web dashboard
```

## Known Issues

### Current Limitations

<Accordion title="Terminal on Linux">
  The web terminal may have compatibility issues on some Linux distributions due to node-pty native dependencies.

  **Workaround**: Rebuild node-pty from source:

  ```bash theme={null}
  cd node_modules/.pnpm/node-pty@1.1.0/node_modules/node-pty
  npx node-gyp rebuild
  ```

  See [Troubleshooting](/resources/troubleshooting) for details.
</Accordion>

<Accordion title="Multiple Orchestrators">
  When running multiple orchestrator instances, ensure each has:

  * Different `port` value in config
  * Different config file location (for unique hash)
</Accordion>

## Planned Features

### Roadmap

* **GitLab integration** - Full support for GitLab SCM and trackers
* **Jira integration** - Issue tracking with Jira
* **Docker runtime improvements** - Better container isolation
* **Kubernetes runtime** - Production-ready k8s support
* **Email notifications** - Email notifier plugin
* **Metrics and analytics** - Session performance tracking
* **Custom dashboards** - Per-project dashboard customization

## Contributing

Want to contribute to the next release?

1. Check the [GitHub Issues](https://github.com/ComposioHQ/agent-orchestrator/issues)
2. Review [Contributing Guidelines](/resources/contributing)
3. Join discussions on planned features
4. Submit a PR with new features or fixes

## Release Notes Archive

For detailed commit history, see the [GitHub Releases](https://github.com/ComposioHQ/agent-orchestrator/releases) page.

## Staying Updated

To stay informed about new releases:

1. **Watch the repository** on GitHub
2. **Star the project** to show support
3. **Follow releases** for notifications
4. **Subscribe to announcements** (coming soon)

## Support

Questions about changes or migrations?

* Open an issue: [GitHub Issues](https://github.com/ComposioHQ/agent-orchestrator/issues)
* Review docs: [Documentation](/)
* Join discussions: [GitHub Discussions](https://github.com/ComposioHQ/agent-orchestrator/discussions)