CLI Redesign: Simplified Onboarding

1. Overview

The CLI redesign eliminates multi-step onboarding by collapsing ao init, ao add-project, and ao start into a single command. The target experience:

npm install -g @composio/ao && ao start

Everything else — config generation, project detection, agent runtime discovery, and environment validation — happens automatically. When AO is already running, the CLI detects it and offers contextual options instead of crashing.

2. Before vs After

ao init
# manually edit agent-orchestrator.yaml
ao add-project my-app ~/code/my-app
ao start

ao start
# config auto-generated, agent auto-detected
# dashboard opens at http://localhost:3000

3. Architecture Changes

File Map

• packages/cli/src/lib/running-state.ts
• packages/cli/src/lib/caller-context.ts
• packages/cli/src/lib/detect-agent.ts
• packages/cli/src/lib/detect-env.ts
• packages/cli/src/lib/config-instruction.ts
• packages/cli/src/commands/start.ts
• packages/cli/src/commands/spawn.ts
• packages/cli/src/commands/init.ts (rewritten as deprecation wrapper)
• packages/cli/src/commands/add-project.ts
• packages/core/src/orchestrator-prompt.ts
• packages/core/src/session-manager.ts (env var injection)
• packages/plugin-agent-claude-code (detect + displayName)
• packages/plugin-agent-aider (detect + displayName)
• packages/plugin-agent-codex (detect + displayName)
• packages/plugin-agent-opencode (detect + displayName)

The core architecture (dist-server, session manager, workspace plugins) remains unchanged. Changes are concentrated in the CLI entry layer and the thin coordination between CLI and core.

4. New Library Files

running-state.ts — Single-Instance Tracking

Tracks whether an AO instance is already running. Writes a ~/.agent-orchestrator/running.json file containing the running state:

interface RunningState {
  pid: number;
  configPath: string;
  port: number;
  startedAt: string;
  projects: string[];
}

• Uses an advisory lockfile (running.lock) with O_CREAT | O_EXCL for atomic creation — prevents concurrent registration races.
• Auto-prunes stale entries: if the recorded PID is dead (process.kill(pid, 0) fails), the entry is cleared on read.
• Lock timeout of 5 seconds with force-remove handles crashed processes that left a stale lock.
• Exports: register(), unregister(), getRunning(), isAlreadyRunning(), waitForExit(pid, timeoutMs).

caller-context.ts — Human/Orchestrator/Agent Detection

Detects who is invoking the CLI and provides typed helpers for propagating context.

type CallerType = "human" | "orchestrator" | "agent";

• getCallerType(): If AO_CALLER_TYPE env var is set, trusts it directly. Otherwise: TTY = human, non-TTY = agent.
• isHumanCaller(): Convenience boolean check.
• setCallerContext(env, opts): Injects AO_CALLER_TYPE, AO_SESSION_ID, AO_PROJECT_ID, AO_CONFIG_PATH, and AO_PORT into a spawn environment record.

detect-agent.ts — Plugin-Based Runtime Discovery

No hardcoded binary paths. Dynamically imports each agent plugin and calls its detect() method.

Known plugins:

Selection logic in detectAgentRuntime():

• 0 agents detected → default to claude-code.
• 1 agent → auto-select.
• Multiple + human caller → interactive picker via node:readline/promises.
• Multiple + non-human → prefer claude-code, else first available.

detect-env.ts — Environment Detection

Probes the local environment to auto-populate config fields. Returns an EnvironmentInfo object:

• Git: repo detection, remote URL parsing, owner/repo extraction, current branch, default branch (via detectDefaultBranch()).
• Tools: tmux availability, gh CLI availability, gh auth status.
• API keys: LINEAR_API_KEY, SLACK_WEBHOOK_URL presence.

config-instruction.ts — Config Schema Reference

Returns a comprehensive annotated YAML schema covering every config field: ports, defaults (runtime, agent, workspace, notifiers), project settings (repo, path, branch, agentConfig, agentRules, workspace symlinks/postCreate, tracker, SCM), notification channels, and notification routing. Used by ao config-help.

5. Command Changes

ao start changed

Now the single entry point for all of AO. On first run:

1. Calls detectEnvironment(cwd) to probe git, tools, and APIs.
2. Calls detectAgentRuntime() to find an installed agent.
3. Generates agent-orchestrator.yaml with all detected values.
4. Calls register() to write running state to ~/.agent-orchestrator/running.json.
5. Starts the dist-server and orchestrator session.

If already running, delegates to the Already-Running Detection flow (Section 8).

Also exports createConfigOnly() for the deprecated ao init wrapper.

ao spawn changed

Simplified from ao spawn <project> <issue> to ao spawn [issue]. The project is always auto-detected — no project argument is accepted. See Section 9 for the auto-detection logic.

If a user passes two args (old syntax), a friendly warning is shown:

⚠ 'ao spawn <project> <issue>' is no longer supported.
  The project is now auto-detected. Use:

    ao spawn INT-100    # spawn with issue INT-100
    ao spawn            # spawn without an issue

The autoDetectProject() function resolves the project from: single project in config, AO_PROJECT_ID env var, or cwd matching a project path.

ao batch-spawn changed

Same simplification: takes only issue IDs as arguments. The project is always auto-detected — no project prefix is accepted.

ao init deprecated

Reduced to a thin wrapper that prints a deprecation warning then delegates to createConfigOnly() from start.ts:

// init.ts — full implementation
program.command("init")
  .description("[deprecated] Use 'ao start' instead")
  .action(async () => {
    console.log("'ao init' is deprecated. Use 'ao start' instead.");
    const { createConfigOnly } = await import("./start.js");
    await createConfigOnly();
  });

ao add-project removed

Fully deleted. Projects are auto-detected from cwd or added manually to the YAML config file.

ao config-help new

Prints the annotated config schema from config-instruction.ts to stdout. Provides both humans and orchestrator agents a quick reference without needing external docs.

6. Plugin System Enhancements

All four agent plugins gained two new exports to support runtime discovery:

These are consumed by detect-agent.ts via dynamic import(). Plugins that fail to import (not installed) are silently skipped — this is by design, as missing plugins are the normal case.

7. Session Environment Variables

Every spawned session (orchestrator and worker) receives these environment variables, set in session-manager.ts (core package) at the single spawn point:

The setCallerContext() helper in caller-context.ts provides a typed interface for populating these variables. All three spawn paths (orchestrator session, ao spawn, ao batch-spawn) go through the session manager, ensuring consistency.

8. Already-Running Detection

When ao start is invoked and isAlreadyRunning() returns a live state, behavior branches on caller type:

Human callers get an interactive menu with four options: open the existing dashboard, start a new instance (killing the old), override with a new config, or quit.

Agent/orchestrator callers receive a structured info dump (port, PID, projects list) and a clean exit code 0, so they can connect to the already-running instance.

9. Spawn Auto-Detection Logic

The ao spawn argument parser uses this decision tree:

autoDetectProject() Resolution Order

1. If only one project in config → use it.
2. If AO_PROJECT_ID env var is set and matches a configured project → use it.
3. If process.cwd() matches a project's path field → use it.
4. Otherwise → throw error listing available projects.

This means an orchestrator agent calling ao spawn INT-1234 from within a session always resolves correctly via the injected AO_PROJECT_ID env var.

10. Testing Scenarios

11. Design Decisions

12. Review Findings & Fixes