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. No public hosted endpoint is available yet.
• An interactive client with MCP form support. Unsupported clients fail closed for access changes.

Install

Version 0.4.0 is published on PyPI. Install with pipx (Python 3.11+):

pipx install niva-connector==0.4.0

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. Google Cloud backend configuration is prepared, not deployed; obtain your operator's reachable HTTPS API URL before remote collaboration. 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 a backend already running on your own computer:

niva setup claude --server http://localhost:8000
# or
niva setup codex --server http://localhost:8000

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 http://localhost:8000.

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. 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 Alice.” Approve the named tool if the host asks, then review and approve Niva's native form. Share the private invitation only with your teammate.

In Codex, review/trust the four installed Niva lifecycle hooks at startup or in /hooks. Ask: “Join this Niva room as Bob: [invitation]” and approve the native form. You do not need to manually write hooks or open a website.

Names are self-selected, not verified identities. Invitations are single-use and expire after 24 hours. Neither the installer nor the connector collects your provider sign-in credentials.

Collaborate and stop

Ask Alice to send a selected question through Niva; ask Bob 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.