tuimote / docs / cli

tuimote session

Talk to other agent sessions, and drive individual ones

Send messages, read screens, start/stop, attach, and ask questions.

tuimote session ls

List sessions as a compact table

Filter with --running, --agent, --cwd. --json (or --pretty) dumps the raw array instead.

--agent <AGENT>

--cwd <CWD>

--running

--json

Emit the full raw JSON array instead of the compact table. Implied by --pretty/--human (which also pretty-print it)

tuimote session start

Start a new session, or resume one with --session

tuimote session start --cwd DIR --agent claude [-m "first message"] [--pin]

--cwd <CWD>

--agent <AGENT>

--session <SESSION>

-m, --message <MESSAGE>

First message to send once the session boots (as if you typed it)

--pin

Pin the new session as this repo's entrance session

tuimote session stop

Kill a session's tmux pane

<SESSION>

tuimote session archive

Archive a session (soft delete — recover it from `stash`)

Pass a <slug> shorthand, or the explicit --agent/--session[/--cwd].

[SLUG]

--agent <AGENT>

--session <SESSION>

--cwd <CWD>

tuimote session delete

Delete a session permanently

Pass a <slug> shorthand, or the explicit --agent/--session[/--cwd].

[SLUG]

--agent <AGENT>

--session <SESSION>

--cwd <CWD>

tuimote session copy

Convert a session to a different harness. [experimental]

tuimote session copy <slug> --to codex

[SLUG]

--cwd <CWD>

--session <SESSION>

--from <FROM>

--to <TO>

tuimote session send

Send a message to a session's composer

tuimote session send <target> your message here

With no target it goes to this repo's pinned session (resuming it if dead). Waits until the keys actually land at a ready agent.

[SESSION]

Target session (shorthand or tmux name). A first word that doesn't resolve is treated as message text (repo's pinned session is used)

[TEXT]…

--from <FROM>

--raw

--gently

tuimote session view

Read what's on a session's screen (read-only)

--lines N, --full, --ansi. No target = this repo's pinned session.

[SESSION]

--lines <LINES>

--full

--ansi

tuimote session attach

Attach to a session's tmux

No target = this repo's pinned session (resuming it if dead).

[SESSION]

tuimote session unpin

Clear a repo's entrance pin (inverse of `repo pin`)

With a <target> clears that session's repo; else --cwd, else this session's own repo.

[TARGET]

--cwd <CWD>

tuimote session keys

Send raw control keys to a session (C-c, Escape, Enter, arrows…)

tuimote session keys <target> C-c

Keys land verbatim — no text, no trailing Enter. Use send to type a message. Accepts tmux names (C-c, Escape, Tab), C-<letter>, or escapes (\x03, \e, \r). Multiple keys are sent in order.

[SESSION]

Target session (shorthand / tmux name / chat). A first word that doesn't resolve is treated as the first key (pinned session used)

[KEYS]…

One or more key names / sequences to send in order

tuimote session image

Attach an image to a session

tuimote session image <target> path/to.png [--caption "…"]

PNG/JPEG/GIF/WebP only. Uploads the file and types its path in the harness's own vision syntax.

<SESSION>

Target session (shorthand / tmux name / chat)

<PATH>

Path to the image file

--caption <CAPTION>

Optional caption typed alongside the path

--no-submit

Type the path without submitting (leave it in the composer)

tuimote session transcript

Print a session's transcript

Pass a <slug> shorthand. --mode picks the format (default no-tools).

[SLUG]

--agent <AGENT>

--session <SESSION>

--cwd <CWD>

--mode <MODE>

(default: no-tools)

tuimote session stub

Generate or refresh a session's one-line summary stub

Pass a <slug> shorthand, or the explicit --agent/--session pair.

[SLUG]

[TEXT]…

--agent <AGENT>

--session <SESSION>

--file <FILE>

tuimote session request

Ask a session a question and wait for its reply

tuimote session request <target> your question here

Blocks until it answers. --keep leaves the session running; --stop kills it after; without either it may auto-compact.

[TARGET]

Target: a live session ref, a dead shorthand (auto-resumed), or a directory to spawn in (needs --agent). Omitted: repo's pinned session

[TEXT]…

--agent <AGENT>

--compact-at <COMPACT_AT>

--tokenlimit <TOKENLIMIT>

--no-compact

--keep

--stop

--from <FROM>

--raw

tuimote session reply

Reply to the request waiting on this pane. (Agent side)

Pass a file path (preferred), inline text, or pipe the reply on stdin.

[PATH]…

--file <FILE>

tuimote session self-compact

Compact your own context, then resume where you left off

Run from inside a session pane, or pass --session.

[TEXT]…

--session <SESSION>

tuimote session summary

Write or deliver a single-session summary. [experimental]

tuimote session summary request

Ask a session to write and deliver its own summary

--archive stops and archives it once the summary lands.

<SESSION>

Session shorthand (or tmux name)

--archive

tuimote session summary deliver

Record a summary you generated. (Agent side)

--session <shorthand> alone is enough; the other flags cover dead-session delivery.

[TEXT]…

--session <SESSION>

--agent <AGENT>

--cwd <CWD>

--tmux <TMUX>

--archive

--file <FILE>

tuimote repo

Per-repo settings: entrance pin, memory, dashboard card, wiring

tuimote repo init

Wire tuimote into a repo and/or install the /tuimote skill

Defaults to --repo on the current directory.

--repo

--global

--cwd <CWD>

tuimote repo customize

Restyle this repo's dashboard card (emoji, icon, name, color)

Only the flags you pass change. --icon-svg takes a file path (read inline; must be <20 KB and script-free).

--emoji <EMOJI>

--icon-svg <ICON_SVG>

--alt-name <ALT_NAME>

--subtitle <SUBTITLE>

--color <COLOR>

--clear

--cwd <CWD>

tuimote repo pin

Pin a session as this repo's entrance point (one per repo)

tuimote repo pin <target>

Pinned sessions skip idle auto-stop and are the default target for send/view/attach/request. No target prints the pin; --clear removes it.

[TARGET]

--clear

Remove this repo's pin

--cwd <CWD>

tuimote repo migrate

Hand this repo's pinned session over to a fresh one (any harness)

tuimote repo migrate --agent codex

The old session writes a handoff, a new one boots reading it and inherits the pin, and the old one is archived.

--agent <AGENT>

Target harness for the successor session (claude/codex/pi/reasonix)

--cwd <CWD>

tuimote repo history

Add a dated entry to this repo's HISTORY.md

Reads from stdin, --file, or positional text.

[TEXT]…

--cwd <CWD>

--file <FILE>

tuimote repo stubs

Generate one-line stubs for all of this repo's sessions

--cwd <CWD>

--agent <AGENT>

--session <SESSION>

Restrict the pass to a single session transcript id

--force

--missing-only

--limit <LIMIT>

--concurrency <CONCURRENCY>

(default: 6)

--model <MODEL>

--timeout <TIMEOUT>

(default: 45)

tuimote repo supercompact

Fold session summaries into repo memory. [experimental]

tuimote repo supercompact start

Spawn the supercompaction agent for a repo

--cwd <CWD>

--agent <AGENT>

--archive

tuimote repo supercompact deliver

Deliver the supercompaction report. (Agent side)

Pipe it, or use --file / positional text. --archive also stops and archives every other session in the directory.

[TEXT]…

--cwd <CWD>

--archive

--session <SESSION>

--dry-run

Print what would be archived/stopped without doing it

--file <FILE>

tuimote repo multisummary

Curate and batch-summarize this repo's sessions. [experimental]

tuimote repo multisummary start

Spawn the multisummary curation agent

--cwd <CWD>

--agent <AGENT>

--convert

tuimote repo multisummary decide

Commit the curation verdict (archive rejects, summarize keepers)

--cwd <CWD>

--session <SESSION>

--keep <KEEP>

Slugs to summarise, comma-separated

--archive <ARCHIVE_SLUGS>

Slugs to archive, comma-separated

--convert

tuimote repo multisummary deliver

Deliver the multisummary receipt. (Agent side)

[TEXT]…

--cwd <CWD>

--session <SESSION>

--file <FILE>

tuimote repo context

Print this repo's memory playbooks (HISTORY, STATE, NEXT)

state or next prints just that one file (raw, pipeable). To append to HISTORY use repo history instead.

[WHAT]

Which view to print [show | state | next] (default: show)

--cwd <CWD>

Repo to read (defaults to the session you're in, then the cwd)

tuimote config

Server config: Claude account profiles and the web-UI password

tuimote config profile

Claude account profiles. With no verb, lists them

tuimote config profile ls

List the available profiles and the active one

tuimote config profile switch

Switch the active Claude account profile

<ID>

tuimote config profile add

Add a Claude account profile

--label and --bin are required. --id is derived from the label when omitted; --credentials-command sets an optional refresh command.

--label <LABEL>

--bin <BIN>

--id <ID>

--credentials-command <CREDENTIALS_COMMAND>

tuimote config profile remove

Remove a Claude account profile by its id

<ID>

tuimote config password

Set the web-UI password (how you secure a networked server)

Pass it as an argument, or omit it to be prompted / read it from stdin.

[PASSWORD]

tuimote config ls

List every setting and its current value

--json emits a {key: value} object.

--json

tuimote config get

Print one setting's value (bare; `--pretty`/`--human` emit JSON)

<KEY>

tuimote config set

Change one setting

tuimote config set fontFamily custom

The value is coerced to the key's type (bool, int, or comma-separated list). Only that one field changes.

<KEY>

<VALUE>

tuimote server

Control this tuimote server: usage, logs, restart

tuimote server usage

Show server usage statistics

tuimote server logs

Show the most recent server log lines

--follow

Keep printing new log lines until interrupted

--err

Show the error log instead of standard output

tuimote server restart

Restart the server in place (same binary, no rebuild)

--scope uses the network-scope-staleness recovery path.

--scope

Use the launchd network-scope-staleness recovery restart

tuimote service

Install tuimote as a background OS service

Generates and manages a launchd agent (macOS) or systemd --user unit (Linux). Runs as your user, in $HOME. Use setup for a guided install.

tuimote service install

Write the OS service file (doesn't start it)

Run service load afterwards to start it. Idempotent overwrite.

--bin <BIN>

Path to the tuimote-server binary the service should run. Defaults to the sibling of this CLI binary

tuimote service uninstall

Stop (if running) then remove the OS service file

tuimote service load

Start the service and enable start-at-boot

tuimote service unload

Stop the service (leaves the file in place)

tuimote service status

Report whether the service is installed and running

--json

Emit a machine-readable JSON report instead of the human summary

tuimote peers

Federation: manage the other tuimote servers on your network

Add/remove peers, toggle them, wake a sleeping one (Wake-on-LAN), flip mDNS discovery, and set the shared pairing secret.

tuimote peers ls

List peers and the current discovery config

tuimote peers add

Add or update a peer

tuimote peers add host[:port] --cert-fingerprint SHA256 [--label NAME]

<PEER>

Peer address: host or host:port

--label <LABEL>

Friendly dashboard label

--mac <MAC>

Wake-on-LAN MAC (aa:bb:cc:dd:ee:ff, any separator)

--cert-fingerprint <CERT_FINGERPRINT>

SHA-256 fingerprint shown by tuimote peers ls on the peer

--transport <TRANSPORT>

Federation transport (direct or ssh) (default: direct)

--ssh-target <SSH_TARGET>

OpenSSH host/alias used by the managed local forward

tuimote peers remove

Remove a static peer

mDNS-discovered peers reappear on the next browse.

<PEER>

Peer address: host or host:port

tuimote peers toggle

Enable or disable a peer (flips its state)

<PEER>

Peer address: host or host:port

tuimote peers wake

Send a Wake-on-LAN packet to a peer's configured MAC

<PEER>

Peer address: host or host:port

tuimote peers discovery

Turn mDNS discovery on or off

tuimote peers discovery on

<STATE>

on or off

tuimote peers secret

Set the shared pairing secret (never echoed back)

<VALUE>

The secret value (use "" to clear)

tuimote artifact

Register files to show in this repo's terminal document reader

Handles markdown, HTML, LaTeX, LilyPond, Mermaid, and images. Run from inside a session pane; the repo defaults to the one you're in.

tuimote artifact add

Register a file to show in the reader

tuimote artifact add PATH [--folder GROUP]

PATH is relative to the repo root. A malformed file is rejected with the linter's error.

<PATH>

--folder <FOLDER>

tuimote artifact remove

Unregister an artifact

<PATH>

tuimote artifact ls

List the registered artifacts

tuimote artifact annotations

Show a user's staged notes on an artifact as a rewrite prompt

No path lists every file with staged notes. --clear discards them.

[PATH]

--clear

tuimote artifact tabs

Manage reader groups (the reader's tabs)

tuimote artifact tabs ls

List the configured tabs

tuimote artifact tabs add

Create a tab (or add cwds to an existing one of the same name)

<NAME>

Tab name (must not collide with a built-in tab name)

--cwd <CWD>

Member cwd(s). Repeatable

tuimote artifact tabs remove

Remove a tab by name

<NAME>

tuimote panel

Author and check dock panels (the right-edge plugin pages)

verify lints a panel .js file against the rules discovery enforces before a panel is allowed to load.

tuimote panel verify

Lint a panel .js file against the registration rules

tuimote panel verify path/to/panel.js

Exits non-zero if any error-severity rule fails and prints the rule, line, and fix. Warnings and info never block.

<FILE>

Path to the panel .js file

--kind <KIND>

Override the source kind (builtin|user|repo); inferred from the path otherwise. Only repo enforces the sidecar allowlist rules

--json

Emit a machine-readable JSON verdict instead of the human report

tuimote panel ls

List the dock panels available in this repo

Built-in + user-global + repo-local, with their trust/valid state.

tuimote panel trust

Allow this repo's local panels to load

Pass a repo path, or omit it for this session's repo. --revoke withdraws the grant.

[CWD]

--revoke

tuimote stash

Restore or purge archived and trashed sessions

archive and delete move sessions here. List them, then restore, re-trash, or purge one by its key — or empty the trash.

tuimote stash ls

List archived + trashed sessions (compact table; `--json`/`--pretty` for the raw `{archive, trash}` object)

--json

Emit the full raw JSON instead of the compact table. Implied by --pretty/--human

tuimote stash restore

Restore a stashed session back to live (archive→live or trash→live), by its key (the `<kind>/<agent>/<rel>` path from `stash ls`)

<ID>

tuimote stash retrash

Move an archived session to trash, by its key

<ID>

tuimote stash purge

Permanently delete one trashed session, by its key

<ID>

tuimote stash empty

Empty the trash (permanently delete every trashed session)

tuimote font

Set a custom terminal/composer font

Upload a woff2/woff/otf/ttf/ttc file, then switch to it with tuimote config set fontFamily custom.

tuimote font upload

Upload a font file (woff2/woff/otf/ttf/ttc) as the custom font

<FILE>

tuimote font delete

Remove the custom font (revert to the system stack)

tuimote font status

Show whether a custom font is set (mime + size)

tuimote skills

List the slash commands an agent offers in a repo

The same set the web composer completes, plus any cross-agent divergence warnings. Defaults the agent and repo to the session you're in.

--agent <AGENT>

Agent id (claude/codex/pi/...). Defaults to this session's agent

--cwd <CWD>

Repo to scan (defaults to the session you're in, then the cwd)

--json

Emit the raw {commands, warnings} JSON

tuimote status

Print a health report for the server, harnesses, and peers

Covers reachability, version, security posture, each harness's availability, and peer/usage status. Read-only. --json for the machine form. Use doctor to also fix what's wrong.

--json

Emit a machine-readable JSON report instead of the human summary

tuimote doctor

Diagnose problems and offer a fix for each

Runs the status checks, then prompts to apply a fix per problem (install hints, config repair, securing a networked host, the OS service, Linux linger). --yes runs unattended; --json just reports.

--yes

Apply every fix without prompting (unattended)

--json

Emit a machine-readable JSON report (suppresses interactive prompts)

tuimote update

Check for a newer release; self-update where safe

Behavior follows the install method: install.sh installs download the signed release, verify it (minisign + SHA-256), swap atomically, and restart the service; Homebrew installs print brew upgrade tuimote && tuimote setup; source builds defer to the dev loop (self-rebuild.sh / tuidev restart).

--check

Report only — never download or swap binaries

--yes

Apply without the confirmation prompt

tuimote setup

One-shot install: set up the service and print your dashboard URL

Runs doctor, installs and starts the OS service, prompts for a password if the host is exposed, then prints the LAN URL. Safe to re-run.

--yes

Run unattended (no prompts)

tuimote uninstall

Remove tuimote's service and installer-managed files

Keeps global config and state by default. --purge removes ~/.tuimote, but always leaves per-repo .tuimote directories alone.

--purge

Also remove global config and state under ~/.tuimote

tuimote changelog

Show what changed between releases

Prints the release notes shipped with this build, newest release first. Handy around an update:

tuimote changelog --since 1.0.0

--since <VERSION>

Show only releases newer than this version (e.g. your current one)

tuimote completions

Print a shell completion script (zsh, bash, fish, …)

Write it where your shell picks it up, e.g. for zsh:

tuimote completions zsh > ~/.local/share/zsh/site-functions/_tuimote

(and make sure that dir is in $fpath before compinit runs).

<SHELL>

Shell to emit a script for [bash | elvish | fish | powershell | zsh]

tuimote man

Print the man page (roff) to stdout

Write it somewhere man looks, e.g.:

tuimote man > ~/.local/share/man/man1/tuimote.1

tuimote whoami

Show this pane's own session identity (shorthand, cwd, agent)

tuimote chat

Open the global chat session (not tied to any repo)

Spawns or resumes the persistent entrance session from settings, then attaches its tmux. Reach it elsewhere with the target chat.