Agentrix CLI

A daemon-based CLI for managing AI agent workers (Claude Code and Codex) in isolated workspaces with git integration.

Overview

Agentrix CLI enables you to run AI agents (Claude or Codex) as background workers that operate in isolated workspaces. Each worker maintains its own git state and communicates with the Agentrix backend server via WebSocket.

Installation

Install from npm (Recommended)

npm install -g @agentrix/cli

Or with yarn:

yarn global add @agentrix/cli

Install from source

git clone https://github.com/xmz-ai/agentrix-cli.git
cd agentrix-cli
yarn install
yarn build

Upgrading

Automatic Update Check

When you run agentrix start, the CLI automatically checks for updates and notifies you if a newer version is available.

To disable automatic update checks, set the environment variable:

export AGENTRIX_DISABLE_UPDATE_CHECK=true

Or add it to your shell profile (~/.bashrc, ~/.zshrc, etc.):

echo 'export AGENTRIX_DISABLE_UPDATE_CHECK=true' >> ~/.zshrc

Manual Upgrade Command

You can also trigger an upgrade manually at any time:

agentrix upgrade

This command will:

• Upgrade to the latest version using npm
• Automatically restart the daemon if it was running

Using npm Directly

You can also upgrade using npm directly:

# Upgrade to latest version (fastest)
npm install -g @agentrix/cli@latest

# Check installed version
agentrix --version

Note: After manual upgrade, restart the daemon:

agentrix stop
agentrix start

Quick Start

# Start the daemon
agentrix start

# Check status
agentrix status

# List active sessions
agentrix ls

# Stop a session
agentrix kill <sessionId>

# Stop the daemon
agentrix stop

Commands

Core Commands

• agentrix start - Start the daemon (if not running) and show status
• agentrix stop - Stop the daemon
• agentrix status - Show daemon and authentication status
• agentrix upgrade - Upgrade CLI to the latest version (auto-restarts daemon)
• agentrix ls - List active worker sessions
• agentrix kill <sessionId> - Stop a specific worker session
• agentrix killall - Clean up all runaway agentrix processes
• agentrix logout - Logout from Agentrix

Diagnostic Commands

• agentrix doctor - Run system diagnostics

Architecture

Process Model

CLI Entry (bin/agentrix.mjs)
    ↓
Daemon Process (src/daemon/run.ts)
    ↓
Worker Processes (src/worker/)
    ├── ClaudeWorker
    └── CodexWorker

• Daemon: Long-running background service that manages worker sessions
• Workers: Isolated agent execution environments that run in separate processes
• Communication: Workers connect to backend via WebSocket for real-time interaction

Key Components

• Machine (src/machine.ts) - Manages machine identity, credentials, and state
• Control Server (src/daemon/controlServer.ts) - HTTP server for daemon management
• TaskWorkerManager (src/daemon/sessions.ts) - Manages worker process lifecycle
• WorkerClient (src/worker/workerClient.ts) - WebSocket client for backend communication
• Git State Manager (src/worker/gitStateManager.ts) - Handles git operations for workers

Configuration

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | AGENTRIX_SERVER_URL | https://agentrix.xmz.ai | Backend server URL | | AGENTRIX_WEBAPP_URL | https://agentrix.xmz.ai | Web app URL | | AGENTRIX_HOME_DIR | ~/.agentrix | State directory | | AGENTRIX_WORKSPACE_HOME_DIR | ~/.agentrix/workspaces | Workspace directory | | AGENTRIX_AGENTS_HOME_DIR | ~/.agentrix/agents | Agent configs directory | | AGENTRIX_DISABLE_CAFFEINATE | false | Disable sleep prevention | | AGENTRIX_DISABLE_UPDATE_CHECK | false | Disable automatic update check on start | | DEBUG | - | Enable debug logging |

State Files

All state is stored in ~/.agentrix/ (configurable via AGENTRIX_HOME_DIR):

• credentials.json - Authentication token and machine credentials
• daemon.state.json - Daemon PID, port, version info
• daemon.state.json.lock - Lock file for daemon process
• machine.key / machine.key.pub - Machine keypair for encryption
• settings.json - User settings
• logs/ - Daemon and worker log files

Development

Build Commands

# Type-check and build
yarn build

# Type-check only
yarn typecheck

# Run with development environment
yarn dev

# Run with production environment
yarn prod

# Run linter
yarn lint

Testing

# Run all tests
yarn test

# Run a single test file
yarn build && npx vitest run src/utils/hmac_sha512.test.ts

Note: Tests require building first because daemon commands directly execute the binary.

Path Aliases

TypeScript path alias @/* maps to src/*.

Worker Types

ClaudeWorker

• Uses @anthropic-ai/claude-agent-sdk
• Supports all Claude Code capabilities
• Auto-commits changes on completion

CodexWorker

• Uses @openai/codex-sdk
• Supports special commands (merge-request)
• Auto-generates diffs and commits

Both workers:

• Setup workspace and handle git state on start
• Connect to backend via WebSocket
• Process user messages and stream responses
• Clean up git state on exit

Monorepo Structure

This CLI is part of the Agentrix monorepo:

agentrix/
├── api/       - Backend API server
├── app/       - Frontend web/mobile app
├── shared/    - Shared types and utilities
└── cli/       - This package

Main development branch: develop

Dependencies

• @anthropic-ai/claude-agent-sdk - Claude agent integration
• @openai/codex-sdk - Codex agent integration
• @agentrix/shared - Shared types and utilities (monorepo sibling)
• ws - WebSocket client
• yargs - CLI framework
• effect - Functional programming utilities

License

[License information to be added]