Mobile and Web client for Claude Code and Codex
npm install @agentrix/cliA daemon-based CLI for managing AI agent workers (Claude Code and Codex) in isolated workspaces with git integration.
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.
``bash`
npm install -g @agentrix/cli
Or with yarn:
`bash`
yarn global add @agentrix/cli
`bash`
git clone https://github.com/xmz-ai/agentrix-cli.git
cd agentrix-cli
yarn install
yarn build
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
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
You can also upgrade using npm directly:
`bashUpgrade to latest version (fastest)
npm install -g @agentrix/cli@latest
Note: After manual upgrade, restart the daemon:
`bash
agentrix stop
agentrix start
`Quick Start
`bash
Start the daemon
agentrix startCheck status
agentrix statusList active sessions
agentrix lsStop 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 diagnosticsArchitecture
$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 workersConfiguration
$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 filesDevelopment
$3
`bash
Type-check and build
yarn buildType-check only
yarn typecheckRun with development environment
yarn devRun with production environment
yarn prodRun linter
yarn lint
`$3
`bash
Run all tests
yarn testRun 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 commitsBoth 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:
developDependencies
-
@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 information to be added]