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

$3

``bash
npm install -g @agentrix/cli
`

Or with yarn:

`bash
yarn global add @agentrix/cli
`

$3

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

Upgrading

$3

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:

`bash
export AGENTRIX_DISABLE_UPDATE_CHECK=true
`

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

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

$3

You can also trigger an upgrade manually at any time:

`bash
agentrix upgrade
`

This command will:
- Upgrade to the latest version using npm
- Automatically restart the daemon if it was running

$3

You can also upgrade using npm directly:

`bash


Upgrade to latest version (fastest)

npm install -g @agentrix/cli@latest

Check installed version

agentrix --version
`

Note: After manual upgrade, restart the daemon:

`bash
agentrix stop
agentrix start
`

Quick Start

`bash


Start the daemon

agentrix start

Check status

agentrix status

List active sessions

agentrix ls

Stop a session

agentrix kill

Stop the daemon

agentrix stop
`

Commands

$3

- 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 - Stop a specific worker session
- agentrix killall - Clean up all runaway agentrix processes
- agentrix logout - Logout from Agentrix

$3

- agentrix doctor - Run system diagnostics

Architecture

$3

`
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

$3

- 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

$3

| 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 |

$3

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

$3

`bash


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
`

$3

`bash


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.

$3

TypeScript path alias @/ maps to src/.

Worker Types

$3


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

$3

- 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]