neuvikon 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Neuvikon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# neuvikon
+
+Tells [Neuvikon](https://neuvikon.com) 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
+
+```sh
+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 stop` | Stop tracking |
+| `neuvikon status` | Login, project setup, current ticket |
+| `neuvikon logout` | Forget the stored token |
+
+`start` also accepts the ticket on stdin, and pulls the reference out of it:
+
+```sh
+pbpaste | npx neuvikon start
+```
+
+## 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 a hook can report it:
+
+```jsonc
+// .claude/settings.json
+{
+  "hooks": {
+    "Stop": [{ "hooks": [{ "type": "command", "command": "npx neuvikon report" }] }],
+    "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.
+
+## Configuration
+
+| | |
+|---|---|
+| `~/.neuvikon/config.json` | Token and deployment URL, `0600` |
+| `.neuvikon-session` | Which ticket this directory is tracking. Git-ignored by `init` |
+| `NEUVIKON_URL` | Point at a self-hosted deployment. `--url` does the same per command |
+
+## Develop
+
+```sh
+pnpm install
+pnpm build       # tsdown -> dist/index.mjs
+pnpm typecheck
+```
+
+No runtime dependencies, so `npx neuvikon` stays a fast cold start.

package/dist/index.mjs

@@ -0,0 +1,728 @@
+#!/usr/bin/env node
+import { chmodSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { spawn } from "node:child_process";
+//#region src/agents/instructions.ts
+/**
+* The bridge between "user pasted a ticket" and "Neuvikon knows about it".
+*
+* Coding agents don't share a hook system, but they all read a plain-text rules
+* file and they all have a shell. So the instruction is the integration: any
+* agent that can read its own rules can report its own work, and support for a
+* new tool is a filename in TARGETS rather than a new adapter.
+*/
+const START_MARKER = "<!-- neuvikon:start -->";
+const END_MARKER = "<!-- neuvikon:end -->";
+const INSTRUCTION_BODY = `## Neuvikon ticket tracking
+
+When the user hands you a Neuvikon ticket — text beginning with a reference like
+\`EWWQ-1:\` — run this before you start working on it:
+
+    npx neuvikon start --ticket EWWQ-1
+
+When you finish that ticket, or the user moves you to a different one, run:
+
+    npx neuvikon stop
+
+This is bookkeeping that tells the user's team which ticket you are on. You do
+not need to narrate these commands, and if one fails, carry on with the actual
+work — never let it block you.`;
+function instructionBlock() {
+	return `${START_MARKER}\n${INSTRUCTION_BODY}\n${END_MARKER}`;
+}
+/**
+* Replaces an existing block or appends a new one, so re-running `init` after
+* an upgrade refreshes the wording instead of stacking duplicates.
+*/
+function mergeInstructions(existing) {
+	const start = existing.indexOf(START_MARKER);
+	const end = existing.indexOf(END_MARKER);
+	if (start !== -1 && end !== -1 && end > start) {
+		const before = existing.slice(0, start);
+		const after = existing.slice(end + 21);
+		return `${before}${instructionBlock()}${after}`;
+	}
+	return `${existing}${existing.length === 0 ? "" : existing.endsWith("\n") ? "\n" : "\n\n"}${instructionBlock()}\n`;
+}
+function hasInstructions(content) {
+	return content.includes(START_MARKER);
+}
+/** Cursor wants frontmatter, or the rule is never loaded. */
+function cursorRuleFile() {
+	return [
+		"---",
+		"description: Report ticket work to Neuvikon",
+		"alwaysApply: true",
+		"---",
+		"",
+		instructionBlock(),
+		""
+	].join("\n");
+}
+//#endregion
+//#region src/agents/install.ts
+/**
+* Files agents actually read. AGENTS.md is the cross-tool convention and is
+* always written; the rest are only touched when that tool is already set up in
+* the project, so `init` doesn't litter a repo with configs for tools nobody
+* on the team uses.
+*/
+const OPTIONAL_MARKDOWN_TARGETS = ["CLAUDE.md", ".github/copilot-instructions.md"];
+function writeMarkdownTarget(root, relativePath) {
+	const path = join(root, relativePath);
+	const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+	const next = mergeInstructions(existing);
+	if (existing === next) return {
+		path: relativePath,
+		action: "unchanged"
+	};
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, next);
+	return {
+		path: relativePath,
+		action: existing ? "updated" : "created"
+	};
+}
+function writeCursorRule(root) {
+	const relativePath = join(".cursor", "rules", "neuvikon.mdc");
+	const path = join(root, relativePath);
+	const next = cursorRuleFile();
+	const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+	if (existing === next) return {
+		path: relativePath,
+		action: "unchanged"
+	};
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, next);
+	return {
+		path: relativePath,
+		action: existing ? "updated" : "created"
+	};
+}
+/** Keeps the per-directory session file out of the user's commits. */
+function ignoreSessionFile(root) {
+	const path = join(root, ".gitignore");
+	if (!existsSync(join(root, ".git")) && !existsSync(path)) return null;
+	const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+	if (existing.split("\n").some((line) => line.trim() === ".neuvikon-session")) return {
+		path: ".gitignore",
+		action: "unchanged"
+	};
+	const prefix = existing.length === 0 ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+	writeFileSync(path, `${existing}${prefix}# neuvikon CLI session state\n.neuvikon-session\n`);
+	return {
+		path: ".gitignore",
+		action: existing ? "updated" : "created"
+	};
+}
+function installAgentInstructions(root) {
+	const results = [writeMarkdownTarget(root, "AGENTS.md")];
+	for (const target of OPTIONAL_MARKDOWN_TARGETS) {
+		const path = join(root, target);
+		if (existsSync(path)) results.push(writeMarkdownTarget(root, target));
+	}
+	if (existsSync(join(root, ".cursor"))) results.push(writeCursorRule(root));
+	const gitignore = ignoreSessionFile(root);
+	if (gitignore) results.push(gitignore);
+	return results;
+}
+/** Whether this project already carries the instruction, for `status`. */
+function isInstalled(root) {
+	for (const target of [
+		"AGENTS.md",
+		"CLAUDE.md",
+		join(".cursor", "rules", "neuvikon.mdc")
+	]) {
+		const path = join(root, target);
+		if (existsSync(path) && hasInstructions(readFileSync(path, "utf8"))) return true;
+	}
+	return false;
+}
+//#endregion
+//#region src/config.ts
+/**
+* The deployment the CLI talks to. Overridable so self-hosted installs and
+* local Convex dev deployments work without a separate build.
+*
+* MUST point at the production Convex deployment before publishing: every
+* installed copy of this CLI hardcodes whatever ships here, and a dev
+* deployment can be reset out from under them.
+*/
+const DEFAULT_SITE_URL = process.env.NEUVIKON_URL ?? "https://calm-sturgeon-831.eu-west-1.convex.site";
+const CONFIG_DIR = join(homedir(), ".neuvikon");
+const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+function readCredentials() {
+	let raw;
+	try {
+		raw = readFileSync(CONFIG_PATH, "utf8");
+	} catch {
+		return null;
+	}
+	try {
+		const parsed = JSON.parse(raw);
+		if (typeof parsed !== "object" || parsed === null) return null;
+		const { token, url } = parsed;
+		if (typeof token !== "string" || !token) return null;
+		if (typeof url !== "string" || !url) return null;
+		return parsed;
+	} catch {
+		return null;
+	}
+}
+/**
+* A token on disk is only as safe as its permissions, so directory and file are
+* locked to the owner on every write, not just on first create — an earlier
+* version may have left them readable.
+*/
+function writeCredentials(credentials) {
+	mkdirSync(CONFIG_DIR, {
+		recursive: true,
+		mode: 448
+	});
+	chmodSync(CONFIG_DIR, 448);
+	writeFileSync(CONFIG_PATH, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 384 });
+	chmodSync(CONFIG_PATH, 384);
+}
+function clearCredentials() {
+	try {
+		rmSync(CONFIG_PATH);
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/ui.ts
+/**
+* Output helpers. Everything the agent shouldn't parse goes to stderr, so a
+* command's stdout stays a clean, pipeable value.
+*/
+const useColor = process.env.NO_COLOR === void 0 && process.stderr.isTTY === true;
+function paint(code, text) {
+	return useColor ? `\x1b[${code}m${text}\x1b[0m` : text;
+}
+const dim = (text) => paint("2", text);
+const bold = (text) => paint("1", text);
+const green = (text) => paint("32", text);
+const red = (text) => paint("31", text);
+const cyan = (text) => paint("36", text);
+function info(message) {
+	process.stderr.write(`${message}\n`);
+}
+function success(message) {
+	process.stderr.write(`${green("✓")} ${message}\n`);
+}
+function warn(message) {
+	process.stderr.write(`${red("!")} ${message}\n`);
+}
+/** Ends the process. Every user-facing failure funnels through here. */
+function fail(message, hint) {
+	process.stderr.write(`${red("✗")} ${message}\n`);
+	if (hint) process.stderr.write(`  ${dim(hint)}\n`);
+	process.exit(1);
+}
+//#endregion
+//#region src/commands/init.ts
+/**
+* Separate from `login` because instructions are per-project and credentials
+* are per-machine: a second checkout needs this, not another login.
+*/
+function init() {
+	const results = installAgentInstructions(process.cwd());
+	for (const result of results) if (result.action === "unchanged") info(dim(`  ${result.path} — already up to date`));
+	else success(`${result.path} — ${result.action}`);
+	if (!readCredentials()) warn("Not logged in yet — run `npx neuvikon login`.");
+}
+//#endregion
+//#region src/api.ts
+var ApiError = class extends Error {
+	status;
+	constructor(message, status) {
+		super(message);
+		this.status = status;
+		this.name = "ApiError";
+	}
+};
+/** A request that never reached the server: offline, DNS, TLS, timeout. */
+var NetworkError = class extends Error {
+	constructor(cause) {
+		super("Could not reach Neuvikon", { cause });
+		this.name = "NetworkError";
+	}
+};
+const TIMEOUT_MS = 15e3;
+/**
+* The one place an HTTP failure becomes a typed error. Callers decide what a
+* failure means — a hook wrapping the agent's turn wants to swallow it, `login`
+* wants to shout about it.
+*/
+async function post(url, path, body) {
+	let response;
+	try {
+		response = await fetch(`${url}${path}`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify(body),
+			signal: AbortSignal.timeout(TIMEOUT_MS)
+		});
+	} catch (error) {
+		throw new NetworkError(error);
+	}
+	const payload = await response.json().catch(() => ({}));
+	const error = typeof payload === "object" && payload !== null ? payload.error : void 0;
+	if (!response.ok) throw new ApiError(typeof error === "string" ? error : `Request failed with status ${response.status}`, response.status);
+	return payload;
+}
+function normalizeUrl(url) {
+	return url.trim().replace(/\/+$/, "");
+}
+//#endregion
+//#region src/browser.ts
+/**
+* Best-effort. The URL is always printed too, so a headless box, an SSH session
+* or a locked-down desktop degrades to "copy this link" instead of failing.
+*/
+function openBrowser(url) {
+	const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+	try {
+		const child = spawn(command, [url], {
+			stdio: "ignore",
+			detached: true,
+			shell: process.platform === "win32"
+		});
+		child.on("error", () => {});
+		child.unref();
+	} catch {}
+}
+//#endregion
+//#region src/commands/login.ts
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function login(flags) {
+	const url = normalizeUrl(flags.get("url") ?? DEFAULT_SITE_URL);
+	let start;
+	try {
+		start = await post(url, "/api/cli/auth/start", {});
+	} catch (error) {
+		if (error instanceof NetworkError) fail(`Could not reach ${url}`, "Check your connection.");
+		if (error instanceof ApiError) fail(error.message);
+		throw error;
+	}
+	info("");
+	info(`  Open ${cyan(start.verifyUrl)}`);
+	info(`  and confirm this code: ${bold(start.userCode)}`);
+	info("");
+	info(dim("  Waiting for approval..."));
+	openBrowser(start.verifyUrl);
+	const interval = Math.max(1e3, start.intervalMs);
+	for (;;) {
+		if (Date.now() > start.expiresAt) fail("That login request expired.", "Run `npx neuvikon login` to get a fresh code.");
+		await sleep(interval);
+		let result;
+		try {
+			result = await post(url, "/api/cli/auth/poll", { deviceCode: start.deviceCode });
+		} catch (error) {
+			if (error instanceof NetworkError) continue;
+			if (error instanceof ApiError && error.status === 429) continue;
+			if (error instanceof ApiError) fail(error.message);
+			throw error;
+		}
+		if (result.status === "pending") continue;
+		if (result.status === "denied") fail("Login was denied in the browser.");
+		if (result.status === "expired") fail("That login request expired.", "Run `npx neuvikon login` to get a fresh code.");
+		writeCredentials({
+			token: result.token,
+			url,
+			userName: result.userName,
+			organizationName: result.organizationName
+		});
+		info("");
+		success(`Logged in as ${bold(result.userName)} · ${result.organizationName}`);
+		info(dim(`  Token stored in ${CONFIG_PATH}`));
+		const touched = installAgentInstructions(process.cwd()).filter((entry) => entry.action !== "unchanged");
+		if (touched.length > 0) success(`Told your coding agent how to report work (${touched.map((e) => e.path).join(", ")})`);
+		else success("Your coding agent already knows how to report work");
+		info("");
+		info(dim("  Paste a ticket into any coding agent and it will do the rest."));
+		return;
+	}
+}
+//#endregion
+//#region src/commands/logout.ts
+function logout() {
+	if (clearCredentials()) {
+		success("Logged out.");
+		return;
+	}
+	info("You were not logged in.");
+}
+//#endregion
+//#region src/session.ts
+/**
+* Scoped to the working directory rather than the machine: two checkouts driven
+* in parallel are two sessions, which is what running two agents means.
+*/
+function sessionPath() {
+	return join(process.cwd(), ".neuvikon-session");
+}
+function readSession() {
+	let raw;
+	try {
+		raw = readFileSync(sessionPath(), "utf8");
+	} catch {
+		return null;
+	}
+	try {
+		const parsed = JSON.parse(raw);
+		if (typeof parsed !== "object" || parsed === null) return null;
+		const { sessionKey, ticket } = parsed;
+		if (typeof sessionKey !== "string" || typeof ticket !== "string") return null;
+		return parsed;
+	} catch {
+		return null;
+	}
+}
+function writeSession(session) {
+	writeFileSync(sessionPath(), `${JSON.stringify(session, null, 2)}\n`);
+}
+function clearSession() {
+	try {
+		rmSync(sessionPath());
+	} catch {}
+}
+//#endregion
+//#region src/ticket.ts
+/**
+* Ticket refs look like `AWKN-14`. This pattern is deliberately looser than the
+* server's — it pulls *candidates* out of arbitrary pasted prose and lets the
+* server decide which one is a real ticket in the caller's organization, so the
+* authoritative rule lives in exactly one place.
+*/
+const CANDIDATE = /\b([A-Z0-9]{2,8})-(\d{1,9})\b/g;
+/** Every distinct ref-shaped token in `text`, in the order it appears. */
+function extractTicketRefs(text) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const match of text.toUpperCase().matchAll(CANDIDATE)) {
+		if (/^\d+$/.test(match[1])) continue;
+		seen.add(`${match[1]}-${match[2]}`);
+	}
+	return [...seen];
+}
+/** Reads piped input, if any. Returns "" when stdin is a terminal. */
+async function readStdin() {
+	if (process.stdin.isTTY) return "";
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(chunk);
+	return Buffer.concat(chunks).toString("utf8");
+}
+//#endregion
+//#region src/usage.ts
+/**
+* Sums token usage out of a JSONL agent transcript, starting from `offset`.
+*
+* Reading incrementally is what makes a per-turn hook safe to call repeatedly:
+* each call reports only what was appended since the last one. Anything that
+* doesn't parse is skipped rather than fatal — a transcript being appended to
+* while we read it will have a torn final line, and that is normal, not an
+* error worth failing a user's turn over.
+*/
+function readUsageSince(path, offset) {
+	let fd;
+	try {
+		fd = openSync(path, "r");
+	} catch {
+		return null;
+	}
+	try {
+		const size = fstatSync(fd).size;
+		const from = offset > size ? 0 : offset;
+		if (size === from) return {
+			tokensIn: 0,
+			tokensOut: 0,
+			offset: size
+		};
+		const buffer = Buffer.alloc(size - from);
+		readSync(fd, buffer, 0, buffer.length, from);
+		const text = buffer.toString("utf8");
+		const lastNewline = text.lastIndexOf("\n");
+		if (lastNewline === -1) return {
+			tokensIn: 0,
+			tokensOut: 0,
+			offset: from
+		};
+		let tokensIn = 0;
+		let tokensOut = 0;
+		for (const line of text.slice(0, lastNewline).split("\n")) {
+			if (!line.trim()) continue;
+			let row;
+			try {
+				row = JSON.parse(line);
+			} catch {
+				continue;
+			}
+			const usage = extractUsage(row);
+			if (!usage) continue;
+			tokensIn += usage.tokensIn;
+			tokensOut += usage.tokensOut;
+		}
+		return {
+			tokensIn,
+			tokensOut,
+			offset: from + Buffer.byteLength(text.slice(0, lastNewline + 1))
+		};
+	} catch {
+		return null;
+	} finally {
+		closeSync(fd);
+	}
+}
+function toCount$1(value) {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+function extractUsage(row) {
+	if (typeof row !== "object" || row === null) return null;
+	const message = row.message;
+	if (typeof message !== "object" || message === null) return null;
+	const usage = message.usage;
+	if (typeof usage !== "object" || usage === null) return null;
+	const fields = usage;
+	return {
+		tokensIn: toCount$1(fields.input_tokens) + toCount$1(fields.cache_read_input_tokens) + toCount$1(fields.cache_creation_input_tokens),
+		tokensOut: toCount$1(fields.output_tokens)
+	};
+}
+//#endregion
+//#region src/commands/report.ts
+/**
+* Agent hooks hand their context to the command on stdin as JSON. Reading the
+* transcript path from there means a hook is a bare `npx neuvikon report` with
+* nothing to wire up, and nothing to keep in sync when a tool renames a flag.
+*/
+async function transcriptFromHookPayload() {
+	const raw = await readStdin();
+	if (!raw.trim()) return void 0;
+	try {
+		const payload = JSON.parse(raw);
+		if (typeof payload !== "object" || payload === null) return void 0;
+		const path = payload.transcript_path;
+		return typeof path === "string" && path ? path : void 0;
+	} catch {
+		return;
+	}
+}
+function toCount(raw) {
+	if (raw === void 0) return void 0;
+	const value = Number(raw);
+	return Number.isFinite(value) && value >= 0 ? value : void 0;
+}
+/**
+* Called from an agent hook on every turn, so it is deliberately silent and
+* never exits non-zero: a token count is not worth interrupting someone's work
+* over, and a hook that fails loudly is a hook people uninstall.
+*/
+async function report(flags) {
+	const credentials = readCredentials();
+	const session = readSession();
+	if (!credentials || !session) {
+		if (flags.has("verbose")) info(dim(credentials ? "No ticket is being tracked here." : "Not logged in."));
+		return;
+	}
+	let tokensIn = toCount(flags.get("tokens-in"));
+	let tokensOut = toCount(flags.get("tokens-out"));
+	let nextOffset;
+	const transcript = flags.get("transcript") || await transcriptFromHookPayload();
+	if (transcript) {
+		const usage = readUsageSince(transcript, session.transcriptOffset ?? 0);
+		if (usage) {
+			tokensIn = (tokensIn ?? 0) + usage.tokensIn;
+			tokensOut = (tokensOut ?? 0) + usage.tokensOut;
+			nextOffset = usage.offset;
+		}
+	}
+	if (!tokensIn && !tokensOut) {
+		if (flags.has("verbose")) info(dim("No new usage to report."));
+		return;
+	}
+	try {
+		await post(credentials.url, "/api/agent/events", {
+			token: credentials.token,
+			event: "report",
+			sessionKey: session.sessionKey,
+			tokensIn,
+			tokensOut
+		});
+	} catch {
+		return;
+	}
+	if (nextOffset !== void 0) writeSession({
+		...session,
+		transcriptOffset: nextOffset
+	});
+	if (flags.has("verbose")) info(dim(`Reported ${tokensIn ?? 0} in / ${tokensOut ?? 0} out`));
+}
+//#endregion
+//#region src/commands/start.ts
+const TOOLS = /* @__PURE__ */ new Set([
+	"claude-code",
+	"codex",
+	"cursor",
+	"other"
+]);
+async function resolveRef(flags, positional) {
+	const explicit = flags.get("ticket") ?? positional[0];
+	if (explicit) {
+		const [ref] = extractTicketRefs(explicit);
+		if (!ref) fail(`"${explicit}" is not a ticket reference.`, "Expected something like EWWQ-1.");
+		return ref;
+	}
+	const refs = extractTicketRefs(await readStdin());
+	if (refs.length === 0) fail("No ticket reference found.", "Pass one with --ticket EWWQ-1, or pipe the ticket text in.");
+	return refs[0];
+}
+async function start(flags, positional) {
+	const credentials = readCredentials();
+	if (!credentials) fail("Not logged in.", "Run `npx neuvikon login` first.");
+	const ref = await resolveRef(flags, positional);
+	const tool = flags.get("tool") ?? "other";
+	if (!TOOLS.has(tool)) fail(`Unknown tool "${tool}".`, `Expected one of: ${[...TOOLS].join(", ")}.`);
+	const existing = readSession();
+	if (existing?.ticket === ref) {
+		info(dim(`Already tracking ${ref}.`));
+		return;
+	}
+	let result;
+	try {
+		result = await post(credentials.url, "/api/agent/events", {
+			token: credentials.token,
+			event: "start",
+			ticketRef: ref,
+			tool
+		});
+	} catch (error) {
+		if (error instanceof NetworkError) fail("Could not reach Neuvikon.");
+		if (error instanceof ApiError) {
+			if (error.status === 401) fail(error.message, "Run `npx neuvikon login` again.");
+			fail(error.message);
+		}
+		throw error;
+	}
+	if (existing) await post(credentials.url, "/api/agent/events", {
+		token: credentials.token,
+		event: "stop",
+		sessionKey: existing.sessionKey
+	}).catch(() => void 0);
+	writeSession({
+		sessionKey: result.sessionKey,
+		ticket: ref,
+		startedAt: Date.now()
+	});
+	success(`Tracking work on ${bold(ref)}`);
+}
+//#endregion
+//#region src/commands/status.ts
+function status() {
+	const credentials = readCredentials();
+	const session = readSession();
+	info("");
+	if (credentials) {
+		const who = credentials.userName ?? "unknown user";
+		const org = credentials.organizationName ?? credentials.url;
+		info(`  Logged in   ${bold(who)} ${dim(`· ${org}`)}`);
+	} else info(`  Logged in   ${dim("no — run `npx neuvikon login`")}`);
+	info(`  This repo   ${isInstalled(process.cwd()) ? "agent instructions installed" : dim("not set up — run `npx neuvikon init`")}`);
+	if (session) {
+		const minutes = Math.round((Date.now() - session.startedAt) / 6e4);
+		info(`  Tracking    ${bold(session.ticket)} ${dim(`· started ${minutes}m ago`)}`);
+	} else info(`  Tracking    ${dim("nothing right now")}`);
+	info("");
+}
+//#endregion
+//#region src/commands/stop.ts
+async function stop() {
+	const session = readSession();
+	if (!session) {
+		info(dim("No ticket is being tracked here."));
+		return;
+	}
+	const credentials = readCredentials();
+	if (credentials) await post(credentials.url, "/api/agent/events", {
+		token: credentials.token,
+		event: "stop",
+		sessionKey: session.sessionKey
+	}).catch(() => void 0);
+	clearSession();
+	success(`Stopped tracking ${session.ticket}`);
+}
+//#endregion
+//#region src/index.ts
+const HELP = `${bold("neuvikon")} — tell Neuvikon which ticket your coding agent is on
+
+${bold("Usage")}
+  npx neuvikon login              Sign in through the browser
+  npx neuvikon init               Teach this project's coding agents to report work
+  npx neuvikon start --ticket EWWQ-1
+  npx neuvikon stop
+  npx neuvikon status             Show login, project setup and current ticket
+  npx neuvikon logout
+
+${bold("Options")}
+  --tool <name>                   claude-code | codex | cursor | other
+  --transcript <path>             Read token usage from an agent transcript
+  --tokens-in <n> --tokens-out <n>
+  --url <site-url>                Point at a self-hosted deployment
+
+${dim("Paste a ticket into any coding agent after logging in — it takes it from there.")}`;
+/**
+* Flags are `--name value`, or bare `--name` for a switch. Kept hand-rolled so
+* the package has no runtime dependencies and `npx neuvikon` stays instant.
+*/
+function parseArgs(argv) {
+	const flags = /* @__PURE__ */ new Map();
+	const positional = [];
+	for (let index = 0; index < argv.length; index++) {
+		const arg = argv[index];
+		if (!arg.startsWith("--")) {
+			positional.push(arg);
+			continue;
+		}
+		const name = arg.slice(2);
+		const next = argv[index + 1];
+		if (next === void 0 || next.startsWith("--")) {
+			flags.set(name, "");
+			continue;
+		}
+		flags.set(name, next);
+		index++;
+	}
+	return {
+		flags,
+		positional
+	};
+}
+async function main() {
+	const [command, ...rest] = process.argv.slice(2);
+	const { flags, positional } = parseArgs(rest);
+	switch (command) {
+		case "login": return login(flags);
+		case "logout": return logout();
+		case "init": return init();
+		case "start": return start(flags, positional);
+		case "report": return report(flags);
+		case "stop": return stop();
+		case "status": return status();
+		case void 0:
+		case "help":
+		case "--help":
+		case "-h":
+			info(HELP);
+			return;
+		default: fail(`Unknown command "${command}".`, "Run `npx neuvikon help` to see what's available.");
+	}
+}
+main().catch((error) => {
+	fail(error instanceof Error ? error.message : "Something went wrong.");
+});
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "neuvikon",
+  "version": "0.1.0",
+  "description": "Tell Neuvikon which ticket your coding agent is working on.",
+  "keywords": [
+    "neuvikon",
+    "cli",
+    "ai-agent",
+    "kanban",
+    "ticket"
+  ],
+  "homepage": "https://neuvikon.com",
+  "author": "Neuvikon <neuvikon@gmail.com>",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "neuvikon": "dist/index.mjs"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm run typecheck && pnpm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2"
+  }
+}