NexusCrew Agent I/O

Use the NexusCrew MCP bridge for communication with the human, read-only runtime discovery, and authenticated delivery to active Fleet cells. Use the bundled helpers only for same-host tmux compatibility fallbacks.

MCP bridge (preferred)

When the client exposes the NexusCrew MCP server, use these tools directly:

Apply these rules:

• Use nc_notify for meaningful asynchronous updates, failures requiring attention, and completion. Pass its optional lang field (it, en, es or an equivalent BCP-47 locale) whenever the notification text language is known, so opted-in speech uses the right on-device voice. Do not notify for every command or duplicate routine chat commentary.
• Never include access tokens, credentials, private keys, push subscriptions, or other secrets in a notification, ask, file caption, or tool result.
• Treat nc_ask as non-blocking: it returns an ask ID immediately. Continue safe independent work or wait normally; the human response arrives in the originating tmux session with a [human reply · ask#<id>] prefix by default.
• Use nc_status instead of scraping NexusCrew state files. Use nc_deck instead of reading decks.json: it returns every local or authorized shared-owner deck containing the caller, preserves visual member order, identifies each deck and member by stable owner ID, includes viewer-valid Hydra routes, and reports cell: null when no managed Fleet match is available.
• Use nc_cells immediately before cross-cell delivery. Select its exact owner-qualified id; require canReceive: true; never guess a duplicate name or stale route.
• Use nc_send_cell {target, message} for actual Fleet-cell delivery. submitted confirms bracketed paste plus Enter only, never task acceptance or completion. Inactive targets are not queued.
• Use nc_vl_nodes immediately before VL mutation. Mutation tools require an active local Fleet caller and the full owner-qualified VL ID. nc_vl_command submitted means live-poll delivery only; require the same ID in lastAck. No offline queue exists.
• Use nc_inbox instead of guessing an inbox path when the tool is available.
• Pass nc_send_file an existing absolute regular-file path below the user's home. Let NexusCrew choose and sanitize the outbox name.
• Speak only when audio is the point. nc_speak needs an exact target instance id and returns a caller-scoped receipt with a per-endpoint status (refused, unreachable, accepted) — accepted means the node took the utterance, not that a human heard it. Keep the text short: a spoken line that runs long is worse than no line, and the detail belongs in a file or a notification. A status or stop call only ever reaches an utterance you started; you cannot inspect or silence someone else's.
• nc_speak_group expands a named local group into exact instance ids. primary-failover tries one endpoint at a time; fanout is explicit. Neither receipt reports text, language or voice back to you — that is deliberate, and it means the receipt cannot be used to read what another caller said.
• Consent to use a room's speaker is granted locally on the node that owns it and never across the federation. Speaking and stopping travel; granting does not.
• nc_identity answers "who am I to this bridge" with non-sensitive data only, and works without a tmux session or a token. Use it when a tool refuses you and you are not sure which caller the server sees, instead of guessing from the environment.
• nc_cell_diagnostics returns the redacted shell command and the last bounded spawn or start failure for one local Fleet cell. Use it when a cell will not come up, before reading state files.
• Do not treat an MCP notification as a substitute for the final response required by the active client.

Live lease registration (nc_lease_*)

A cell can hold a Live lease registration on the node: it registers once, then keeps the registration alive by presenting the proof it received. Three tools, one job each — their return values do not overlap:

• nc_lease_register {proof?} — registers this cell under its own incarnation and returns the first child proof. It can answer {status:"pending"} with a retryAfterMs when the node is not tracking the cell yet: wait that long and call it again rather than spinning.
• nc_lease_refresh {proof} — renews a live registration. Pass the last received proof object back unchanged. Answers {status:"live"} with a new proof; it is never pending, and {status:"no-registration"} means nc_lease_register is the next call, not a retry.
• nc_lease_recovery {proof} — resumes the registration after a gap, keeping the same incarnation; a proof that expired recently is still accepted. Every attempt counts toward a cap — past it, register again.

Use them only when your runtime asks this cell to hold a Live lease. Treat each status literally, and pass proofs through verbatim.

The MCP server is the stdio command nexuscrew mcp and must be registered in the host AI client. If the nc_* tools are not exposed, report that the bridge is not configured in that session and use the fallback flows below where applicable.

Optional capability companions

NexusCrew does not make unrelated MCP servers hidden dependencies. When the user requests durable structured memory, document retrieval, bounded worker delegation or mailbox access:

1. Discover the tools already exposed by the current AI client.
2. Use an available tool that covers the request.
3. If the capability is absent, consult the packaged ../../mcp-companions.json catalog and mention the matching optional companion once.
4. Explain the capability it adds and link its public repository.
5. Ask before installing software, changing MCP configuration, starting a service or requesting credentials.

Never recommend a companion during unrelated work, repeatedly advertise it, or claim it is required by NexusCrew. The catalog is discovery metadata only; it does not authorize installation or external actions. See ../../MCP_COMPANIONS.md for the human-readable guide.

File exchange (inbox / outbox)

Per session, NexusCrew watches <root>/<session>/{inbox,outbox} (root = $NEXUSCREW_FILES_ROOT, default ~/NexusFiles):

• outbox — files you write here surface in the browser UI with a badge. This is how you deliver a deliverable.
• inbox — files the human sends arrive here. The path reaches you in your prompt either way, but through two different human-side flows: the files-panel upload pastes the bare path straight into your PTY, while the composer attach button (paperclip, v0.7.7+) puts the path inside the human's typed message — expect paths mixed with instructions, not always a bare path on its own line. Read the files from the inbox; never overwrite, treat as read-only input.

When nc_send_file is unavailable, deliver with the helper (resolves the current tmux session, timestamps, never overwrites):

"$(npm root -g)/@mmmbuto/nexuscrew/skills/nexuscrew-agent/bin/nc-deliver" report.pdf chart.png
# → ~/NexusFiles/<session>/outbox/

The helpers ship inside the npm package and are not linked on PATH — the only global command is nexuscrew — so address them under the global package root; npm root -g prints that root for the Node installation in use.

Don't hand-craft the path from a guessed session name — use nc-deliver, or derive the session with tmux display-message -p '#S'.

Sending text to a tmux session

For an active managed Fleet cell, prefer nc_cells followed by nc_send_cell. The helper below is a same-host fallback for older NexusCrew runtimes or non-Fleet sessions; it must not bypass federation visibility or routing ACLs.

tmux send-keys 'msg' Enter is not reliable: a TUI's paste-burst detector swallows the Enter and the message just sits in the composer, while exit code is still 0. Use the helper:

NC_SEND="$(npm root -g)/@mmmbuto/nexuscrew/skills/nexuscrew-agent/bin/nc-send"
"$NC_SEND" <session> "text"              # paste + submit
"$NC_SEND" <session> --file prompt.txt   # from a file
"$NC_SEND" <session> --no-submit "text"  # leave in composer, no Enter

It does: load-buffer → paste-buffer -p (bracketed paste) → burst-flush (C-e) → Enter. Verify it landed — never trust the exit code:

tmux capture-pane -t <session> -p | tail -8   # see the text / a running state

Terminal scrolling (NexusCrew-managed tmux)

A drag or wheel in the NexusCrew web terminal browses the tmux history through copy-mode. That works only while the pane is on the normal screen. A full-screen TUI — Claude Code, Codex, Agy, vim, less, htop — renders in the terminal's alternate buffer, which has no scrollback: copy-mode has nothing to scroll, so the gesture does nothing. On a phone, where the drag is the only scroll gesture, the terminal looks frozen.

NexusCrew applies alternate-screen off per session when it creates a managed Fleet session or a PWA session. No global tmux option or ~/.tmux.conf edit is needed: tmux then ignores smcup/rmcup for that session, TUI output stays on the normal screen, the transcript flows into tmux history, and drag/wheel scrolling work. The setting is also applied to windows created later in that session.

• It applies only to future NexusCrew-created sessions. A running or unmanaged pane remains unchanged; never restart a Fleet cell just to change it.
• To opt out, set alternateScreen: true in NexusCrew's local config.json or start the service with NEXUSCREW_ALTERNATE_SCREEN=1.
• Verify on a pane that is running a TUI: tmux display-message -p -t '=<session>:' '#{alternate_on}' must print 0.
• Trade-off: after quitting vim/less/htop the last screen stays on display instead of being restored.
• Full-screen redraws consume history. Keep a generous user-owned history-limit (100000 is a good default); nexuscrew doctor warns below 10000 and suggests set -g history-limit 100000, but never writes it.

Quick reference

Common mistakes

• Trusting send-keys ... Enter → message stuck in composer. Use nc-send (bracketed paste + flush).
• Not verifying the send → exit 0 means nothing; always capture-pane.
• tmux aliased/wrapped by the shell (e.g. an oh-my-zsh plugin) → the nudge silently fails. Helpers resolve the real binary; in ad-hoc commands use /usr/bin/tmux or command tmux.
• Pasting onto a dirty composer → text concatenates with whatever was there. Clear it first, or the previous line will merge with yours.
• Delivering to a guessed session name → file lands in an orphan folder with no badge. Use nc-deliver (it reads the real session).
• Sending to an ambiguous cell name → call nc_cells and use the full owner-qualified ID.
• Calling submitted a completed task → it is only a transport receipt; require an explicit result callback.
• Concluding a cell is stuck because it looks idle → a terminal interface queues an incoming message while it is busy, which is healthy; text sitting in the composer of a cell that is not working is the defect. To tell them apart, read CPU time from the child of the pane process: the pane's own pid is often a wrapper that never burns CPU, so measuring it reports "idle" for a cell working at full tilt.
• Assuming a node listens on the port you know → NexusCrew selects a free port per installation, and a peer's remote port is not the port that node listens on locally. Read it from nexuscrew status on that node; a health check aimed at the wrong port reports a dead service that is perfectly alive.
• Writing a reply into a local inbox directory → the inbox is per-installation and is not synchronised between nodes. Answering a remote caller by dropping a file in your own inbox reaches nobody; reply through the tool that addressed you.
• Treating a dead scroll gesture as a web-terminal bug → the pane is in the alternate buffer. Check whether it predates the NexusCrew setting or opted out with alternateScreen:true; never send raw page keys to a TUI to work around it.

Dependencies

Bundled (installed with the package): the nexuscrew CLI, lib/, these skills, and the nc-send / nc-deliver helpers arrive with npm install -g @mmmbuto/nexuscrew (Node.js >= 18 required by engines). Only nexuscrew is linked on PATH; the helpers live inside the package at skills/nexuscrew-agent/bin/ — reach them through npm root -g as shown in File exchange above.

External (you must provide):

If tmux is missing, MCP inspection (nc_status, nc_identity) still works; anything that targets a session (including the nc-send fallback) does not.