Skip to main content

Dependencies

The Agentrix CLI requires several external tools to run tasks. The daemon checks these at startup and agentrix doctor shows the full status.

CLI Core Dependencies​

git (required)​

Required for all tasks — every workspace is a git repository.

claude (required)​

The Claude Code CLI is required for Claude agent tasks, which cover most Agentrix use cases.

npm install -g @anthropic-ai/claude-code

codex (optional)​

Required only if you create Codex tasks. Claude tasks work without it.

npm install -g @codex-ai/codex-cli

Pi (built in)​

Pi tasks use the Pi SDK bundled with Agentrix, so no separate CLI is required. Configure providers, credentials, models, skills, and prompt templates in Pi's standard ~/.pi/agent/ directory. You can override that directory with PI_CODING_AGENT_DIR.

Sandbox Dependencies​

The sandbox isolates worker processes from the rest of your filesystem. The required tools differ by platform.

macOS — ripgrep​

ripgrep (rg) is used by the sandbox runtime on macOS.

brew install ripgrep

Alternative (MacPorts):

sudo port install ripgrep

Linux — bubblewrap + socat​

bubblewrap (bwrap) provides namespace-based sandboxing on Linux.

# Debian / Ubuntu
sudo apt install bubblewrap

# RHEL / CentOS / Fedora
sudo yum install bubblewrap
# or
sudo dnf install bubblewrap

# Arch Linux
sudo pacman -S bubblewrap

socat handles socket communication inside the sandbox.

# Debian / Ubuntu
sudo apt install socat

# RHEL / CentOS / Fedora
sudo yum install socat

# Arch Linux
sudo pacman -S socat

Check Dependency Status​

agentrix doctor

The doctor output shows each dependency with its installation status and path:

🔧 CLI Dependencies
✓ git - Version control system (required for all tasks)
  Location: /usr/bin/git
✓ claude - Claude Code CLI (required for most features)
  Location: /usr/local/bin/claude
⚠️  codex - Codex CLI (optional, for Codex tasks)
  Install: npm install -g @codex-ai/codex-cli

🔒 Sandbox Dependencies
Platform: macos
✓ ripgrep - Fast code search tool (required by sandbox)
  Location: /usr/local/bin/rg

✓ All required dependencies are installed

Startup Check​

agentrix start checks critical dependencies before launching the daemon. If any are missing it prints the error and exits without starting:

⚠️  Missing Critical Dependencies
Cannot start daemon. Missing: ripgrep

Run "agentrix doctor" for detailed dependency information and installation instructions.

Fix the missing dependency, then run agentrix start again.

PATH Issues​

If the CLI reports a dependency as missing even though it is installed, the binary may not be on your PATH.

# Find where npm installs global binaries
npm config get prefix
# Output example: /usr/local

# The binaries are in <prefix>/bin — add it to PATH if missing
export PATH="$PATH:$(npm config get prefix)/bin"

Add the export to your shell profile (~/.zshrc, ~/.bashrc, etc.) to make it permanent.

For tools installed with Homebrew:

# Homebrew sets PATH automatically on Apple Silicon via /opt/homebrew/bin
# Intel Macs use /usr/local/bin
# Verify:
echo $PATH | tr ':' '\n' | grep -E 'homebrew|local'