Cortex

Self-hosted Claude AI agent with full system access. Gateway, memory, tools, Telegram, cron, heartbeat — all in one framework.

npm install -g agent-cortex
cortex start
cortex message "what's running on this server?"

What It Does

Cortex runs Claude as a persistent agent on your server with:

• 9 system tools — shell commands, file operations, web requests, memory, cron
• Persistent memory — SQLite database + daily markdown logs + curated long-term memory
• HTTP gateway — REST API + WebSocket for streaming on port 18800
• Telegram bot — talk to your agent from your phone
• Heartbeat — periodic health checks with customizable tasks
• Cron scheduler — schedule recurring agent tasks
• Webhook receiver — integrate with n8n, Zapier, or any HTTP client
• Soul/Identity system — define your agent's personality, rules, and knowledge

Authentication

Three ways to connect to Claude — pick one:

| Mode | Config | Cost | Best For | |------|--------|------|----------| | anthropic | ANTHROPIC_API_KEY in .env | Pay per token | Production, highest quality | | ccp | Claude Code Provider running locally | Free (uses CLI auth) | Dev machines with Claude Code | | cli | claude CLI installed + authenticated | Free (uses CLI auth) | Simplest zero-config setup |

Auto-detection: if no provider is set, Cortex checks for API key → CCP → CLI and picks the first available.

Using Claude Code Auth (Zero Cost)

If you already have Claude Code authenticated in your terminal:

# Option 1: CLI mode (simplest)
echo 'AGENT_PROVIDER=cli' >> .env
cortex start

# Option 2: Claude Code Provider (better for tool_use)
# Start CCP: https://github.com/anthropics/claude-code-provider
echo 'AGENT_PROVIDER=ccp' >> .env
echo 'CCP_BASE_URL=http://127.0.0.1:18321/v1' >> .env
cortex start

Quick Start

# Install globally
npm install -g agent-cortex

# Set up authentication
cd $(npm root -g)/agent-cortex
cp .env.example .env
nano .env  # add your ANTHROPIC_API_KEY or set provider

# Start the gateway
cortex start

# Talk to your agent
cortex message "list all running processes"
cortex message "check disk space and tell me if anything is concerning"
cortex message "create a cron job that checks system health every hour"

# Check status
cortex status
cortex sessions
cortex cron list

Architecture

cortex start
  ├── Gateway (Fastify HTTP + WS :18800)
  │     ├── REST API (/api/message, /api/sessions, /api/cron, /api/memory)
  │     ├── WebSocket (/ws) for streaming
  │     └── Webhook (/webhook/inbound) for external integrations
  │
  ├── Agent Brain (Claude API with tool_use loop)
  │     ├── shell_exec — run any shell command
  │     ├── file_read/write/edit — full filesystem access
  │     ├── web_fetch — HTTP requests
  │     ├── memory_save/search — persistent memory
  │     └── cron_create/list — scheduled tasks
  │
  ├── Memory (SQLite + daily markdown logs)
  │     ├── cortex-data/cortex.db — structured message history
  │     ├── workspace/memory/YYYY-MM-DD.md — daily conversation logs
  │     └── workspace/MEMORY.md — curated long-term memory
  │
  ├── Telegram Bot (optional)
  ├── Cron Scheduler (persistent jobs)
  └── Heartbeat (periodic health checks)

Configuration

cortex.json

Main config file — controls agent, gateway, channels, and automation:

{
  "agent": {
    "provider": "auto",
    "maxToolRounds": 25,
    "maxTokens": 8192
  },
  "gateway": {
    "port": 18800,
    "bind": "loopback"
  },
  "channels": {
    "telegram": {
      "enabled": false,
      "botToken": "",
      "allowFrom": []
    }
  },
  "heartbeat": {
    "enabled": true,
    "intervalMinutes": 30,
    "activeHours": { "start": 8, "end": 23, "tz": "UTC" }
  }
}

Workspace Files

Cortex uses markdown files to define the agent's personality and behavior:

| File | Purpose | |------|---------| | workspace/SOUL.md | Agent personality, values, communication style | | workspace/IDENTITY.md | Agent name and persona | | workspace/USER.md | Information about you (the owner) | | workspace/AGENTS.md | Behavioral rules, safety boundaries | | workspace/HEARTBEAT.md | What to check during periodic heartbeats | | workspace/MEMORY.md | Curated long-term memory (agent maintains this) | | workspace/TOOLS.md | Environment-specific notes |

Edit these to customize your agent's behavior.

API

All API endpoints require Authorization: Bearer <token> header (token from cortex.json).

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /health | Health check (no auth) | | POST | /api/message | Send message, get response | | GET | /api/sessions | List all sessions | | GET | /api/sessions/:id | Get session with history | | GET | /api/status | Agent status and stats | | GET | /api/cron | List cron jobs | | POST | /api/cron | Create cron job | | DELETE | /api/cron/:id | Delete cron job | | GET | /api/memory/search?q=... | Search memory | | POST | /api/memory | Save memory entry | | POST | /webhook/inbound | Receive webhook (optional X-Webhook-Secret) |

WebSocket

Connect to /ws for real-time streaming:

const ws = new WebSocket('ws://localhost:18800/ws');
ws.send(JSON.stringify({ type: 'message', text: 'hello' }));
ws.onmessage = (e) => console.log(JSON.parse(e.data));

CLI Commands

cortex start              Start the gateway
cortex stop               Stop the gateway
cortex status             Show status
cortex message <text>     Send a message to the agent
cortex sessions           List active sessions
cortex cron list          List cron jobs
cortex cron create        Create a cron job
cortex cron delete <id>   Delete a cron job
cortex memory <query>     Search agent memory
cortex auth               Check authentication status
cortex config             Show config (redacted)
cortex install-service    Install as systemd service

Telegram Setup

1. Create a bot via @BotFather
2. Add to .env:

   TELEGRAM_BOT_TOKEN=your-bot-token
   TELEGRAM_ALLOW_IDS=your-telegram-user-id

3. Enable in cortex.json:

   { "channels": { "telegram": { "enabled": true } } }

4. Restart: cortex stop && cortex start

Run as Service

# systemd (Linux)
cortex install-service
systemctl --user start cortex-gateway
systemctl --user status cortex-gateway

# PM2
pm2 start ecosystem.config.js
pm2 save

Tools

The agent has access to 9 tools via Claude's tool_use:

| Tool | Description | |------|-------------| | shell_exec | Execute any shell command (30s timeout) | | file_read | Read files with optional line range | | file_write | Write/create files | | file_edit | Find-and-replace in files | | web_fetch | HTTP requests (GET, POST, etc.) | | memory_save | Store entries in persistent memory | | memory_search | Search memory and past conversations | | cron_create | Create scheduled tasks | | cron_list | List all scheduled tasks |

Requirements

• Node.js >= 22.0.0
• One of: Anthropic API key, Claude Code Provider, or Claude CLI authenticated

License

MIT