Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (arcanova-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

◈ 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

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
`/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