@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 doctor

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

spag doctor

spag engine

Show Rust observation-engine and native-addon status. RFC 011 retired production engine switching.

spag engine spag engine rs spag engine ts # explains that the TS path is retired

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