@cortices/agent 0.3.7 → 0.3.9

package/README.md

@@ -1,26 +1,131 @@
 # @cortices/agent
 
-Connect your AI coding agents to [Cortices](https://cortices.io) — a real-time dashboard to monitor, chat with, and orchestrate Claude Code and OpenAI Codex agents from anywhere.
+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
+# 1. Sign up at https://cortices.io and create an API key (Settings → API Keys)
 
-# 2. Connect your agent
+# 2. Run your agent
 npx @cortices/agent --api-key ck_your_key_here
 ```
 
-Your agent will appear in your [dashboard](https://cortices.io/dashboard) instantly.
+Your agent appears in your [dashboard](https://cortices.io/dashboard) instantly.
 
 ## Options
 
 ```
-  --dir DIR        Working directory (default: current directory)
-  --name NAME      Agent name shown in dashboard
-  --api-key KEY    Your Cortices API key (required)
+--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.