A modular, autonomous AI agent runtime that runs locally on your machine. Connect via WhatsApp, CLI, or Web interface. ANT manages memory, schedules tasks, and continuously improves itself through its Main Agent system.
- Multi-Channel Support - Interact via WhatsApp, CLI commands, or Web UI (React + Tailwind)
- Cron Scheduling - Schedule recurring agent tasks with cron expressions
- Memory System - Semantic search with embeddings over notes and session history (SQLite)
- Main Agent Loop - Ralph-inspired autonomous system that continuously monitors, maintains, and improves
- Subagents - Spawn parallel workers for complex tasks
- Local Tools - File operations, shell commands, screenshots, browser automation (Playwright)
- Pluggable Providers - OpenAI-compatible APIs (LM Studio) or CLI tools (Codex, Claude, Copilot)
- Provider Discovery & Survival Mode - Auto-discover local backups (Ollama/LM Studio) and recover when providers fail
- Web Dashboard - Real-time monitoring, session history, memory search, and system health
- Health + Watchdog -
/healthliveness,/readydependency readiness, optional watchdog supervisor
# Clone and install
git clone <repo-url>
cd ant-cli
npm install
# Build the project
npm run build
# Build the web UI (production)
npm run ui:build- Node.js 22+ - Runtime engine
- WhatsApp account - For QR pairing (optional if using CLI/Web only)
- LM Studio or OpenAI-compatible API - For local LLM inference
- macOS/Linux - Primary support (Windows WSL2 compatible)
- Screen Recording permission (macOS) - For screenshot/recording tools
Copy ant.config.example.json to ~/.ant/ant.config.json (or run ant onboard to generate config + .env interactively). ant auto-detects the nearest ant.config.json by walking upwards from your current directory; otherwise it falls back to ~/.ant/ant.config.json (see docs/config.md). Put secrets and machine paths in .env (notably ANT_WORKSPACE_DIR and ANT_RUNTIME_REPO_ROOT if your config lives in ~/.ant).
{
"workspaceDir": "~",
"providers": {
"default": "lmstudio",
"items": {
"lmstudio": {
"type": "openai",
"baseUrl": "http://localhost:1234/v1",
"model": "your-model-name",
"embeddingsModel": "text-embedding-nomic-embed-text-v1.5"
}
}
},
"whatsapp": {
"sessionDir": "./.ant/whatsapp",
"respondToSelfOnly": true,
"typingIndicator": true
},
"memory": {
"enabled": true,
"sqlitePath": "./.ant/memory.sqlite"
},
"scheduler": {
"enabled": true,
"storePath": "./.ant/jobs.json"
},
"ui": {
"enabled": true,
"port": 5117,
"autoOpen": true
},
"mainAgent": {
"enabled": true,
"intervalMs": 300000
}
}# Development mode (with hot reload)
npm run dev -- run
# With TUI dashboard (real-time monitoring + drone flights)
npm run dev -- run --tui
# Production mode
npm startOpen http://localhost:5117 in your browser to access:
- 🎛️ Royal Chamber - Main dashboard with real-time status
- 💬 Chat Interface - Direct conversation with the agent
- 📊 Sessions - View and export conversation history
- 🧠 Memory - Search semantic knowledge base
- ⚙️ Settings - Configure runtime options
Scan the QR code in the terminal to pair with WhatsApp and start chatting!
Enable automatic backup discovery in your ant.config.json:
{
"providers": {
"discovery": {
"enabled": true,
"researchIntervalHours": 24,
"healthCheckIntervalMinutes": 120,
"minBackupProviders": 1
},
"local": {
"enabled": true,
"preferFastModels": true,
"autoDownloadModels": false,
"ollama": { "enabled": true, "endpoint": "http://localhost:11434" },
"lmstudio": { "enabled": true, "endpoint": "http://localhost:1234/v1" }
}
}
}Optional env vars for remote backups (only used if set):
OPENROUTER_API_KEY,OPENROUTER_MODELGROQ_API_KEY,GROQ_MODELTOGETHER_API_KEY,TOGETHER_MODELMISTRAL_API_KEY,MISTRAL_MODEL
Discovered providers are stored in .ant/providers.discovered.json and merged at runtime (no changes to ant.config.json).
GET /health→ liveness (fast OK)GET /ready→ readiness (providers + memory + whatsapp)
docker build -t ant-cli:latest -f Dockerfile.prod .
docker compose up -ddocker build -t ant-watchdog:latest -f Dockerfile.watchdog .| Command | Description |
|---|---|
ant start |
Start the agent runtime |
ant start --tui |
Start with TUI dashboard |
ant start --detached |
Run in background |
ant stop |
Stop the running agent |
ant restart |
Restart the agent |
ant status |
Show runtime status |
| Command | Description |
|---|---|
ant ask "<prompt>" |
Ask a one-off question |
ant ask -s <session> "<prompt>" |
Ask in a specific session |
ant run-task "<description>" |
Spawn a long-running task |
ant run-task -w "<description>" |
Spawn and wait for completion |
ant list-tasks |
Show active tasks |
ant list-tasks -a |
Show all tasks including completed |
| Command | Description |
|---|---|
ant schedule add "0 9 * * *" -p "<prompt>" |
Schedule daily 9am task |
ant schedule list |
List all scheduled jobs |
ant schedule run <jobId> |
Manually trigger a job |
ant schedule remove <jobId> |
Delete a scheduled job |
Built-in drone flights are registered automatically at runtime start. See DRONE_FLIGHTS.md
for the hourly X AI+Tech digest and Safari cookie helper requirements.
| Command | Description |
|---|---|
ant remember "<note>" |
Add a note to memory |
ant recall "<query>" |
Search memory |
ant recall -l 10 "<query>" |
Search with limit |
ant memory export -f json -o backup.json |
Export memory |
| Command | Description |
|---|---|
ant sessions list |
List all sessions |
ant sessions view <key> |
View session messages |
ant sessions export <key> -f markdown |
Export session |
ant sessions clear <key> |
Clear a session |
ant sessions clear -a |
Clear all sessions |
| Command | Description |
|---|---|
ant logs |
Tail live logs |
ant logs -n 100 -l error |
Last 100 error logs |
ant dashboard |
Show TUI dashboard |
ant doctor |
Run health checks |
ant doctor --fix |
Auto-fix issues |
| Command | Description |
|---|---|
ant main-agent status |
Check Main Agent status |
ant main-agent pause |
Pause Main Agent loop |
ant main-agent resume |
Resume Main Agent loop |
ant main-agent logs |
View Main Agent log file |
| Command | Description |
|---|---|
ant list-tools |
Show all available tools |
ant tool <name> |
Get tool details and schema |
ant onboard |
Interactive setup wizard |
ant mcp-server |
Run MCP server over stdio |
ant subagents list |
List active subagents |
ant subagents cleanup |
Clean up completed subagents |
| Command | Description |
|---|---|
ant debug run "<prompt>" |
Run prompt without WhatsApp |
ant debug simulate "<text>" |
Simulate inbound message |
ANT includes a programmatic harness for repeatable “polish loops”: inject a simulated WhatsApp inbound message, observe outbound responses, and capture full trace logs + session artifacts in an isolated temp run directory.
# Inject an inbound WhatsApp message (child-process mode; closest to real CLI runtime)
npm run dev -- diagnostics harness --message "Reply with exactly: PONG" --mode child_process --timeout 120000
# Faster, in-process mode (best observability)
npm run dev -- diagnostics harness --message "Reply with exactly: PONG" --mode in_process --timeout 120000The command writes a harness-report.json and a full .ant/ state tree (sessions, logs) into a temp directory printed at the end of the run.
Useful flags:
--launch-target src|dist(default:src) to run against TypeScript or built output--enable-memory,--enable-main-agent,--enable-schedulerto include more subsystems--no-block-exec-deletesto disable the exec delete guard
When running in test mode (NODE_ENV=test) the gateway exposes endpoints used by harnesses:
POST /api/test/whatsapp/inbound— inject an inbound messageGET /api/test/whatsapp/outbound— list outbound messages recorded by the test adapterPOST /api/test/whatsapp/outbound/clear— clear outbound buffer
These endpoints are disabled outside test mode (or can be forced with ANT_ENABLE_TEST_API=1).
ant loads a single config file (selected by -c, ANT_CONFIG_PATH, nearest ant.config.json, or fallback ~/.ant/ant.config.json). Secrets (API keys, tokens) should live in .env (gitignored), not in ant.config.json. See docs/config.md.
{
"workspaceDir": "~", // Base directory for file operations
"logging": {
"level": "info", // Console log level
"fileLevel": "debug" // File log level (~/.ant/ant.log)
}
}{
"providers": {
"default": "lmstudio",
"items": {
"lmstudio": {
"type": "openai",
"baseUrl": "http://localhost:1234/v1",
"model": "your-model",
"embeddingsModel": "text-embedding-nomic-embed-text-v1.5"
},
"codex": {
"type": "cli",
"cliProvider": "codex"
}
}
},
"routing": {
"chat": "codex", // Provider for chat responses
"tools": "lmstudio", // Provider for tool calls
"embeddings": "lmstudio" // Provider for memory embeddings
}
}{
"whatsapp": {
"sessionDir": "./.ant/whatsapp",
"respondToSelfOnly": true, // Only respond to your own messages
"respondToGroups": false,
"mentionOnly": true,
"typingIndicator": true
},
"ui": {
"enabled": true,
"port": 5117,
"autoOpen": true
},
"gateway": {
"enabled": true,
"port": 18789 // HTTP API for programmatic access
}
}{
"memory": {
"enabled": true,
"sqlitePath": "./.ant/memory.sqlite",
"indexSessions": true,
"sync": {
"onSessionStart": true,
"onSearch": true,
"watch": true
}
}
}{
"scheduler": {
"enabled": true,
"storePath": "./.ant/jobs.json",
"timezone": "UTC"
}
}{
"mainAgent": {
"enabled": true,
"iterationDelayMinutes": 5,
"maxIterationsPerTask": 10,
"maxConsecutiveFailures": 3,
"dutiesFile": "AGENT_DUTIES.md",
"logFile": "AGENT_LOG.md",
"alertOwnerOnCritical": true,
"duties": {
"subagentManagement": true,
"systemMaintenance": true,
"memoryManagement": true,
"improvements": true,
"monitoring": true
}
}
}{
"monitoring": {
"enabled": true,
"retentionDays": 30,
"alertChannels": ["whatsapp"],
"criticalErrorThreshold": 5
}
}┌────────────────────────────────────────────────────────────────┐
│ Channels Layer │
│ WhatsApp (Baileys) │ CLI Interface │ Web UI │ HTTP Gateway │
└──────────────────────────┬─────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────┐
│ Message Router │
│ Routes messages to sessions, manages queue per conversation │
└──────────────────────────┬─────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────┐
│ Agent Runtime │
│ Prompt building │ Tool loop │ Provider routing │ Subagents │
└────┬─────────────┬───────────┬───────────────┬─────────────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌─────────┐ ┌──────────┐ ┌─────────┐ ┌───────────┐
│ Tools │ │Providers│ │ Memory │ │ Subagents │
│ │ │ │ │ │ │ │
│ • File │ │ • OpenAI │ │ • SQLite│ │ • Jobs │
│ • Exec │ │ • CLI │ │ • Vector│ │ • Monitors│
│ • Media │ │ tools │ │ • Search│ │ │
│ • Browse│ │ │ │ │ │ │
└─────────┘ └──────────┘ └─────────┘ └───────────┘
│
▼
┌─────────────────────┐
│ Main Agent Loop │
│ (Ralph-Inspired) │
│ • Duty Execution │
│ • System Monitoring │
│ • Auto-Improvements │
└─────────────────────┘
| Component | Location | Purpose |
|---|---|---|
| Channels | src/channels/ |
WhatsApp, CLI, Web, Gateway adapters |
| Agent | src/agent/ |
Core agent logic, prompt building, tool calls |
| Tools | src/tools/ |
Built-in tool implementations (40+) |
| Memory | src/memory/ |
Embeddings, SQLite store, semantic search |
| Scheduler | src/scheduler/ |
Cron job management and execution |
| Monitor | src/monitor/ |
Metrics, alerting, event streaming |
| Gateway | src/gateway/ |
HTTP API for external integrations |
| Supervisor | src/supervisor.ts |
Main Agent loop, duty execution |
| CLI | src/cli/ |
Command-line interface |
.ant/
├── whatsapp/ # WhatsApp session data (Baileys)
├── sessions/ # Conversation history (JSONL)
├── memory.sqlite # Embeddings & memory index
├── jobs.json # Scheduled jobs
├── subagents.json # Active/completed subagents
├── ant.log # Runtime logs
└── main-agent.log # Main Agent activity log
The Main Agent is an autonomous background supervisor that continuously monitors, maintains, and improves the runtime. It's inspired by the Ralph Wiggum loop philosophy—a self-referential feedback cycle where the agent reviews its own work and builds upon it.
✅ Autonomous Operation - Runs every 5 minutes without user intervention ✅ Self-Aware - Reviews its own logs and session history ✅ Maintenance Focused - Keeps system healthy and optimized ✅ Error Recovery - Detects issues and attempts fixes ✅ Learning Loop - Improves strategy based on past iterations ✅ Owner Alerts - Notifies you on critical issues via WhatsApp
-
Iteration Cycle (Every 5 minutes by default):
Read Duties → Inspect State → Execute Tasks → Log Results → Sleep → Repeat -
Core Responsibilities:
- 🔧 Subagent Management - Monitor, restart, archive parallel tasks
- 🧹 System Maintenance - Cleanup old logs, check health, prune large files
- 🧠 Memory Management - Index new content, detect duplicates, optimize
- 📈 Improvements - Analyze patterns, suggest optimizations, learn from usage
- 🚨 Monitoring - Track errors, usage, resource consumption, send alerts
-
Self-Correction:
- Learns from previous iterations
- Adjusts tactics based on failures
- Pauses after 3 consecutive failures
- Logs all actions for transparency
Add to ant.config.json:
{
"mainAgent": {
"enabled": true,
"dutiesFile": "AGENT_DUTIES.md",
"logFile": ".ant/AGENT_LOG.md",
"intervalMs": 300000
}
}Create AGENT_DUTIES.md in your workspaceDir (often your project root). If your workspaceDir is something like ~/.ant, create it there instead. See docs/agent-files.md for how ant resolves these paths.
# Main Agent Duties
## 1. Subagent Management
- Read `.ant/subagents.json` for active tasks
- Check if any subagent has been running > 10 minutes
- Flag stuck/failed subagents and attempt restart
- Archive completed runs older than 24 hours
## 2. System Maintenance
- Delete session files older than 30 days
- Warn if any single session exceeds 10 MB
- Test provider connectivity (embeddings model)
- Check available disk space in `.ant/`
## 3. Memory Management
- Re-index memory if new content detected
- Archive old sessions as memory summaries
- Detect broken internal links
- Consolidate duplicate entries
## 4. Improvements & Optimization
- Analyze tool usage patterns from session history
- Suggest new tools based on common requests
- Identify repetitive tasks for automation
- Review error logs for optimization opportunities
## 5. Monitoring & Alerting
- Count errors in last 1000 log lines
- Track provider API usage/costs
- Detect unusual activity patterns
- Send WhatsApp alert if critical threshold reached
## Completion
After checking all duties, output:
<promise>DUTY_CYCLE_COMPLETE</promise># View duty execution log
tail -f .ant/AGENT_LOG.md
# Check Main Agent session
ant sessions view "agent:main:system"
# Monitor in TUI dashboard
ant start --tui
# Check status
ant main-agent status✅ Clear, actionable duties - Each duty should have specific steps ✅ Idempotent operations - Safe to run multiple times ✅ Log everything - Append to AGENT_LOG.md with timestamps ✅ Graceful failures - Try alternatives, don't crash ✅ Owner notifications - Ask for help on uncertain decisions
The agent has access to comprehensive tools for system control:
File Operations: read, write, append, ls, mkdir, rm
Execution: exec, open_app, restart_ant
Media: screenshot, screen_record, send_file
Browser: browser (Playwright automation)
Memory: memory_search, memory_get, memory_recall
Messages: message_send, sessions_spawn, sessions_send
External CLI: external_cli (Codex, Copilot, Claude)
Social: bird (Twitter/X via bird CLI)
For full tool documentation, run:
ant list-tools
ant tool <tool-name>- PROJECT.md - Complete technical documentation
- AGENT_DUTIES.md - Main Agent responsibilities template
docs/agent-files.md- Where agent docs/logs live (repo vs workspace vs state)- AGENTS.md - Quick reference for AI agents
MIT