@vibecook/spaghetti

CLI commands

Binaries: spaghetti and the shorter spag. Bare spag on a TTY opens the multi-agent TUI; subcommands print to the shell. Most commands accept --json for scripting. When ~/.codex/sessions exists, Codex is auto-detected alongside Claude Code.

Resolution

Flexible project & session args

You rarely need full UUIDs. Arguments resolve the way you already think about them.

.

Current working directory’s project (matched against indexed paths).

latest / last

Newest session for the selected project.

1, 2, …

Numeric index from the list view (1-based).

spaghetti

Fuzzy / prefix project name match.

a3f1

Partial session UUID prefix.

--json

Machine-readable output on nearly every command.

common patterns 
spag                              # interactive TUI
spag projects
spag sessions .                   # current repo
spag messages . latest
spag search "worker pool"
spag export . --format markdown -o out.md
spag doctor
Browse

Projects, sessions, messages

spag projects

alias: p

List indexed projects with Agent column, session counts, message totals, tokens (official or ~ estimated for Codex), and last activity. TUI groups projects into per-agent tabs when multiple sources are present.

  • -s, --sort <key>active · sessions · messages · tokens · name (default: active)
  • -l, --limit <n>Limit rows
  • --jsonJSON output (includes sourceId, tokensEstimated)
spag projects --sort tokens --limit 20 spag p --json

spag sessions [project]

alias: s

List sessions for a project — agent, branch, message count, tokens, duration, summary. Scoped to the resolved project’s sourceId so Claude and Codex on the same repo stay separate.

  • -s, --sort <field>recent · tokens · messages · duration
  • -l, --limit <n>Default 20
  • -a, --allNo limit
  • --since <time>today · yesterday · "3 days ago" · ISO date
  • --jsonJSON output
spag sessions . spag s spaghetti --sort tokens --limit 10 spag sessions . --since today

spag messages [project] [session]

alias: m

Read a session transcript with tool use, thinking blocks, and pagination. Assistant headers show CLAUDE or CODEX based on the project’s agent source.

  • -n, --limit <n>Default 50 messages
  • --offset <n>Start at message N
  • --last <n>Show last N messages
  • --compactOne line per message
  • --no-toolsHide tool-use details
  • --no-thinkingHide thinking blocks
  • --rawRaw JSON per message
  • --jsonFull JSON payload
spag messages . latest spag m . latest --last 20 --compact spag messages spaghetti a3f1 --no-thinking
Discover

Search & stats

spag stats

alias: st

Aggregate overview: project/session/message counts, DB size, token totals, top projects by tokens.

  • --jsonJSON output
spag stats spag st --json
Artifacts

Memory, todos, plans, subagents

spag memory [project]

alias: mem

Print project MEMORY.md content.

spag memory . spag mem spaghetti --json

spag todos [project] [session]

alias: t

Show session todos captured under ~/.claude/todos/.

spag todos . latest

spag plan [project] [session]

alias: pl

Show the plan linked to a session, if any.

spag plan . latest

spag subagents [project] [session] [agent]

alias: sub

List subagents for a session, or drill into a specific agent’s transcript by index.

spag subagents . latest spag sub . latest 1
Export & ops

Export, hooks, chat, doctor

spag export [project]

alias: x

Export project or session data as JSON or Markdown.

  • -s, --session <id>Export one session only
  • -f, --format <fmt>json · markdown (default: json)
  • -o, --output <path>Write to file (default: stdout)
  • --include-toolsInclude full tool-result bodies
spag export . --format markdown -o session.md spag x spaghetti -s latest --include-tools

spag hooks

alias: h

View Claude Code hook events captured by the Spaghetti hooks plugin. Does not require a full index rebuild.

  • -f, --followStream like tail -f
  • --filter <type>e.g. PreToolUse
  • -l, --limit <n>Last N events (default 50)
  • --clearClear recorded events
  • --jsonJSON output
spag hooks --follow spag h --filter PreToolUse --limit 100

spag chat [message]

alias: c

Talk to active Claude Code sessions via the channels plugin (loopback WebSocket). Requires the channel plugin to be installed and a live session.

  • -f, --followStream messages in real time
  • -s, --session <id>Target session UUID prefix or index
  • -a, --allApply to all sessions
  • -l, --limit <n>History entries before follow
  • --cleanupRemove stale session discovery files
spag chat --follow spag c -s a3f1 "what's the status?"

spag plugin <action> [plugin]

Install, uninstall, or check Spaghetti’s Claude Code plugins (hooks, channels).

spag plugin list spag plugin install hooks

spag doctor

Health-check data paths, plugin state, and common setup issues.

spag doctor

spag engine

Show or set the active ingest engine (rs / ts). Persists to ~/.spaghetti/config.json.

spag engine spag engine rs SPAG_ENGINE=ts spag stats

spag update

Check for and install CLI updates from npm.

spag update

spag uninstall

Print uninstall instructions for the CLI and related state under ~/.spaghetti.

Prefer a library?

Everything the CLI can see is available from @vibecook/spaghetti-sdk.

API reference Install