neuvikon

Tells Neuvikon which ticket your coding agent is working on, and how many tokens it spent doing it.

Works with any agent that reads a rules file and has a shell — Claude Code, Cursor, Codex, Copilot, opencode — because the integration is the rules file.

Use

npx neuvikon login

A browser opens, you approve, and the CLI writes its instructions into the project's agent rules (AGENTS.md, plus CLAUDE.md / .cursor/rules/ when the project already uses them).

After that, paste a ticket into whichever agent you like:

EWWQ-1: Fix the invite expiry
Type: Bug
Priority: High
...

The agent reads its rules, sees the EWWQ-1 reference, and runs npx neuvikon start --ticket EWWQ-1 before it begins. Neuvikon shows the ticket as being worked on, by whom, with which tool.

Commands

| | | |---|---| | neuvikon login | Sign in through the browser and set up the current project | | neuvikon init | Set up another project (credentials are per-machine, rules are per-project) | | neuvikon start --ticket EWWQ-1 | Begin tracking. --tool claude-code\|codex\|cursor\|other | | neuvikon start --tickets EWWQ-1,EWWQ-2 --spawn | Open one terminal per ticket instead of tracking one here | | neuvikon stop | Stop tracking | | neuvikon status | Login, project setup, current ticket | | neuvikon logout | Revoke this machine's token and forget it | | neuvikon pages [--ticket EWWQ-1] | List the ticket's project pages, flattened to plain text | | neuvikon pages update "Title" [--ticket EWWQ-1] | Create or update a page by title, body on stdin (or --text) | | neuvikon create "Title" [--ticket EWWQ-1] | File something you noticed as a new ticket, same project | | neuvikon create "Title" --sub [--ticket EWWQ-1] | ...or as a sub-ticket of the ticket you're on | | neuvikon create "Title" --parent NS-12 | ...or of a different ticket entirely |

start also accepts the ticket on stdin, and pulls the reference out of it:

pbpaste | npx neuvikon start

Kicking off several tickets at once

npx neuvikon start --tickets EWWQ-1,EWWQ-2,EWWQ-3 --spawn

If Herdr is installed, every ticket in the batch lands as its own tab in one Herdr workspace instead of separate OS windows — Herdr's own UI then shows each agent's live working/blocked/done state. Run it from inside a Herdr-managed pane and the batch adds its tabs to that same workspace instead of opening a new one. Otherwise it opens one terminal per ticket the usual way (a tmux window if you're already in tmux, an iTerm2 or Terminal.app tab on macOS, a Windows Terminal tab on Windows), each cd'd into this directory. Either way, if a coding agent CLI is installed (Claude Code, Cursor, Codex) it's launched with that ticket's full text as its first prompt — same substance a manual paste would give it. With more than one installed, you're asked once which to use and that choice is remembered (--agent <name> overrides it any time). Nothing is tracked automatically, even then: a session only scopes safely once an agent is actually running, so the launched agent runs npx neuvikon start --ticket EWWQ-1 itself once it's up, via its rules file, same as a manual paste always has. Without a detected agent, or on a platform/terminal this can't drive, it just prints the ticket ref and that command for you to paste by hand.

Filing what you notice along the way

Working a ticket turns up other things — a bug, a chunk of related work that doesn't belong in the same diff. Rather than silently expanding scope or silently dropping it, an agent can file it as its own ticket:

npx neuvikon create "Invite emails aren't localized" --ticket EWWQ-1

Or as a sub-ticket, if it's really part of finishing the one you're on:

npx neuvikon create "Add French copy" --sub --ticket EWWQ-1

--parent NS-12 files it under a different ticket instead. Sub-tickets are one level deep — a ticket that's already a sub-ticket can't take --sub itself, same restriction the app's own "+ sub-ticket" control has. Either way the ticket you were on gets an automated comment pointing at the new one, so nothing gets filed invisibly.

Project pages

An agent's most useful output often isn't the ticket, it's what it learned doing it. pages reads and writes the same project pages a person sees in the app — the running knowledge base for that project, not a per-ticket scratchpad:

npx neuvikon pages --ticket EWWQ-1

npx neuvikon pages update "Auth flow" --ticket EWWQ-1 <<'EOF'
Sessions are issued by convex/auth.ts and expire after 30 days.
See [[Session storage]] for where they're persisted.
EOF

An update matches an existing page by title (case-insensitive) and overwrites it, so writing to the same title again refines that page instead of piling up duplicates. [[Another Title]] inside the text becomes a real link to that page if a page with that title already exists in the project, same as typing it in the editor.

Both commands fall back to whichever ticket npx neuvikon start is already tracking in this directory when --ticket is omitted.

Token usage

start/stop are all an agent can report about itself — no agent knows its own token count. On Claude Code the transcript does, so login/init wire a hook into .claude/settings.json for you, whenever that project already has one:

// .claude/settings.json
{
  "hooks": {
    "Stop": [{ "hooks": [{ "type": "command", "command": "npx neuvikon report" }] }],
    "Notification": [
      { "hooks": [{ "type": "command", "command": "npx neuvikon report --heartbeat" }] }
    ],
    "SessionEnd": [{ "hooks": [{ "type": "command", "command": "npx neuvikon stop" }] }]
  }
}

report reads only what was appended since the last call, so firing it every turn adds that turn rather than re-counting the conversation. It is silent and always exits 0 — a token count is never worth interrupting someone's work.

Notification fires when Claude Code is blocked mid-turn — a permission prompt, a question, waiting on you — exactly when Stop doesn't fire yet. The --heartbeat flag tells report to still check in even when there's no new token usage to send, so a session that's genuinely just waiting on you doesn't read as stopped on the board.

If .claude/settings.json doesn't exist yet, or another agent is the one being used, add the block above by hand.

Configuration

| | | |---|---| | ~/.neuvikon/config.json | Token and deployment URL, 0600 | | .neuvikon-session[.<id>] | Which ticket this directory (or, under Claude Code, this agent) is tracking. Git-ignored by init | | --dev | Target the development deployment instead of production | | NEUVIKON_URL | Point at a self-hosted deployment. --url does the same per command | | NEUVIKON_TOKEN | Use this token instead of logging in — for CI and anywhere a browser cannot open |

Develop

pnpm install
pnpm build       # tsdown -> dist/index.mjs
pnpm typecheck

No runtime dependencies, so npx neuvikon stays a fast cold start.