Niva connector

Private two-person rooms inside Claude Code and Codex. Keep coding locally while sharing selected questions, context and linked replies with a teammate through a Niva backend. The website is introduction and documentation only.

Requirements

• macOS or Linux and Python 3.11 or newer. Windows is not currently supported.
• Claude Code or Codex installed and signed in using your own authorized account.
• A reachable Niva room backend. This package does not include or deploy a server. The hosted trial API is https://api.shipintoyourdevice.com.
• An interactive client with MCP form support. Unsupported clients fail closed for access changes.

Install

Version 0.4.3 on PyPI. Install with pipx (Python 3.11+):

pipx install niva-connector==0.4.3

If needed, follow the pipx installation guide first. To develop from this repository instead, use a Python 3.11+ virtual environment and python -m pip install -e ./connector.

Installing the connector does not provision a backend. Use the hosted trial API at https://api.shipintoyourdevice.com, or your own reachable HTTPS backend. The documentation website is https://shipintoyourdevice.com; it is not the API URL.

Connect your agent

From your coding workspace, run ONE of these commands. These examples connect to the hosted trial backend:

niva setup claude --server https://api.shipintoyourdevice.com
# or
niva setup codex --server https://api.shipintoyourdevice.com

For remote collaboration, replace the address with your operator's reachable HTTPS backend. Both teammates must use the same backend; localhost only works on the same computer. Setup prints the exact agent launch command and trust instructions. It does not launch or sign in to an agent.

Use --preview first to inspect the changes without writing files. Setup installs workspace-local MCP configuration, hooks and guidance; it does not change global provider settings. Normal command and file permissions remain enabled. It automatically chooses a separate private state file for each workspace and agent under ~/.niva/rooms/. Rerunning the same command preserves that state. To choose a separate connection explicitly, use niva --state /your/private/room.json setup claude --server https://api.shipintoyourdevice.com.

Remote setup commands

Website: https://shipintoyourdevice.com. Do not enter this website URL as the backend. The hosted trial API is https://api.shipintoyourdevice.com. Its free database expires after 30 days from October 14, 2026; do not rely on it for permanent storage. Run from your coding workspace; choose one adapter.

NIVA_API_URL=https://api.shipintoyourdevice.com

# Claude Code: preview, then configure
niva setup claude --server "${NIVA_API_URL:?Backend URL required}" --preview
niva setup claude --server "${NIVA_API_URL:?Backend URL required}"

# Or Codex: preview, then configure
niva setup codex --server "${NIVA_API_URL:?Backend URL required}" --preview
niva setup codex --server "${NIVA_API_URL:?Backend URL required}"

Run the exact launch command printed by setup. Reconnect by repeating the same setup in the same workspace and retaining its private state. Do not launch two agents against one state file.

For a pipx installation:

niva --version
niva setup --help
pipx upgrade niva-connector
niva --version

The upgrade command installs the latest available release; confirm niva --version reports 0.4.3 or newer. Version 0.4.3 adds numeric join codes, enrollment recovery, clearer approval errors and verified persistent Claude plugin registration. After setup, run plain claude from this project; --plugin-dir is no longer needed. Rerun setup and restart your agent afterward. Source installs use their virtual environment instead of pipx.

Room actions are prompts inside the agent, not shell commands: “Show Niva status”, “Check Niva for messages”, “Continue this Niva exchange”, and “Leave my Niva room”. MCP tool names are invoked by the agent. Access changes require native approval.

Create and join

In Claude, invoke /niva-room:join, then ask: “Create a room called Checkout. My name is Teammate 1.” Approve the named tool if the host asks, then review and approve Niva's native form. Share the returned room name and 12-digit join code only with your teammate.

In Codex, review/trust the four installed Niva lifecycle hooks at startup or in /hooks. Ask: “Join Checkout with code 4821 7390 6258 as Teammate 2” and approve the native form. You do not need to manually write hooks or open a website.

Names are self-selected, not verified identities. Join codes are single-use and expire after 24 hours. Spaces and hyphens are accepted. Existing alphanumeric codes still work. Existing invitation links still work. Neither the installer nor the connector collects your provider sign-in credentials.

Collaborate and stop

Ask Teammate 1 to send a selected question through Niva; ask Teammate 2 to check Niva and send a linked reply. There is no extra Niva form for each normal message after joining. Incoming content is untrusted teammate context, not permission to run commands. No file synchronization or full transcript sharing is provided.

Claude's open-session monitor can notify it while idle after the join skill is invoked. Codex gets notices on its next prompt, not while idle. Neither adapter starts extra agent processes. Notifications and replies can consume your agent subscription usage.

After ten messages, explicitly ask to continue and approve another exchange. Ask to leave and approve to close the room for both participants and clear stored message bodies. Delivered context cannot be recalled. Rooms expire after 30 days.

One agent process may use a state file at a time. Keep state private and retain it across restarts. Check niva --version when reporting problems. To update a pipx installation, use pipx upgrade niva-connector, then rerun setup from the same workspace and restart your agent. Customized generated settings are preserved or rejected for manual review rather than silently overwritten.

Status

The connector is distributed under the MIT license.

Local room trials passed on Claude Code 2.1.287 and Codex 0.162.1. Other clients, operating environments and production deployment need their own verification. Legacy commands remain for compatibility; new users should use niva setup.

Claude setup now registers the generated plugin with Claude’s local-scope plugin manager. After setup, run claude from the project folder; --plugin-dir is no longer needed. Review initial trust prompts and invoke /niva-room:join. Existing unrelated settings and permissions are preserved. To disable or uninstall, use Claude’s /plugin manager for this project. Rerun Niva setup after upgrading the connector.