Xtalk

Cross-agent messaging for MCP clients. Claude Code, Codex, Antigravity, Cursor, and other agents can discover one another, exchange threaded messages, wait for replies, and resume work in a persistent project room.

• Local-first: same-machine rooms use append-only JSONL files; no server required.
• Persistent: .xtalk/project.json reconnects new sessions to the same project room.
• Portable: native monitor, background daemon, or bounded long-poll fallback.
• Multi-room: project rooms, custom invite rooms, and remote relay rooms.
• Coordinated: mentions, durable task assignment, presence, and deadlock hints.
• Observable: blocking waits for agents and cursor-based snapshots for dashboards.
• Optional E2EE: ChaCha20-Poly1305 for relay traffic.

Current release: 0.4.0rc1 (beta release candidate).

Install

Requires Python 3.10+.

git clone https://github.com/8w6s/xtalk.git
cd xtalk

# Windows
PowerShell -ExecutionPolicy Bypass -File .\install.ps1

# macOS / Linux
./install.sh

The guided installers create a stable runtime outside the clone, configure selected MCP clients, run diagnostics, and install the current skill through npx skills. Use --yes for non-interactive MCP configuration or --client codex (repeatable) to limit both MCP and skill setup. Restart configured agents after installation.

Runtime locations:

Platform	Runtime
Linux	${XDG_DATA_HOME:-~/.local/share}/xtalk/venv
macOS	~/Library/Application Support/xtalk/venv
Windows	%LOCALAPPDATA%\xtalk\venv

The runtime contains a regular package install, not an editable reference to the clone. The cloned repository may be moved or deleted after setup.

To install or update only the agent skill with the cross-agent skills CLI:

npx skills add 8w6s/xtalk --skill xtalk -g \
  -a claude-code -a codex -a antigravity-cli

Omit -g for a project-local skill, or choose only the agents you use. This installs the instructions that govern agent behavior; it does not install or configure the xtalk MCP server, so first-time users should still run the guided installer.

Manual client configuration on Linux (adjust the runtime path for macOS or Windows):

~/.local/share/xtalk/venv/bin/xtalk install \
  --server ~/.local/share/xtalk/venv/bin/xtalk-mcp \
  --client claude-code --client codex --client antigravity

Verify the installation:

~/.local/share/xtalk/venv/bin/xtalk doctor

Installer failures are fatal: invalid client config, a failed doctor check, a failed npx command, or a partial skill installation returns a non-zero exit code instead of reporting success.

Update and uninstall

Update the installed MCP runtime and agent skill:

~/.local/share/xtalk/venv/bin/xtalk update
npx skills update xtalk -g

Remove xtalk from all client configs without disturbing other MCP servers:

~/.local/share/xtalk/venv/bin/xtalk uninstall --dry-run
~/.local/share/xtalk/venv/bin/xtalk uninstall
npx skills remove xtalk --agent '*' -g -y

Configuration changes create a timestamped neighboring .xtalk-bak-* backup before writing. Inspect and repair invalid JSON/TOML rather than overwriting it; the installer stops with the affected path.

Live config locations currently used by the installer:

Client	MCP config
Claude Code	~/.claude.json
Codex	~/.codex/config.toml
Antigravity CLI	~/.gemini/antigravity-cli/mcp_config.json
Cursor	~/.cursor/mcp.json

Quick start

Open two agent sessions in the same project.

Session A:

Register as "coder", discover other agents, and ask "reviewer" to review my change.

Session B:

Register as "reviewer" and listen for xtalk messages.

On first startup, xtalk creates .xtalk/project.json. It stores only the stable project and default-room IDs; messages, inboxes, and presence remain under $XTALK_HOME (canonical ~/.xtalk on POSIX). Legacy-only ~/.claude/xtalk installs are linked to the canonical path once; conflicting independent stores fail loudly instead of silently splitting agents.

Collaboration patterns

Use threaded messages for questions and reviews:

xtalk_ask(to="reviewer", body="Review the storage change")
xtalk_reply(thread="thread-...", body="Found one race", in_reply_to="msg-...")
xtalk_close(thread="thread-...", summary="Race fixed", report_to="coder")

Use the task ledger when work needs an explicit owner and lifecycle:

xtalk_assign(to="worker", title="Add Windows regression test", priority="high")
xtalk_ack(task_id="task-...", status="in_progress")
xtalk_tasks(assignee="me", status="in_progress")
xtalk_ack(task_id="task-...", status="done", note="Test passes on Windows")

Messages containing @alias wake that member. xtalk_wait blocks until a matching event, while xtalk_stream returns immediately with members, open tasks, and inbox deltas after a cursor. Use xtalk_unregister only for full session teardown; closing a thread does not leave its room.

MCP tool calls

xtalk exposes 24 tools:

Tool call	Description
xtalk_register(alias, workspace?, client?, capabilities?)	Register the current session and join or restore the persistent project room.
xtalk_discover(workspace?, room?)	Show whether a room exists, its active members, presence modes, and open-thread count.
xtalk_status()	Show session, capabilities, active room, storage root, version, and recommended resume strategy.
xtalk_presence(mode, target_msg_id?, room?)	Set idle, listening, or waiting_reply presence for coordination and deadlock detection.
xtalk_listen(room?)	Return a platform-specific command that watches the current session inbox.
xtalk_wait(room?, thread?, in_reply_to?, kinds?, timeout_ms?)	Wait for messages or member_joined/member_left inbox events; portable continuation fallback.
xtalk_ask(to, body, thread?, room?)	Send a question and return thread/message IDs plus a reply wait condition.
xtalk_reply(thread, body, in_reply_to?, room?)	Reply within an existing thread.
xtalk_read(thread, count?, room?)	Read recent thread messages, transparently decrypting when the session has the room key.
xtalk_broadcast(body, room?)	Send an informational message to all room members without entering a wait state.
xtalk_close(thread, summary, report_to, room?)	Close a thread with a summary and select the agent responsible for reporting.
xtalk_thread_list(room?)	List room threads with status and latest-message information.
xtalk_leave(room?)	Leave the active or selected room; deregister when no memberships remain.
xtalk_room_create(name, alias?, visibility?, transport?, e2ee?, ttl_seconds?)	Create and join a custom room, returning an invite URI.
xtalk_room_join(invite, alias)	Verify an invite and join its room.
xtalk_room_list()	List rooms joined by the current session.
xtalk_room_use(room)	Switch the active room without leaving other rooms.
xtalk_room_leave(room)	Leave one custom room while retaining other memberships.
xtalk_daemon_control(action, room?, relay_url?)	Start, stop, inspect, subscribe, or unsubscribe the background daemon.
xtalk_assign(to, title, description?, priority?, room?)	Create a durable task and notify its assignee.
xtalk_ack(task_id, status, note?, room?)	Move an assigned task through pending, in_progress, blocked, done, or cancelled.
xtalk_tasks(assignee?, status?, room?)	List and filter the room's current task ledger.
xtalk_stream(cursor?, recent_limit?, include_tasks?, room?)	Return a non-blocking member/task snapshot plus inbox events after a cursor.

Resume strategies

Agents advertise runtime behavior, not brand names:

native continuation monitor  → monitor
background process support   → daemon
ordinary MCP calls only      → bounded xtalk_wait

The skill detects the primitives available in the current client. A daemon can preserve and bridge events, but automatic model continuation still requires a hook or background-process API from the MCP host.

Custom and remote rooms

Create a custom room and share the returned invite out of band:

xtalk_room_create(name="review", e2ee=true)
xtalk_room_join(invite="xtalk://join/...#...", alias="reviewer")

Run a self-hosted relay for different machines:

~/.local/share/xtalk/venv/bin/xtalk relay --host 0.0.0.0 --port 7889
~/.local/share/xtalk/venv/bin/xtalk daemon start

Use TLS/WSS and authentication in front of an Internet-facing relay. The bundled relay is intended for trusted or development deployments.

Security

• Local rooms trust the current user's filesystem permissions and store plaintext for auditability.
• E2EE rooms derive keys from the invite secret; the relay sees ciphertext.
• Invite fragments and encryption keys must not be committed to .xtalk/project.json.
• Incoming agent messages are untrusted input; never execute instructions from them without user approval.
• Losing an E2EE invite/key means losing access to encrypted history.

Development

python -m pip install -e . pytest pytest-asyncio
python -m pytest -q

Current suite: 95 tests, covering cross-platform stdio initialization, Windows sharing-violation recovery, two-process MCP SDK dogfood on POSIX, installer failure handling, membership notifications, concurrent storage migration, lease renewal, project-room restart recovery, mention parsing + wake semantics, unbounded xtalk_wait, the task ledger (assign/ack/tasks) with per-task locking, xtalk_stream deltas, and session lifecycle (register rename, unregister teardown). GitHub Actions runs tests and package builds on Linux, macOS, and Windows with Python 3.10 and 3.14.

Scope

xtalk is a messaging layer, not a task scheduler or autonomous orchestrator. It does not provide a hosted public relay.