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)

Breaking Change: This release requires manual migration for existing users.

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

What Changed

Before:

# agent-orchestrator.yaml
dataDir: ~/.ao-sessions
worktreeDir: ~/.ao-worktrees

After:

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

// Config at: ~/projects/acme/agent-orchestrator.yaml
// Hash of:   /Users/you/projects/acme
// Result:    a3b4c5d6e7f8

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

Why 12 chars? Balance between uniqueness (collision probability ~1 in 16 billion) and path length.

Migration Required

Migration Steps

1. Clean up config file

   Remove dataDir and worktreeDir from your config:

   vim ~/path/to/agent-orchestrator.yaml
   

   Remove these lines:

   dataDir: ~/.ao-sessions
   worktreeDir: ~/.ao-worktrees
   
2. Kill existing sessions

   # 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
   
3. Clean up old directories

   # 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
   
4. Update to latest version

   git pull origin main
   pnpm install
   pnpm build
   
5. Start fresh

   # Start orchestrator (creates new directory structure)
   ao start
   
   # Spawn new sessions (uses hash-based paths)
   ao spawn my-app INT-1234
   
6. Verify new structure

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

Breaking Changes

Config File Changes

REMOVED fields (will cause validation errors if present):

• dataDir
• worktreeDir

REQUIRED field:

• configPath (automatically set by loadConfig())

API Changes (Plugin Developers)

Removed from OrchestratorConfig:

interface OrchestratorConfig {
  dataDir: string; // REMOVED
  worktreeDir: string; // REMOVED
  configPath: string; // NOW REQUIRED
}

New Path Utilities:

import {
  getSessionsDir,
  getWorktreesDir,
  getProjectBaseDir,
  generateConfigHash,
  generateInstanceId,
  validateAndStoreOrigin,
} from "@composio/ao-core";

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

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.

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:

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

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:

cd node_modules/.pnpm/node-pty@1.1.0/node_modules/node-pty
npx node-gyp rebuild

See Troubleshooting for details.

Multiple Orchestrators

When running multiple orchestrator instances, ensure each has:

• Different port value in config
• Different config file location (for unique hash)

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
2. Review Contributing Guidelines
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 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
• Review docs: Documentation
• Join discussions: GitHub Discussions