sesh-cli
Use the `sesh` CLI/TUI to list, find, enter, resume, create, tag, archive, rename, reparent, capture, send-to, delegate, or inspect coding-agent threads across machines. Use when the user asks about sesh command usage, the thread TUI, entering/resuming a thread, cross-machine thread state, the sesh daemon, peers, mycockpit (the cross-machine tmux cockpit), or tickets.
How do I install this agent skill?
npx skills add https://github.com/lukastk/sesh --skill sesh-cliIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The sesh-cli skill is a sophisticated management tool for coordinating AI agent threads across multiple machines using the sesh daemon and tmux. It features robust safety protocols, including mandatory identity verification and directory traversal protections. While it processes external data from agent transcripts and tickets, it implements strong boundary markers and sanitization to maintain security.
- Socketpass
No alerts
- Snykfail
Risk: CRITICAL · 2 issues
What does this agent skill do?
sesh
Use sesh, the multi-machine thread manager: one Go binary + daemon per machine.
Agent identity is a pane marker, not a tmux session (sessions may host siblings).
Records survive runtime loss. sesh owns mechanism; myrig owns policy/shell UX.
Prefer sesh help-tree and sesh <group> <verb> --help to guessing; use --json
for scripts. Paths below resolve from this installed skill directory, not CWD.
Read only the reference for the task, not the whole manual.
Mandatory authority and safety
- Verify yourself:
TID=$(sesh whoami) || exit 1. Daemon-launched headless or scheduled workers useTID=$("$SESH_BIN" whoami) || exit 1. This gate accepts pane/turn or corroborated harness provenance; inheritedSESH_THREAD_IDalone is unverified and can name unrelated work.infois diagnostic, not proof. Never discard stderr or use--allow-unverifiedto bypass a self-action gate. If refused, read its lead and corroborate viainfo+ pane capture; unresolved does not mean “not a thread”. Never borrow an id for signing/attaching work. - Explicit targets: scripts should name their intended thread.
stopanddeleterequire explicit nonempty--id; other verbs may infer only if the selector is omitted, never explicitly empty. Prefixes must be unambiguous.stopends runtime but keeps the conversation;deletedrops the record, promotes children, and refuses live runtime unless--force(which orphans it). Shell-thread stop kills the whole session and requires force if agents live inside. Archive parks a FINISHED record: it refuses a flagged or running thread (clear the flag / stop it, or--force). Think before all mutations. - Parenting is deliberate:
thread newnormally infers a child of the caller. A requested child must use your verified id as--parent; standalone work MUST use--no-parent. Parenting requires the same owner machine; do not pretend a routed root is a cross-machine child. For ordinarythread new, omit--agentunless the user requested a harness; the owner applies[defaults] agent (unset fails loudly;--fork-from` inherits the source harness). - Harnesses:
claude,codex,piandmypi.mypiis the patched pi fork as its own harness: same conversation format, session store, RPC steering and native metadata CLIs aspi, launched from themypiexecutable on the OWNER daemon's PATH. It is a separate kind everywhere a launch happens (--agent mypi,[defaults] agent = "mypi",[spawn.mypi], resume, headless turns) and shares pi's behaviour everywhere a conversation is read or steered. A missingmypifails loudly; it never falls back topi, andsesh doctorwarns (never fails) when the executable is absent. Pane detection depends on the packaging: the frozen mypi copy presents comm/argv0/titlemypiand is detected as such, while the plain source fork keeps pi'sAPP_NAMEand presentspi, indistinguishable from vanilla pi. Sesh therefore matches a pane's agent by FAMILY, which is correct either way, and an unmanaged pi-presenting mypi pane is ADOPTED aspi. Pass--agent mypito a headless adopt when registering a not-running mypi conversation. - Schedules: archive one you are finished with (
schedule archive), do not leave it paused —pausedmeans "coming back" and stays in the default listing, so a paused pile buries the live schedules. Archiving keeps the record and its run history;remove/prunethrow them away. This applies to the one-shot backstops a thread sets for itself: when the work lands early, archive the backstop. Archiving a THREAD archives the active message schedules aimed at it. - Route for real:
--machine <m>uses SSH or peer HTTP, not a cosmetic field; HTTP routing needs the local daemon. Check owner/reachability withmesh/info. The TCP API never exposes generic/v1/route. Cross-peer browser operations require explicit[browser_hub]opt-in plus a trusted HTTP-peer allowlist; otherwise browser endpoints are local-owner-only. Browser Fetch access additionally requires an exact[browser_api].allowed_originsentry; it defaults empty and grants CORS only to fixed browser/ticket routes. Preflight does not weaken bearer authentication; generic, Unix-only, and runtime routes never receive CORS headers. Quote owner-home paths:--cwd '~/proj'reaches the remote home; unquoted~expands in the caller's shell. Relative paths expand locally. Browser clients follow the browser API contract: fixed routes, ids not paths, no fallbacks from refused native protocols. - Delivery: live Pi
thread sendis literal RPC steering, even/compact; it preserves drafts and waits for running tools. Commands usethread command. No paste fallback, automatic reload, or blind retry after uncertain ACKs.sent/resourcesubmittedis not completion. Recover commands by request UUID. Everything true of live Pi delivery is true ofmypi: one RPC protocol, one socket directory, no paste fallback for either. Claude/Codex/shell pastes use the viewer-typing guard (60s default): defer/wait/ skip, bounded, never paste on expiry.--respect-typing 0intentionally bypasses it; do not casually disable it. Deferred queues are lost on daemon restart. - Live rig: never hand-restart supervised production daemons; use
supervisorctl restart sesh-daemonwhen authorized, preserving service env/API. Termux is the explicit-PID/fresh-login exception; read the fleet reference first. Tests must strip inheritedSESH_*and isolateSESH_HOME,SESH_TMUX_SOCKET,SESH_MASTER_SOCKET,SESH_CODEX_HOME. Use absolute sandbox binary paths; myrig wrappers may point to production. No default live homes/sockets, broad process kills, or test viewers attached to user sessions (resize risk). - Tickets: never create one unless Lukas explicitly asked. An unasked-for
ticket lands in his vault as a note he must consolidate by hand; steer sub-threads
with
thread send/delegateand record findings where the work lives. Read assigned prompts, keep active until ready, then finish withdoneand a markdown note explaining changes and commit SHA. Abandoned work isdroppedwith a reason, never silently closed. Verify routing/binding.
Common operations
Replace <…> placeholders; creation/sending/lifecycle commands mutate real work.
sesh thread list --all-machines --json
sesh info <id> --json
sesh thread capture --id <id> --lines 80
sesh tail <id> -n 50
sesh tui --all-machines
sesh thread new --name subtask --cwd . --parent "$TID"
sesh thread new --name independent --cwd '~/proj' --machine macbook --no-parent
sesh thread resume --id <id>
sesh thread send --id <id> --text 'Continue the approved task' --wait --timeout 5m
sesh thread send-headless --id <id> --text 'Summarize' # idle thread, no pane (strict: refuses while busy)
sesh thread send --id <id> --text 'Also check X' # headless thread: a turn now, or queued behind one in flight
sesh thread queue --id <id> # queued messages for a headless thread
sesh thread command --id <pi-id> --text '/compact retain the plan' --timeout 5m
sesh thread command --id <pi-id> --request-id <uuid> --timeout 5m # poll, no resend
sesh subscribe <child-id> --from "$TID" # completed turns into parent
sesh context set --file brief.md --id <id> # standing instructions for ONE thread
sesh env set --id <id> API_URL=https://… # env vars for ONE thread; flags first
sesh thread new --mcp-arg soliton=--agent-file=<path> # add an argument to a global MCP server, for ONE thread
sesh ticket list --current # assigned ticket prompts are work
sesh ticket get --id <ticket-id> --field prompt
sesh ticket set-status --id <ticket-id> --status done --note 'Changes; closed by <sha>'
sesh doctor
sesh mesh
TUI: p command palette, ? keys, / filter, Tab view picker, Enter navigate/revive,
I details, K tickets, S shells; a archives instantly (refused for
flagged/running threads), U undoes archive. Sidebar q/Esc dismiss errors, not
quit; Ctrl-C always quits. Headful/headless is independent of busy/idle; flags
require explicit clearing, holds hide even flagged work from active. Offline rows
are hidden by default, not deleted.
Task → bundled reference
| Task | Read |
|---|---|
| Identity refusal, selectors, scheduled-worker provenance | identity |
| State glyphs, shell/virtual threads, trust, ownership | concepts |
Create/adopt/fork, lifecycle, held Claude sessions, navigation, idle stop (sesh idle-stop) | threads |
| Send/wait/delegate/subscribe, Pi commands, typing and state authority | delivery |
| Ticket lifecycle/routing/reporting, blob tokens/files | tickets and blobs |
| TUI scope, palette/keymap, parent picker, tickets/columns | TUI |
| Persistent/traveling sidebar and focus tracking | sidebar |
| Hold/release inheritance, pin/divider, archive/offline views | views and holds |
| Cron/interval/one-shot messages or spawns, guards, run history, lifecycle | scheduling |
| Mesh, peers, cockpit/daemon recovery, environment | fleet |
| Agent models: registered vs observed, set/switch a thread's model, the MODEL column, listing, per-harness defaults | models |
A thread's custom context: per-thread standing instructions (sesh context), how each harness receives it, the CTX column, viewing/editing | context |
A thread's environment variables (sesh env, thread new --env), when a change reaches a running agent, thread restart, inheritance, where values live, the ENV column | env |
A thread's MCP arguments: --mcp-arg, thread mcp-arg set/unset/list, what each harness receives, what the global entry must look like | mcp-args |
| Daemon/TUI config, the per-machine config.local.toml overlay, hooks, browser hub/CORS settings | config |
| Browser HTTP API for graphical clients: routes, WebSocket tickets, history/artifacts/media, attachments | browser API |
Remote directory listing, running named commands on a machine (host-cmd) | integrations |
Detailed examples retain their versioned incident context; check installed help and observed state rather than assuming an old deployment claim is current.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/lukastk/sesh/sesh-cli">View sesh-cli on skillZs</a>