Agent Orchestrator CLI

The official CLI tool for Agent Orchestrator - Monitor your Claude Code sessions in real-time.

Installation

npm install -g agents-orchestrator-cli

Or run locally:

npm run build
npm uninstall -g agents-orchestrator-cli
npm install -g .
asdf reshim nodejs

Usage

Authentication

First, authenticate with Agent Orchestrator:

ao login

This will:

1. Start a local HTTP server for the OAuth callback
2. Open your browser to the Agent Orchestrator authentication page
3. Save your session token to ~/.claude-orchestrator/config.json

Initialize Repository Hooks

In your project directory, initialize Claude Code hooks:

ao init

This will:

1. Create a .claude/ directory
2. Install the Agent Orchestrator hook script (agent-orchestrator-hook.js)
3. Create or update .claude/settings.json with proper hook configuration

Check Status

Check your authentication and setup status:

ao status

Commands

• ao login - Authenticate with Agent Orchestrator (validates existing tokens)
• ao init - Initialize Claude hooks in current repository (requires valid authentication)
• ao status - Check authentication and configuration status (validates tokens with backend)
• ao --help - Show help information

How It Works

1. Authentication: The CLI uses browser-based OAuth flow with your Agent Orchestrator account
2. Token Validation: All commands validate authentication tokens with the backend to ensure they're still valid
3. Hook Installation: Creates a .claude/settings.json file with hook configuration and installs a hook script
4. Event Streaming: When you use Claude Code, the hooks receive JSON input via stdin and send events to localhost:4000/api/events

Hook Events

The installed hook captures these Claude Code events:

• PreToolUse - Before a tool is executed
• PostToolUse - After a tool completes
• Notification - General notifications
• Stop - When Claude stops
• SubagentStop - When a subagent stops

Configuration

Authentication data is stored in ~/.claude-orchestrator/config.json:

{
  "sessionToken": "your-session-token",
  "sessionId": "your-session-id",
  "userId": "your-user-id",
  "backendUrl": "http://localhost:4000"
}

Development

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev -- <command>

# Example
npm run dev -- login

Troubleshooting

Backend Connection Issues

Make sure the Agent Orchestrator backend is running on localhost:4000:

# In your backend directory
mix phx.server

Hook Not Working

1. Check that hooks are properly installed: ao status
2. Ensure you're authenticated: ao login
3. Verify the hook script exists: ls .claude/agent-orchestrator-hook.js
4. Check that hooks are configured: cat .claude/settings.json

Authentication Issues

1. Token expired or invalid: The CLI automatically validates tokens with the backend

   • If validation fails, run ao login to re-authenticate
   • The CLI will clear invalid tokens automatically

2. Backend connection issues: If the backend is unreachable during token validation

   • Ensure the backend is running: mix phx.server
   • Check the backend URL in ~/.claude-orchestrator/config.json

3. Manual token cleanup: If needed, clear existing config:

   rm ~/.claude-orchestrator/config.json
   ao login

Deploy

Local/Development: cd agents-orchestrator-cli npm run build npm install -g .

NPM Registry (public): npm run build npm publish

Private Registry: npm run build npm publish --registry

The CLAUDE.md file shows the testing/installation command for local deployment: npm run build && npm uninstall -g agents-orchestrator-cli && npm install -g . && asdf reshim nodejs