# @cortices/agent

Connect your AI coding agents to [Cortices](https://cortices.io) — 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](https://docs.anthropic.com/en/docs/claude-code) |
| OpenAI Codex | `cortices-codex` | `CODEX_API_KEY` or `OPENAI_API_KEY` |
| OpenCode | `cortices-opencode` | [OpenCode](https://opencode.ai) |
| Native (multi-provider) | `cortices-native` | API key for any supported provider |

## Quick Start

```bash
# 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](https://cortices.io/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.

```bash
# 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

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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](https://cortices.io) to get started.
