@cortices/agent

Connect your AI coding agents to Cortices — a real-time dashboard to monitor, chat with, and manage your agents from anywhere. Works behind NAT with no port forwarding needed.

Supported Agents

| Agent | Command | Requirement | |-------|---------|-------------| | Claude Code | cortices-claude | Claude Code CLI | | OpenAI Codex | cortices-codex | CODEX_API_KEY or OPENAI_API_KEY | | OpenCode | cortices-opencode | OpenCode | | Native (multi-provider) | cortices-native | API key for any supported provider |

Quick Start

# 1. Sign up at https://cortices.io and create an API key (Settings → API Keys)

# 2. Run your agent
npx @cortices/agent --api-key ck_your_key_here

Your agent appears in your dashboard instantly.

Options

--api-key KEY     Your Cortices API key (required)
--dir DIR         Working directory (default: current directory)
--name NAME       Agent name shown in dashboard (default: auto-generated)
--interactive     Require approval for each tool call from the dashboard

Install as a Background Service

Run your agent as a persistent service that starts on boot and auto-restarts on failure.

# Install
npx @cortices/agent install --api-key ck_xxx --dir /path/to/project --name my-agent

# Manage
npx @cortices/agent list          # List installed agents
npx @cortices/agent status NAME   # Check agent status
npx @cortices/agent uninstall NAME # Remove agent

• Linux: creates a systemd user service
• macOS: creates a launchd agent

Viewing Logs

# Linux
journalctl --user -u cortices-agent-NAME -f

# macOS
tail -f ~/Library/Logs/Cortices/NAME.log

Native Agent (Multi-Provider)

The native agent (cortices-native) works with multiple LLM providers without requiring an external CLI:

# Use with Anthropic (default)
ANTHROPIC_API_KEY=sk-ant-... npx @cortices/agent native --api-key ck_xxx

# Use with OpenAI
OPENAI_API_KEY=sk-... npx @cortices/agent native --api-key ck_xxx --model openai/gpt-4o

# Use with Google
GOOGLE_API_KEY=... npx @cortices/agent native --api-key ck_xxx --model google/gemini-2.5-pro

# Use with OpenRouter (access any model)
OPENROUTER_API_KEY=... npx @cortices/agent native --api-key ck_xxx --model openrouter/anthropic/claude-sonnet-4

You can also configure provider API keys from the dashboard under Settings → Credentials, so the agent picks them up automatically.

Dashboard Features

Once connected, the dashboard gives you:

• Chat — send messages to your agent and see streaming responses
• File Browser — browse the agent's working directory with git status indicators
• File Viewer — view files with syntax highlighting
• Git Diff — unified diffs for any changed file
• Tool Calls — see what the agent is doing in real time (file edits, bash commands, etc.)
• Scheduled Tasks — set up recurring tasks with cron expressions
• Plans — define long-running, multi-step goals that the agent works through over time
• Memories — store persistent context (facts, preferences, learnings) that your agent remembers across sessions

Scheduled Tasks

Create recurring tasks directly from the dashboard, or via the agent's built-in CLI:

# Run a bash command every 5 minutes (free, no LLM cost)
schedule create --name "health check" --cron "*/5 * * * *" --command "curl -s https://example.com/health"

# Run a Claude prompt daily at 9am UTC
schedule create --name "daily summary" --cron "0 9 * * *" --prompt "Summarize yesterday's git commits"

Plans

Plans are stateful, multi-step tasks that maintain progress across runs:

# Create a plan that runs every 4 hours
plan create --name "migrate to TypeScript" \
  --cron "0 */4 * * *" \
  --description "Convert all .js files in src/ to TypeScript. Track progress in state."

The agent tracks its progress, remembers what it did last run, and picks up where it left off.

Permission Modes

• Auto-approve (default) — the agent executes tools automatically; you watch from the dashboard
• Interactive (--interactive) — every tool call requires your approval from the dashboard before it runs

Requirements

• Node.js 18+
• The CLI for your chosen agent type (Claude Code, Codex, or OpenCode) — not needed for native agent

Learn More

Visit cortices.io to get started.