Reducing AO Onboarding Friction — CLI, npm & UX

This document covers everything needed to reduce onboarding friction for Agent Orchestrator — from npm install to first agent spawn. It includes CLI consolidation, npm publishing, error handling, auto-detection, and UX design.

0. The Onboarding Journey — End to End

Every improvement in this doc serves one flow:

1. Current CLI Structure (16 Commands)

All commands are registered in packages/cli/src/index.ts via individual register*(program) calls using Commander.js.

2. Current File Map & Line Counts

Command Files

Shared Library Files

3. Overlap Analysis: init vs add-project vs start

These three commands share significant logic. The table below shows which capabilities exist in each:

4. Commands to ABSORB into ao start

4.1   ao init → absorbed into ao start

4.2   ao add-project <path> → absorbed into ao start <path>

4.3   ao start <url> — already exists, no change

5. New Functionality to ADD

5.1   running.json State File

New file lib/running-state.ts — ~80 lines

// ~/.agent-orchestrator/running.json
[
  {
    "pid": 12345,
    "projectId": "my-app",
    "configPath": "/Users/me/my-app/agent-orchestrator.yaml",
    "port": 3000,
    "startedAt": "2026-03-15T10:30:00Z",
    // No identifier field needed — one instance per machine
  }
]

5.2   Already-Running Detection in ao start

See §8 Already-Running Behavior — Deep Dive for full details, interactive menus, running.json mechanics, and edge cases.

5.3   ao stop Improvements

Edit commands/start.ts — ~30 changed lines

5.4   ao --get-config-generation-instruction

New file lib/config-instruction.ts — ~60 lines

5.5   CLI Context-Awareness via Environment Variables

New file lib/caller-context.ts — ~40 lines

export function getCallerType(): "human" | "orchestrator" | "agent"
export function isHumanCaller(): boolean
export function setCallerContext(env: Record<string, string>, opts: CallerContextOpts): void

6. Commands that STAY Unchanged (10 Commands)

7. Deprecation Strategy

Implementation: Thin Wrappers (~15 lines each)

// commands/init.ts (after rewrite)
export function registerInit(program: Command): void {
  program
    .command("init")
    .description("[deprecated] Use 'ao start' instead")
    .action(async (opts) => {
      console.log(chalk.yellow("⚠ 'ao init' is deprecated. Use 'ao start' instead."));
      // Delegate to start's config-creation logic
      await createConfigOnly({ interactive: opts.interactive, output: opts.output });
    });
}

8. Already-Running Behavior — Deep Dive

When a user runs ao start for a project that is already running, the CLI must handle it gracefully instead of blindly starting a second instance.

8.1   How detection works

// Pseudocode inside ao start, before any startup logic
const existing = findRunningEntry({
  configPath: resolvedConfigPath,
  projectId:  resolvedProjectId,
});

if (existing) {
  // Verify PID is actually alive (kill(pid, 0))
  if (isProcessAlive(existing.pid)) {
    printAlreadyRunning(existing);
    process.exit(0);
  } else {
    // Stale entry — clean it up and proceed
    unregister(existing.pid);
  }
}

8.2   Default behavior: interactive prompt (human) or inform-and-exit (agent)

If AO is already running for the same project, behavior depends on who is calling:

$ ao start

ℹ AO is already running for this project.

  Project:    my-app
  URL:        http://localhost:3000
  PID:        12345
  Started:    2h 15m ago

? What would you like to do?
  ❯ Continue with the current one (open dashboard)
    Start a new orchestrator on the same project
    Override current config and restart
    Quit

$ ao start

ℹ AO is already running for this project.

  Project:    my-app
  URL:        http://localhost:3000
  PID:        12345
  Started:    2h 15m ago
  Config:     /Users/me/my-app/agent-orchestrator.yaml

  To restart: stop with 'ao stop', then 'ao start' again.

8.3   Restart — handled interactively

$ ao start

⚠ Stopping existing instance (PID 12345, port 3000)...
✓ Stopped.

  Starting fresh...
  Dashboard:    http://localhost:3000
  Orchestrator: running

8.4   Multiple orchestrators on the same project — same instance

When user picks "Start a new orchestrator on the same project":

1. CLI auto-generates a unique name (e.g. my-app-x7k2)
2. Duplicates the project entry in the config with the new session prefix
3. Spawns a new orchestrator session under the existing AO instance
4. Dashboard sidebar shows both: my-app and my-app-x7k2
5. Same port, same dashboard, same everything

$ ao start ~/my-app

ℹ An orchestrator is already running on this project.
  Dashboard: http://localhost:3000
  Sessions:  3 active | Up: 2h

? What would you like to do?
  > Start a new orchestrator on the same project

✓ New orchestrator started on my-app
  ID: my-app-x7k2
  Dashboard: http://localhost:3000 (same dashboard)

  2 orchestrators now running on my-app:
    1. my-app      — 3 sessions
    2. my-app-x7k2 — 0 sessions (new)

If a user runs ao start ~/other-repo (a different project) while AO is already running:

1. The new project is added to the existing config
2. The dashboard sidebar shows both projects
3. Same port, same instance, same dashboard

8.5   Config file resolution (auto-detected, no flag needed)

8.6   running.json state

{
  "pid": 12345,
  "configPath": "/Users/me/my-app/agent-orchestrator.yaml",
  "port": 3000,
  "startedAt": "2026-03-15T10:30:00Z",
  "projects": ["my-app", "my-app-x7k2", "backend"]
}

8.7   Complete scenario matrix

8.8   Edge cases

9. New ao start Decision Tree

After absorbing init and add-project, ao start handles every entry scenario:

10. File Changes Summary

Net Impact

11. Before / After Comparison

First-time user journey

$ cd ~/my-project
$ ao init          # step 1: create config
$ ao start         # step 2: start orchestrator

# Later, adding another project:
$ ao add-project ~/other-repo   # step 3
$ ao start other-repo           # step 4

$ cd ~/my-project
$ ao start         # auto-creates config + starts

# Later, adding another project:
$ ao start ~/other-repo   # auto-adds + starts

Already-running scenario

$ ao start
# Starts a SECOND dashboard — two processes competing, confusion

$ ao start
# Already running on port 3000 (PID 12345)
# Started 2h ago. Dashboard: http://localhost:3000
# Select "Restart" from the menu to restart.
# Or: ao stop && ao start

Stopping with awareness

$ ao stop
# Stopped. (silence — no idea if other
# orchestrators are still running)

$ ao stop
# ✓ Stopped AO on port 3000
#   Projects managed: my-app, backend
#   Uptime: 4h 12m
#
# Dashboard and all sessions terminated.

Full new ao start flag inventory

Full new ao stop flag inventory

12. Smart Agent Runtime Detection

12.1   Why not hardcode?

12.2   The plugin registry approach

PR #474 introduces packages/core/src/plugin-registry.ts — a proper plugin registry that discovers plugins dynamically. We build on this, not duplicate it.

How plugins are discovered (3 sources):

1. Built-in — packages/plugins/agent-* (shipped with AO)
2. npm packages — any package named @composio/ao-plugin-agent-*
3. Local paths — specified in config (for custom/private plugins)

12.3   Plugin interface: each agent declares its own detection

Every agent plugin exports a detect() method. The CLI never needs to know how to detect each runtime — the plugin handles it.

// Plugin interface (in @composio/ao-core types)
interface AgentPluginManifest {
  name: string;           // e.g. "claude-code"
  displayName: string;    // e.g. "Claude Code"
  priority: number;       // Higher = preferred. e.g. 100 for claude, 90 for codex
  detect(): boolean;      // Can this runtime be found on the system?
}

// Example: claude-code plugin exports
export default {
  name: "claude-code",
  displayName: "Claude Code",
  priority: 100,
  detect() {
    try { execSync("which claude", { stdio: "ignore" }); return true; }
    catch { return false; }
  },
  create() { /* ... existing plugin factory ... */ }
};

12.4   Detection flow in ao start

// In ao start, when auto-creating config:
async function detectAgentRuntime(registry: PluginRegistry): Promise<string> {
  // 1. Get ALL registered agent plugins from the registry
  const agentPlugins = registry.getAll("agent");

  // 2. Filter to those that are detected on this system
  const available = agentPlugins.filter(p => p.detect());

  // 3. Selection logic
  if (available.length === 0) {
    console.warn("No agent runtimes detected. Using claude-code as default.");
    return "claude-code";
  }

  if (available.length === 1) {
    return available[0].name;
  }

  // Multiple available
  if (isHumanCaller()) {
    // Prompt: "Multiple runtimes detected. Which one?"
    return await promptChoice(
      available.sort((a, b) => b.priority - a.priority)
               .map(p => ({ name: p.displayName, value: p.name }))
    );
  }

  // Agent caller: pick highest priority
  const selected = available.sort((a, b) => b.priority - a.priority)[0];
  console.log(`Auto-selected: ${selected.displayName} (highest priority)`);
  return selected.name;
}

12.5   What this enables

13. System Prompt Auto-Injection

13.1   Dual-use architecture

13.2   Implementation details

• Source: lib/config-instruction.ts exports getConfigInstruction(): string
• CLI registration: Both ao config-help (subcommand) and ao --get-config-generation-instruction (flag) call the same function
• Injection point: ao-core/src/orchestrator.ts → generateOrchestratorPrompt() imports and appends the instruction text to the system prompt
• Caching: Generated once at orchestrator startup. If config changes mid-run, orchestrator restart picks up the new version.
• Content: Complete YAML schema, valid enum values, default values, and an annotated example config

14. Interactive-First UX Design Principles

14.1   Core principle: Guide, don't require flags

For human callers (TTY detected), the CLI should always guide through interactive prompts rather than requiring flag knowledge. Flags exist as shortcuts for power users and as the API surface for agents.

14.2   Output format per caller type

• Human: Colored output, banners, interactive prompts, browser auto-open
• Orchestrator: Minimal color, structured output, no prompts, no browser
• Agent session: JSON-friendly output, no color, no prompts, no browser

14.3   The "dumbest agent" test

Every CLI command should pass this test: Can an agent with zero prior knowledge of AO figure out what to do next from the CLI output alone?

• Error messages must include the exact command to fix the problem
• Success messages must include next steps
• Help text must be exhaustive but scannable
• System prompts (via auto-injection) must explain the full CLI surface

15. npm Publishing & Distribution

15.1   Current state (from PR #463)

PR #463 already fixes the major npm publishing blockers:

15.2   The install experience target

git clone ...
cd agent-orchestrator
pnpm install
pnpm build
npm link
ao init          # 13 prompts
ao start         # port crash
# manually edit YAML...

npm install -g @composio/ao
ao start ~/my-project   # or ao start https://github.com/org/repo

15.3   How this connects to CLI redesign

The CLI consolidation (absorbing init and add-project into start) is what makes the 3-step npm experience possible:

• No ao init step — ao start auto-creates config on first run
• No ao add-project step — ao start ~/other-repo auto-adds to config
• No port conflicts — auto-finds free port if configured one is busy
• No "what's next?" confusion — every command prints contextual next steps

15.4   Package structure

15.5   Remaining considerations

• Package rename: Publish as @composio/ao instead of @composio/agent-orchestrator. The unscoped ao is taken on npm, but @composio/ao is available. Keep @composio/agent-orchestrator as a deprecated redirect package.
• Version sync: All packages should publish together with matching versions to avoid compatibility issues
• Pre-built dashboard: ao-web should ship pre-built (next build output) so npm users don't need to build
• Binary size budget: Monitor total install size — target under 5 MB for the full npm install -g
• Offline-friendly: After install, ao start should not need to download anything else
• Update path: ao update should handle both npm (npm update -g) and source (git pull && pnpm build) installs

16. Simplifying ao spawn

16.1   Current vs new

ao spawn my-app #42
ao spawn my-app INT-1234

ao spawn #42
ao spawn INT-1234

16.2   How auto-detection works

Simple — no fancy heuristics needed:

1. AO_PROJECT_ID env var is set → use it. This covers 99% of cases because ao start sets this variable and every child process (orchestrator, agent sessions) inherits it.
2. Not set, but config has only one project → use it. No ambiguity.
3. Not set, multiple projects → error: “Multiple projects in config. Run from an orchestrator session, or specify: ao spawn <project> <issue>”

16.3   Command signature change

// CURRENT in spawn.ts
.argument("<project>", "Project ID from config")
.argument("[issue]", "Issue identifier")

// NEW — project becomes optional
.argument("<issue>", "Issue identifier (e.g. #42, INT-1234)")
.argument("[project]", "Project ID — auto-detected if omitted")

16.4   Implementation

// In registerSpawn action handler:
function resolveProjectForSpawn(
  config: OrchestratorConfig,
  arg1: string,
  arg2?: string
): { projectId: string; issueId: string } {

  // Two args: explicit project + issue (backward compat)
  if (arg2) {
    return { projectId: arg1, issueId: arg2 };
  }

  // One arg: auto-detect project, arg1 is the issue
  const issueId = arg1;

  // 1. Check AO_PROJECT_ID env var
  if (process.env.AO_PROJECT_ID) {
    return { projectId: process.env.AO_PROJECT_ID, issueId };
  }

  // 2. Single project in config
  const projectIds = Object.keys(config.projects);
  if (projectIds.length === 1) {
    return { projectId: projectIds[0], issueId };
  }

  // 3. Ambiguous — error
  throw new Error(
    `Multiple projects in config: ${projectIds.join(", ")}
` +
    `Run from an orchestrator session, or specify:
` +
    `  ao spawn <project> <issue>`
  );
}

17. Open Questions for Review

Items that need owner input before implementation: