Skip to main content
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

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

REMOVED fields (will cause validation errors if present):
  • dataDir
  • worktreeDir
REQUIRED field:
  • configPath (automatically set by loadConfig())
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);
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

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/[email protected]/node_modules/node-pty
npx node-gyp rebuild
See Troubleshooting for details.
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?

Build docs developers (and LLMs) love

Get started for freeTalk to us