@agentrix/cli 0.3.2

package/README.md

@@ -0,0 +1,249 @@
+# 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)
+
+```bash
+npm install -g @agentrix/cli
+```
+
+Or with yarn:
+
+```bash
+yarn global add @agentrix/cli
+```
+
+### Install from source
+
+```bash
+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:
+
+```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
+```
+
+### Manual Upgrade Command
+
+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
+
+### Using npm Directly
+
+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 <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
+
+```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
+```
+
+### Testing
+
+```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.
+
+### 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]

package/bin/agentrix.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { join, dirname } from 'path';
+
+// Check if we're already running with the flags
+const hasNoWarnings = process.execArgv.includes('--no-warnings');
+const hasNoDeprecation = process.execArgv.includes('--no-deprecation');
+
+if (!hasNoWarnings || !hasNoDeprecation) {
+  // Get path to the actual CLI entrypoint
+  const projectRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+  const entrypoint = join(projectRoot, 'dist', 'index.mjs');
+  
+  // Execute the actual CLI directly with the correct flags
+  try {
+    execFileSync(process.execPath, [
+      '--no-warnings',
+      '--no-deprecation',
+      entrypoint,
+      ...process.argv.slice(2)
+    ], {
+      stdio: 'inherit',
+      env: process.env
+    });
+  } catch (error) {
+    // execFileSync throws if the process exits with non-zero
+    process.exit(error.status || 1);
+  }
+} else {
+  // We're running Node with the flags we wanted, import the CLI entrypoint
+  // module to avoid creating a new process.
+  await import("../dist/index.mjs");
+}