◈ Arcanova CLI

AI-powered project management for coding agents.

npx arcanova-cli@latest

Works on Mac, Windows, and Linux.

Supports Claude Code, GitHub Copilot, Cursor, Gemini CLI, OpenAI Codex, and Qwen Code.

Website · Docs · GitHub

What Is This?

Arcanova CLI connects your AI coding agent to Arcanova — a project management platform with an encrypted secrets vault, Kanban boards, and real-time SSE updates.

Your agent picks tasks from the board, researches context, writes code, documents the work, and moves on to the next task. Autonomously.

PICK → RESEARCH → EXECUTE → DOCUMENT → COMPLETE → REPEAT

Quick Start

1. Create an Arcanova account

Sign up at arcanova.online with GitHub or Google. Free tier available.

2. Create an API token

Go to Settings > API Tokens → New Token → copy it.

3. Install

npx arcanova-cli@latest

You'll be asked for your API token and server URL. The installer writes config files for your AI agent automatically.

4. Use it

In Claude Code:

/arcanova:project my-project       # bind this directory to a project
/arcanova:status                    # see the board (with optional filters)
/arcanova:pick                      # auto-select the next unblocked task
/arcanova:autopilot                 # full autonomous cycle
/arcanova:autopilot --dry-run       # preview the plan without touching the board
/arcanova:help                      # categorised reference of every command

In other agents (Copilot, Cursor, Gemini, Codex, Qwen): the agent reads its config file and follows the workflow using curl commands.

Supported Agents

| Agent | Config File | Commands | |-------|-------------|----------| | Claude Code | CLAUDE.md + .claude/commands/ | /arcanova:* slash commands | | OpenAI Codex | AGENTS.md + ~/.codex/skills/ | $arcanova-* skill commands | | GitHub Copilot | .github/copilot-instructions.md | Workflow via config | | Cursor | .cursorrules | Workflow via config | | Gemini CLI | GEMINI.md | Workflow via config | | Qwen Code | QWEN.md | Workflow via config |

Claude Code gets /arcanova:* slash commands. Codex gets $arcanova-* skill commands. All other agents get the full Autopilot workflow with curl commands in their config file.

Slash Commands (Claude Code)

Account + project

| Command | Description | |---------|-------------| | /arcanova:connect [token] | Set or switch your Arcanova API token (account-level — persists to your shell profile). | | /arcanova:project [slug] | Switch the current directory to a project. Without arg, lists projects and you pick. Writes project_id to .arcanova + auto-adds .arcanova to .gitignore. |

Task workflow

| Command | Description | |---------|-------------| | /arcanova:status [--mine] [--blocked] [--review] [--feature=X] [--label=X] [--priority=P] | Show board state with optional filters (combinable as AND). Header shows active filter set + X-of-Y totals. | | /arcanova:pick [id] | Pick highest priority unblocked task | | /arcanova:task [id] | Read task details (research phase) | | /arcanova:done | Complete task + append Session Log + auto-commit (no Co-Authored-By) + pick next | | /arcanova:review | Move task to review | | /arcanova:block "reason" | Block task with reason | | /arcanova:comment "msg" | Post markdown comment on task | | /arcanova:note "title" | Create documentation note | | /arcanova:spec | Read full project spec | | /arcanova:issue "create title" | Create or read issues | | /arcanova:files [list \| read \| info \| download] | Read-only access to the project's Files tab (uploaded reference docs, scan reports, etc.) |

Git + PR

| Command | Description | |---------|-------------| | /arcanova:branch [task-id] [--push] | Create + check out arc/<task-id-short>-<slug> for the current task. Optional --push sets upstream. | | /arcanova:pr [task-id] [--draft] | Open a GitHub PR with body auto-composed from the task description + research brief + completion comment. Posts a back-link comment on the task. Requires gh CLI authenticated. |

Operations

| Command | Description | |---------|-------------| | /arcanova:logs [tail \| errors \| since <dur>] [service] [--prod] | Tail/grep docker-compose logs without reinventing flags. Service auto-detected. --prod targets the prod compose project. | | /arcanova:help [command] | Categorised reference of every Arcanova slash command. With arg: full description for that one command. |

AI memory (cross-device context)

| Command | Description | |---------|-------------| | /arcanova:map | Scan the codebase, write 📐 Architecture Map into the project's Memory folder. | | /arcanova:gap [area] | Code audit — scan for weaknesses (security / tests / performance / tech-debt / a11y; default: top 10), write 🔍 Improvement Plan, auto-create improvement tasks. | | /arcanova:intel [refresh|query <term>|status|diff] | Maintained queryable codebase index — symbol → file lookup, exports/imports, routes, change detection. Sibling to map: map is the human narrative, intel is the machine-queryable backing data. | | /arcanova:resume | Cross-device session briefing — pulls Memory folder + open tasks + recent activity + active seeds, prints a one-screen summary. | | /arcanova:sync | Pull Memory folder notes → .ai/memory/*.md so any AI agent (Claude / Codex / Cursor / Gemini / Qwen) reads them automatically on session start. Pull-only (Phase 1); local edits are clobbered on next sync. | | /arcanova:plant-seed "<idea>" | Park a forward-looking idea with trigger conditions. Surfaces in /arcanova:resume only when conditions are met (e.g. "when feature X ships"). | | /arcanova:session-report [--detailed] | Stakeholder-ready summary of the session (default ~150 words). --detailed for engineer detail (~500 words with file paths + commit SHAs). |

Autonomous

| Command | Description | |---------|-------------| | /arcanova:autopilot | Full autonomous cycle — auto-detects parallelizable work, dispatches sub-agents in worktrees when supported (Claude Code), runs serially otherwise. Profiles: budget / balanced (default) / quality via .arcanova or --profile=<x>. | | /arcanova:autopilot --supervised | Same cycle but pauses after research for approval. | | /arcanova:autopilot --dry-run | Preview the plan: runs PICK + RESEARCH for up to 3 candidates and prints briefs locally without touching the board, codebase, or comments. |

Safety Hooks (PreToolUse)

The installer registers four PreToolUse hooks in .claude/settings.json. They're defense-in-depth — the agent's system-prompt rules already cover most of these, but a hook is deterministic. All opt out via ARCANOVA_HOOKS_OFF=1.

| Hook | Triggers on | What it blocks | |------|-------------|----------------| | read-before-edit | Edit/Write/Read | Edit/Write on a file the agent hasn't Read first this session — prevents the "infinite retry" loop after compaction. | | bash-confirm-dangerous | Bash | 16 categories of destructive shell: rm -rf on root/home/sysdir, git push --force to main/master, git reset --hard, git rebase -i, --no-verify, --no-gpg-sign, npm/pnpm/yarn publish, SQL DROP/TRUNCATE, prisma migrate reset, dd if=, mkfs.*, chmod 777 /, fork bomb. | | secret-scan | Edit/Write | New content containing real-looking credentials: GitHub PATs, OpenAI/Anthropic keys, Arcanova PATs, Stripe/PayMongo webhook secrets, Slack/AWS/Google keys, JWTs, PEM private keys. Placeholder allowlist (example, <YOUR_KEY>, xxxx...) prevents false positives. | | compose-port-check | Edit/Write on docker-compose*.yml | Port mappings without an explicit 127.0.0.1: (or [::1]:) host bind. Catches 0.0.0.0:6379:6379 and the implicit 6379:6379 — both publicly reachable through Docker's iptables manipulation. Annotation # arcanova:public whitelists specific lines. |

Autopilot Workflow

┌─────────────────────────────────────────────┐
│            /arcanova:autopilot              │
├─────────────────────────────────────────────┤
│                                             │
│  1. PICK                                    │
│     Auto-select highest priority task       │
│     Move to IN_PROGRESS                     │
│                                             │
│  2. RESEARCH                                │
│     Read task + feature + notes + comments  │
│     Explore codebase for patterns           │
│     Post research brief as comment          │
│                                             │
│  3. EXECUTE                                 │
│     Write code following research plan      │
│     On failure → create issue, move to      │
│     REVIEW, continue to next task           │
│                                             │
│  4. DOCUMENT (mandatory)                    │
│     Post completion comment                 │
│     Create documentation note               │
│                                             │
│  5. COMPLETE                                │
│     Mark DONE → pick next → repeat          │
│                                             │
│  6. EXIT                                    │
│     No tasks left → session summary note    │
│                                             │
└─────────────────────────────────────────────┘

Supervised Mode

/arcanova:autopilot --supervised

Pauses after the research phase so you can approve the plan before the agent writes code.

Multi-Agent

Multiple agents can work on the same project simultaneously:

• Each agent gets its own API token
• Tasks are auto-assigned when picked — other agents skip them
• Dependencies prevent agents from starting blocked work
• Real-time SSE keeps boards synchronized
• Comments serve as inter-agent communication

Features

• Real-time boards — SSE-powered, cards move instantly
• Task dependencies — depends on / blocked by
• Encrypted secrets vault — AES-256-GCM
• AI spec analyzer — paste a spec, AI generates features + tasks
• File attachments — with inline preview (images, PDF, DOCX, code)
• Markdown comments — with @mention notifications
• GitHub-style rendering — syntax-highlighted code blocks
• 5 AI providers — Gemini, Claude, OpenAI, Grok, Qwen (BYO keys)

Options

# Install globally (all projects)
npx arcanova-cli@latest --global

# Uninstall
npx arcanova-cli@latest --uninstall

# Refresh commands + hooks without re-prompting for the token
# (shows a sha256 diff so you can see what changed)
npx arcanova-cli@latest --upgrade

# Diagnose: token validity, server reach, hooks registered, gh CLI present, etc.
npx arcanova-cli@latest --health

Self-hosting or custom endpoint

The installer defaults to the hosted service at https://arcanova.online. If you run a self-hosted Arcanova instance or point at a dev server, export ARCANOVA_URL before running the installer — it won't ask, but it'll use your value and record it:

ARCANOVA_URL=https://arcanova.mycompany.com npx arcanova-cli@latest
# or for local dev:
ARCANOVA_URL=http://localhost:3000 npx arcanova-cli@latest

The slash commands also read ARCANOVA_URL from the environment at runtime, so you can override per-shell without reinstalling.

API

All endpoints accept Bearer token auth:

curl -H "Authorization: Bearer arc_your_token" https://arcanova.online/api/projects

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/projects | List projects | | GET | /api/projects/{id}/ai/context | Full project context | | GET | /api/projects/{id}/ai/context?taskId=X | Task context | | GET | /api/projects/{id}/events | SSE real-time stream | | PATCH | /api/projects/{id}/tasks/{id} | Update task | | POST | /api/projects/{id}/comments | Post comment | | POST | /api/projects/{id}/notes | Create note | | POST | /api/projects/{id}/issues | Create issue |

Full API docs at arcanova.online/docs.

License

MIT

Built by kupzsensei

arcanova.online