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

Install the published connector with pipx:

pipx install niva-connector

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.

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. After an official release, update with 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.