Niva — LEGACY LOCAL CONNECTOR installation and verification for coding agents

This is the retained local connector path, not the new hosted MCP setup.
Hosted Google/email + workspace OAuth instructions: /docs on the Niva website.
Use hosted instructions only for an enabled, validated backend. Existing local
rooms and their private state must not be silently migrated or deleted.

Install Niva for the current agent in the current project. The connector includes its local stdio MCP server. Do not clone a repository or install a backend when using the legacy hosted room service. This package does not install the new hosted MCP receiver.

Minimum connector version: 0.4.3
Package: niva-connector on PyPI
Backend API: https://api.shipintoyourdevice.com
Website: https://shipintoyourdevice.com (never use this as the API)

Authorization and scope
Honor the user's installation request and existing approvals; do not ask again for routine steps they already authorized. The website's copied prompt authorizes the connector install/upgrade and project-local Niva configuration. Ask only for missing prerequisites, ambiguous project/client, conflicting settings, or system-level changes. Preserve normal sandbox, file and tool permissions. Never answer native trust or room approval forms for the user. Do not create/join/leave rooms, send messages, or launch another interactive coding agent as an installation test.

1. Inspect before installing
- Confirm the current project and whether this is Claude Code or Codex; use known session context rather than asking unnecessarily.
- Check macOS/Linux, Python 3.11+, pipx, the agent CLI, and niva --version. Windows is not supported yet.
- Locate the current Niva executable and installation method. Inspect only relevant configuration fields; never print credentials, full global settings, private room state, or invitations.
- If prerequisites are missing, explain the specific missing item and a platform-appropriate remedy. Use https://pipx.pypa.io/stable/installation/. Do not use sudo or alter global Python automatically.

2. Install or upgrade the connector
If absent:
  pipx install niva-connector==0.4.3
If an older pipx-managed version is installed:
  pipx upgrade niva-connector
Then:
  niva --version
  niva setup --help
Require 0.4.3 or newer; do not downgrade newer versions. For a virtualenv/source installation, use its existing environment rather than creating a competing pipx installation. If pipx succeeds but niva is not on PATH, locate pipx's application directory and use the verified absolute executable for this session; explain any persistent PATH change before applying it. Recheck the version of the executable that will actually run.

3. Inspect existing configuration and configure this project
Use only the matching adapter:
  niva setup claude --server https://api.shipintoyourdevice.com --preview
  niva setup codex --server https://api.shipintoyourdevice.com --preview
Run only one of those commands. Then rerun that same command without --preview.
Existing private connection state must be retained. If this project already uses another backend, stop and explain the mismatch; do not replace its state or switch endpoints silently.
Before rerunning Codex setup, inspect the Niva hooks in .codex/hooks.json: version 0.4.3 replaces matching hook entries. If they are customized or share a group with unrelated hooks, explain the conflict and preserve the original instead of overwriting it. A changed Python executable path may also require reviewed configuration repair; do not delete the whole config to get past it.
If setup exits nonzero, record its safe error and diagnose it. Do not describe a failed or partial installation as complete, suppress the error, or keep repeating an unchanged command.

4. Verify configuration and MCP startup
- Check the generated MCP command exists and that its Python environment reports the expected Niva version. A working shell niva command is not proof that the MCP configuration uses the same installation.
- Codex: check the niva-room entry in .codex/config.toml and the four lifecycle hooks (SessionStart, UserPromptSubmit, PostToolUse, Stop) in .codex/hooks.json. The hook must call niva_event on niva-room with the event and the host-expanded cwd. Preserve unrelated entries.
- Claude: verify the local plugin is enabled for this exact project using claude plugin list --json. Inspect only the Niva entry. Setup generates its MCP configuration, hooks, join skill and monitor, and registers it persistently. An MCP file merely existing is not proof of plugin registration.
- If possible, start the exact configured MCP command in a short-lived diagnostic subprocess and send only initialize and tools/list JSON-RPC requests. Confirm the server responds and advertises niva_status, niva_create_room, niva_join_room, niva_send, niva_inbox and niva_leave; Codex also exposes niva_event. Close the subprocess after discovery. Do not invoke room operations or synthetic approval responses against a real connection.
- Check GET https://api.shipintoyourdevice.com/api/ready with a bounded timeout. The free service can take about a minute to wake; at most one bounded retry is appropriate. Report backend readiness separately from local installation. Do not substitute a different server on failure.
- Startup/tool discovery does not verify hooks, approvals, or message delivery inside the real agent. Keep those results separate.

5. Finish in the native agent
If a restart is required, report "Installed and configured; restart/trust verification pending" and stop at that boundary.
- Claude: restart with plain claude from this project. Review native plugin/MCP/hook trust prompts, then invoke /niva-room:join. No --plugin-dir is required after successful persistent registration.
- Codex: restart in this project, then review and trust the four Niva hooks through the client or /hooks.
Do not approve these prompts or disable permissions on behalf of the user. Do not claim that the current session has reloaded settings without evidence.
Give this resume prompt:
  Finish verifying my existing Niva installation in this project. Check that the Niva tools are available and call niva_status only. Check any hook errors visible in this session. Do not reinstall, create or join a room, send messages, or change my existing connection. Tell me what passed and what remains unverified.
After restart, a disconnected niva_status result is normal when no room has been created. Do not create a room just to make it say connected. Report "Ready to create or join" only after actual tool availability and status succeed; report any unverified hook behavior separately.

6. Handoff
End with a short checklist: connector version, project/agent, configuration and plugin registration, MCP startup/tool discovery, backend readiness, and native-session verification. Use Passed / Pending / Blocked with actual evidence. Include only the next action the user needs, not every command already completed. If a hook fails, capture the agent/version, event and safe error code; distinguish workspace mismatch, missing host identity and competing agent processes before proposing a repair. Never delete private room state or bypass room approval to clear a hook error.

After installation, room creation and joining are separate user requests. Example: "Create a Niva room called Checkout as Teammate 1" or "Join Checkout with code 4821 7390 6258 as Teammate 2". Pass join_code to the tool as a string and preserve leading zeros; users do not need quotation marks in chat. Room access changes require the user's native approval form.

Both teammates install independently and use the same backend. Claude idle notices need the join skill and monitor; Codex checks on its next prompt. Selected messages travel through the backend, not full transcripts or provider credentials. Keep private connection state out of Git and logs.

Hosted trial: the API can sleep after 15 idle minutes. The free database has no backups and expires around November 13, 2026. Preserve important work locally. Backend readiness and automated local room flows have been verified; actual hosted two-person agent collaboration remains unverified.