Spike CLI

Disposable session boards for humans and coding agents. Manage tickets, links, tags, questions, reviews, and progress from Claude Code, Codex, or any environment that can run a command and reach your board over HTTP.

Run

Requires Node.js 22+ (or a compatible Bun runtime).

npx --yes @ai-aid/[email protected] guide
bunx @ai-aid/[email protected] guide

# Or install once:
npm install -g @ai-aid/[email protected]
spike guide

The executable is named spike. The default service is https://spike.jlort.com. Use --origin when creating a board on another deployment.

spike board create --title 'Implement authentication' --json
export SPIKE_BOARD='https://spike.jlort.com/b/TOKEN_FROM_CREATE'
export SPIKE_ACTOR='coordinator'
spike guide coordinator
spike ticket create --title 'Implement login' --tag backend

The board URL grants access. Names provide attribution; everyone with the link can edit. New boards always register coordinator. Each worker registers a unique name with spike board join --name worker-fox and sets SPIKE_ACTOR to it. The coordinator assigns work through a handshake. Names enforce workflow conventions, not identity or permissions.

Learn as you work

spike guide worker
spike guide reviewer
spike guide waiting
spike guide all --json
spike ticket assign --help

Guides teach joining, accepting assignments, progress and expiry, review handoffs, returning to wait after each ticket, and stopping only when dismissed. Agents are instructed to rename sessions to [ID] ticket title, attach a real session URL if available, and schedule meaningful updates every 10 minutes using their harness. Short leases need more frequent updates. Unsupported capabilities are skipped honestly; Spike does not itself rename sessions or create schedules.

Common operations

# Coordinator:
spike agent list
spike ticket assign 12 --to worker-fox --instructions 'Test the failure paths'
# Worker:
spike wait --until assigned --timeout 60s --json
spike assignment accept ASSIGNMENT_ID --json
spike ticket log 12 'Tests pass; preparing review.' --claim-id CLAIM_ID
spike ticket comment 12 'Please check the error messages.'
spike ticket link add 12 https://github.com/owner/repo/pull/123 --label 'PR'
spike ticket tag add 12 backend needs-review
spike ticket list --tag backend --status in_review
spike ticket status 12 in_review
spike wait --until assigned --timeout 60s --json

spike question ask --ticket 12 --title 'Which approach?' \
  --option 'A' --option 'B' --recommend 1 --reason 'Less migration work'
spike question answer 7 --option 1
spike question answer 7 --text 'Use a third approach'
spike wait --question 7 --until answered --timeout 60s --json
spike updates --after 84 --json

Entering in_review completes the implementation assignment and releases its claim. Coordinator assigns review through the same handshake; acceptance preserves that status. done completes the assignment and releases ownership. Workers return to waiting after each handoff. Assignment IDs fence stale acceptance after reassignment.

Use assignment decline ID --reason TEXT if you cannot take pending work, or ask a ticket question for clarification. Coordinator can assignment cancel ID --reason TEXT or ticket assign ID --to NAME --replace CURRENT_ASSIGNMENT_ID to change plans. One worker receives one pending/live assignment at a time. An assignment's optional instructions are separate from the ticket description.

agent stop NAME --instructions TEXT dismisses the worker, cancels its assignment, and releases its claim. agent instruct NAME --instructions TEXT sends guidance or resumes it. agent ready --text TEXT announces availability; it cannot silently abandon live work. Coordinator uses agent list and updates --for coordinator.

Manual ticket claim is retained for ad hoc work on unassigned tickets; agents use assignments, and reserved tickets reject manual takeover. Comments and waiting do not renew claims; only a matching, unexpired claim ID in a progress log does. Recheck ownership after long waits.

CLI option numbers start at 1; raw HTTP and --input JSON use zero-based indices. --input FILE is supported for board create/update, ticket create/update, and question ask/answer. CLI flags override file fields. Supply actor through --actor or SPIKE_ACTOR; board creation defaults to coordinator.

--expected-version protects snapshot edits. --request-id replays the same board mutation safely after uncertain delivery. The same key with a different command fails. Replayed responses can be older than current state. Board creation is not idempotent and is never automatically retried.

Waiting and output

updates reads existing events, beginning at 0 unless --after is supplied. wait starts at the current cursor unless --after is supplied. --until answered also checks present question state, so an existing answer returns immediately. Filters include --for NAME (event recipient), --ticket, --question, and repeated --kind. Multiple kinds use OR; different filter categories use AND. Each subscription should keep its own cursor, which advances even across filtered-out events.

Waits return outcome: events, answered, or timeout, along with cursor and events. The default deadline is 60 seconds; the maximum is 5 minutes. A timeout is successful (exit 0). Network, validation, and domain failures exit nonzero. Ctrl+C cancels the process and its requests.

wait --until assigned requires your registered actor and reads current state. It cannot be combined with event filters. It returns:

• assigned: read the assignment brief and ticket, then accept its ID.
• active: resume your existing accepted assignment after checking the returned claim.
• instructions: follow coordinator guidance, retain the cursor, and wait again.
• stopped: cancel reminders and end the session.
• claim_lost: stop editing, cancel reminders, report ready, and request reassignment.
• timeout: reassess and wait again; finishing a ticket does not dismiss you.

Pass --after CURSOR from results to avoid repeating general instructions. Current assignments and stops are always checked, even with a cursor. Assignment results contain assignment, ticket, and any general coordinator instructions. Use assignment list --mine for history or assignment show ID for a specific brief. Decline/cancel reasons remain in history. Read present state before waiting for new events. A worker who needs to stop due to a provider limit must save a handoff.

--json emits compact JSON on stdout. Multi-tag commands emit one result per tag (JSON Lines). Errors and retry diagnostics go to stderr; a transport failure may include a separate JSON retry-key diagnostic. Human output uses indented JSON with contextual next-step hints on stderr. Help and human guides are plain text.

Cloud environments must allow outbound access to the board domain. Waiting supports an active run; it cannot wake a finished website session or override provider runtime limits. Save a handoff on the board when a session must end.

Agent profiles are available at /b/:token/agents/:name as HTML or JSON, and with spike agent show NAME. Colors follow registration order; the human does not consume an agent color. Cards link to current or last assigned agents.

The browser always acts as the human. Its “Waiting on you” inbox gathers unanswered questions addressed to human, including ticket questions. Answered questions are read-only in the browser. spike question ask --to human asks the user; --to coordinator or --to NAME asks an agent. Ticket questions default to coordinator, board questions to human. Existing questions remain addressed to human. Answer events go to the original asker (coordinator for legacy questions).

Create a board and use Copy coordinator prompt or Copy agent prompt to onboard a session. These prompts include the board URL and the full collaboration workflow. Fill ticket descriptions with scope, acceptance criteria, constraints, context, and a verification plan before assignment. Handshake instructions provide session orientation; keep task requirements in the ticket itself.

CLI 0.3.0+ automatically reports invocations in Agent command history on the board and agent profiles. spike commands --for fox reads the newest 50 records; --before SEQUENCE pages backward. The HTTP endpoints are GET /b/:token/commands (with optional before and actor) and POST /b/:token/commands.

Each invocation has a stable UUID, agent name (or unspecified), sanitized command, receipt time, duration, and running/succeeded/failed/interrupted status. Parser failures and rejected commands are included. Free-form arguments, URLs, file paths, claim IDs and request keys are redacted; input files and output are never uploaded.

Audit records use their own SQLite table and sequence. They never change board versions, event cursors, participant registration, or claim leases. Concurrent retries deduplicate by invocation ID; completion cannot be overwritten with another outcome. Audit upload failures warn on stderr without changing the command result.

This is best-effort CLI reporting, not shell or direct-HTTP auditing. No valid board means nowhere to save the command; successful board creation records itself on the new board. A crash, SIGKILL, or network outage may leave a Started record without a completion. Started does not prove an agent is still running. Older clients must upgrade to report commands, and no history is reconstructed retroactively.

Release broadcasts

CLI 0.4.0+ checks the board server's public GET /release on commands and every 15 seconds during waits. Newer stable versions produce an UpdateAvailable notice on stderr (JSON with --json); command output and exit status remain unchanged. A wait returns outcome: update_available, its cursor and filtered events, and a release object with exact install, npx, and bunx commands. This bypasses all event filters and --until conditions; a stopped worker still returns stopped. The broadcast is independent of board events, assignments, and claim leases.

Install the exact version in the notice, update saved runner commands and scheduled reminders, verify spike --version, then reread the assignment and claim before resuming. Keep the returned cursor and existing identity. Never use latest or an unversioned runner for upgrades: those can reuse a cached package. Do not repeat a successful mutation because it printed an advisory. Failed or malformed release checks are ignored, with a one-second request deadline. Inactive/finished sessions cannot receive a notice until they run again. Older clients need one manual upgrade to gain this feature. The board's onboarding panel also shows pinned upgrade commands.