This guide will walk you through setting up APEX and running your first automated development task.
Before you begin, ensure you have:
- Node.js 18 or higher - Download Node.js
- Anthropic API Key - Get an API key
- Git - For version control operations
For Windows users, ensure you have:
- Node.js 18+ - Install from nodejs.org or use
winget install OpenJS.NodeJS - Git for Windows - Download for full Git functionality
- PowerShell 5.1+ - Included with Windows 10/11
- Windows Terminal (recommended) - Install from Microsoft Store for the best CLI experience
Note: APEX works in Command Prompt, PowerShell, Git Bash, and Windows Terminal. We recommend Windows Terminal for the best experience with colors and formatting.
All Platforms:
npm install -g @apexcli/cliWindows-Specific:
# PowerShell (recommended)
npm install -g @apexcli/cli
# Or install Node.js first with winget
winget install OpenJS.NodeJS
npm install -g @apexcli/clinpx @apexcli/cli <command>git clone https://github.com/JoshuaAFerguson/apex.git
cd apex
npm install
npm run build
npm linkWindows Note: If you encounter permission issues during global installation, run your terminal as Administrator or use
npm config set prefix %APPDATA%\npmto install to your user directory.
Unix/Linux/macOS:
export ANTHROPIC_API_KEY=your_api_key_hereWindows Command Prompt:
set ANTHROPIC_API_KEY=your_api_key_hereWindows PowerShell:
$env:ANTHROPIC_API_KEY="your_api_key_here"Unix/Linux/macOS: Add to your shell profile (~/.bashrc, ~/.zshrc, etc.):
echo 'export ANTHROPIC_API_KEY=your_api_key_here' >> ~/.bashrc
source ~/.bashrcWindows: Set permanently using System Properties:
- Press
Win + R, typesysdm.cpl, press Enter - Click "Environment Variables" button
- Under "User variables", click "New"
- Variable name:
ANTHROPIC_API_KEY - Variable value:
your_api_key_here - Click OK and restart your terminal
Or use PowerShell to set permanently:
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "your_api_key_here", "User")
# Restart your terminal after running this commandNavigate to your project directory and run:
cd your-project
apex initYou'll be prompted for:
- Project name - Name of your project
- Language - Primary programming language (typescript, python, etc.)
- Framework - Optional framework (nextjs, fastapi, etc.)
This creates the .apex/ directory with default configuration, agents, and workflows.
Open .apex/config.yaml to customize:
version: "1.0"
project:
name: "my-project"
language: "typescript"
autonomy:
default: "review-before-merge" # Human approval before merging
limits:
max_cost_per_task: 10.00 # Safety limitapex run "Add a health check endpoint to the API"APEX will:
- Create a feature branch
- Plan the implementation
- Write the code
- Create tests
- Review the changes
- Create a pull request (if configured)
APEX v0.5.0 introduces powerful new capabilities. Here's how to get started:
Install browser dependencies for web testing and automation:
# Install Playwright browsers
npx playwright install chromium
# Test browser connectivity
apex browser test-connectionAdd v0.5.0 features to your .apex/config.yaml:
# Permission system (choose one preset)
permissions:
preset: autonomous # Full automation (recommended for trusted environments)
# preset: reviewAll # Prompt for every operation (recommended for learning)
# preset: readOnly # Safe exploration mode (no file modifications)
persistence: true # Remember permission decisions
# Browser automation
tools:
browser:
enabled: true
engine: chromium
headless: true
allowedDomains:
- localhost
- '*.local'
- 'staging.example.com'
blockedDomains:
- '*.onion'
- 'malicious.site'
# Smart autonomy controls
autonomy:
enabled: true
limits:
budgetLimit: 10.0 # Stop at $10 USD
tokenLimit: 100000 # Stop at 100k tokens
timeLimit: 3600000 # Stop after 1 hour
changeLimit:
files: 20 # Max 20 files modified
lines: 1000 # Max 1000 lines changed
warningThreshold: 0.8 # Warn at 80% of limits
# Code quality integration
codeQuality:
lintAfterEdit: true # Auto-lint after file edits
autoCorrection: true # Fix syntax errors automatically
tddMode: false # Test-driven development mode
regressionGuard: true # Prevent breaking changesTry these commands to test the new capabilities:
# Test browser automation
apex run "Create a login form with visual regression tests"
# Test permission system
apex run --autonomy reviewAll "Update database configuration"
# Test tool system with autonomy controls
apex run "Add authentication middleware with rate limiting"Choose the right permission preset for your workflow:
-
autonomous- Maximum automation efficiency- Most tools auto-approved
- Great for trusted, repetitive workflows
- Dangerous operations still require confirmation
-
reviewAll- Maximum control and learning- Every tool operation requires approval
- Perfect for understanding how APEX works
- Ideal for security-sensitive environments
-
readOnly- Safe exploration mode- Blocks all write operations
- Perfect for reviewing unknown codebases
- No risk of accidental changes
When you run a task, you'll see:
🚀 Starting APEX task...
Task created: task_abc123_def456
Branch: apex/abc123-add-health-check
Workflow: feature
Autonomy: review-before-merge
📍 Stage: planning
🔧 Read
🔧 Grep
📍 Stage: implementation
🔧 Write
🔧 Bash
✅ Task Completed
Tokens: 45,234
Cost: $0.1523
Duration: 3m 42s
APEX now features a rich terminal interface with real-time updates, enhanced visual feedback, and customizable display modes:
Tasks display live progress with detailed stage information:
🚀 APEX Task: Add authentication middleware
┌─ Task Progress ──────────────────────────────────────┐
│ Stage: implementation [■■■■■■■░░░] 70% │
│ Agent: developer │
│ File: src/middleware/auth.ts │
│ │
│ Recent Actions: │
│ ✓ Created auth middleware structure │
│ ✓ Added JWT validation logic │
│ → Writing error handling... │
└──────────────────────────────────────────────────────┘
Tokens: 12,456 | Cost: $0.0425 | Elapsed: 1m 23s
Customize how information is displayed to match your workflow:
# Toggle compact mode for minimal display
/compact
● main | $0.0425
# Toggle verbose mode for maximum detail
/verbose
● main | ⚡developer | ▶implementation | tokens: 1.5k→800 | total: 2.3k | cost: $0.0425 | 🔍 VERBOSE
# Return to normal balanced display
/compact # (toggles off)Three Display Modes:
- Normal - Balanced information display (default)
- Compact - Minimal display for focus or small terminals
- Verbose - Maximum information for debugging and analysis
See Display Modes Guide for complete details.
Preview what will be sent to Claude before executing commands:
# Enable preview mode
/preview on
# Now when you type commands, you'll see:
┌─ Input Preview ─────────────────────────────────────┐
│ Input: "implement user authentication" │
│ │
│ Intent: task_execution (85% confidence) │
│ This will be sent to the developer agent │
│ │
│ [Enter] Execute [Escape] Cancel [E] Edit │
└─────────────────────────────────────────────────────┘Benefits of Input Preview:
- Verify your intent before execution
- See confidence levels for command interpretation
- Catch potential issues before they happen
- Learn how APEX processes different input types
See Input Preview Guide for complete details.
Control task execution with keyboard shortcuts:
Space- Pause/resume taskq- Quit taskl- View detailed logsEnter- Approve current stage (manual mode)/compact- Toggle compact display mode/verbose- Toggle verbose display mode/preview on|off- Control input preview mode
- 🟢 Success indicators
- 🟡 Warnings and reviews
- 🔴 Errors and failures
- 🔵 Information and status updates
- 📋 Preview mode active indicator
- 🔍 Verbose mode active indicator
APEX's terminal interface is built on a modern React-based framework designed for exceptional developer experience. This section covers the 8 core UI capabilities that power the interactive CLI.
APEX uses Ink, a React renderer for CLI applications, enabling component-based terminal interfaces with familiar React patterns:
Components render as a tree, just like React DOM:
┌─ App ─────────────────────────────────┐
│ ├─ Banner │
│ ├─ StatusBar │
│ ├─ TaskProgress │
│ ├─ AgentPanel │
│ └─ InputPrompt │
└───────────────────────────────────────┘
The component architecture enables maintainable, testable terminal interfaces with proper state management and event handling.
Experience live updates as agents work, with character-by-character streaming and animated cursors:
Streaming output with live cursor:
┌──────────────────────────────────────┐
│ The agent is analyzing your code...▊ │
└──────────────────────────────────────┘
Text appears dynamically with typewriter effects, creating an engaging real-time development experience that shows exactly what agents are thinking and doing.
Rich markdown content renders with full formatting support, making documentation and responses easy to read:
Markdown renders with full formatting:
# Header 1 (cyan, bold)
## Header 2 (blue, bold)
• Bullet points (yellow bullets)
1. Numbered lists (yellow numbers)
> Blockquotes (gray with │ prefix)
`inline code` (highlighted background)
Headers, lists, blockquotes, and inline code all render with appropriate colors and formatting for maximum readability.
Code blocks receive full syntax highlighting for supported languages (TypeScript, JavaScript, Python, Rust, Go):
┌─ typescript ────────── 5 lines ──┐
│ 1 │ const greeting = "Hello"; │
│ 2 │ function sayHello() { │
│ 3 │ // This is a comment │
│ 4 │ console.log(greeting); │
│ 5 │ } │
└──────────────────────────────────┘
Keywords, strings, and comments are color-coded with line numbers. Code automatically wraps for narrow terminals while preserving readability.
View code changes with comprehensive diff rendering supporting three display modes:
Unified diff view:
--- src/api.ts
+++ src/api.ts
@@ -1,3 +1,4 @@
import express from 'express';
+ import cors from 'cors'; ← added (green)
const app = express();
- app.listen(3000); ← removed (red)
+ app.listen(process.env.PORT); ← added (green)
Unified, split, and inline modes automatically adapt to your terminal width. Line numbers, hunk headers, and color-coded additions/deletions make code changes clear.
The interface adapts to any terminal size using a 4-tier breakpoint system:
Breakpoint System:
┌────────────────────────────────────────────────────────────┐
│ Narrow │ Compact │ Normal │ Wide │
│ < 60 │ 60-99 │ 100-159 │ 160+ │
│ cols │ cols │ cols │ cols │
├───────────┼───────────┼────────────┼──────────────────────┤
│ Minimal │ Condensed │ Standard │ Full with extras │
│ UI only │ display │ display │ split diffs, etc. │
└────────────────────────────────────────────────────────────┘
Components automatically adjust their layout, information density, and visual elements based on available space using the useStdoutDimensions hook.
Comprehensive theming supports both dark and light modes with agent-specific color schemes:
Agent Colors (Dark Theme):
🟡 planner - Yellow
🔵 architect - Blue
🟢 developer - Green
🟣 reviewer - Magenta
🔵 tester - Cyan
🔴 devops - Red
The ThemeProvider manages consistent colors across all UI components, syntax highlighting, and diff views with automatic adaptation for different terminal capabilities.
Multiple progress indicator types provide clear feedback on task execution:
Progress indicators:
[■■■■■■■░░░] 70% ← Progress bar
◐ Loading... ← Spinner
Step 2 of 4: implementation ← Step progress
Progress bars show completion percentages, spinners indicate background activity, and step indicators track workflow stage progress. Multi-task views coordinate progress across parallel operations.
APEX maintains session state for improved workflow continuity:
View and manage active tasks:
# List all active sessions
apex sessions
# Resume a paused session
apex resume task_abc123_def456
# Attach to a running session
apex attach task_abc123_def456Sessions survive terminal disconnections and system restarts:
- Task state is automatically saved to
.apex/apex.db - Progress is preserved across interruptions
- Resume where you left off with full context
Run tasks in the background:
# Start task in background
apex run "Fix memory leak" --background
# Check background tasks
apex status --backgroundFor production environments or continuous operation, install APEX as a system service:
# Install as system service
apex install-service --enable
# Service will auto-start on boot and restart on failure
# View service status
systemctl --user status apex-daemon # Linux
launchctl list | grep apex # macOS📖 See Service Management Guide for complete installation, configuration, and troubleshooting instructions.
APEX supports intelligent tab completion for faster workflows:
# Complete commands
apex <tab>
# Shows: init, run, status, logs, sessions, serve
# Complete task IDs
apex status task_<tab>
# Shows recent task IDs
# Complete autonomy levels
apex run "task" --autonomy <tab>
# Shows: full, review-before-commit, review-before-merge, manual| Shortcut | Action |
|---|---|
Ctrl+C |
Graceful task termination |
Ctrl+Z |
Pause task (resume with fg) |
↑/↓ |
Navigate command history |
Tab |
Auto-complete commands/options |
Ctrl+L |
Clear terminal (preserves task state) |
Add to your shell profile for persistent completion:
Bash:
echo 'eval "$(apex completion bash)"' >> ~/.bashrcZsh:
echo 'eval "$(apex completion zsh)"' >> ~/.zshrcFish:
apex completion fish | sourceChoose how much control to give APEX:
| Level | Description |
|---|---|
full |
Complete autonomy - executes without stopping |
review-before-commit |
Pauses before each commit for review |
review-before-merge |
Creates PR and waits for human approval |
manual |
Pauses at each stage for approval |
Set the default in config or override per-task:
apex run "Fix login bug" --autonomy manualView task status:
# List recent tasks
apex status
# Get details for a specific task
apex status task_abc123_def456
# View logs
apex logs task_abc123_def456- v0.5.0 Features Overview - Complete guide to tools, permissions, and browser automation
- Tool System Guide - Built-in tools (Read, Write, Edit, Bash, Browser, etc.)
- Permission System Guide - Fine-grained security and access controls
- Browser Automation Guide - Headless browser testing and visual regression
- Complete v0.3.0 Features Overview - Comprehensive guide to all new features and capabilities
- Display Modes Guide - Customize how information is displayed (compact, normal, verbose)
- Input Preview Guide - Preview commands before execution with intent detection
- CLI Guide - Complete command reference and advanced features
- Service Management - Install and manage APEX as a system service
- Configure your agents - Customize agent behavior
- Define workflows - Create custom development workflows
- API Reference - Integrate with your tools
- Best Practices - Tips for effective usage
Run apex init in your project directory first.
Ensure your API key is set in the environment:
export ANTHROPIC_API_KEY=your_keyIncrease the limit in .apex/config.yaml:
limits:
max_cost_per_task: 20.00- Add more context to your task description
- Include acceptance criteria
- Customize agent prompts in
.apex/agents/
- GitHub Issues - Report bugs
- Discussions - Ask questions
- Discord - Community chat (coming soon)