lattice-talk 0.1.2 → 0.1.3

package/README.md

@@ -1,327 +1,134 @@
 # Lattice Talk
 
-## Let your AI coding agents work together
+**Let your AI coding agents talk to each other.**
 
-Lattice Talk is a shared communication space for AI coding agents.
+Lattice Talk is a shared communication bus for AI coding agents. It connects agents running in Claude Code, Codex, Cursor, Gemini CLI, Windsurf, and any other MCP-compatible harness — so a frontend agent, a backend agent, and a reviewer can coordinate in real time instead of you copying messages between windows.
 
-It connects agents running in Claude Code, Codex, Cursor, Gemini CLI, Windsurf, and other MCP-compatible tools. Agents can discover one another, send direct messages, talk in named rooms, and share project memory without copying context between windows.
+Everything runs on your own Redis instance. There is no hosted Lattice service and no account to create.
 
-Lattice Talk runs locally and uses your Redis instance as the shared communication layer. It does not require a hosted Lattice account or a central Lattice service.
+## Quick start
 
-## Why use Lattice Talk?
+1. **Open the dashboard** — run `npx -y lattice-talk` in a terminal.
+2. **Guided setup** — enter your Redis URL, pick a namespace and workspace name, optionally set a join token. The connection is tested before anything is saved.
+3. **Install into your harnesses** — run `npx -y lattice-talk mcp add claude` (or `codex`, `gemini`, `cursor`, `windsurf`, or `all`).
+4. **Restart your harness**, then create a room in the dashboard and press `p` to copy the agent prompt — paste it into an agent session and it joins the room and starts talking.
 
-Modern coding workflows often use several agents at the same time:
+That's it. Agents in the same workspace can now DM each other, talk in rooms, and share memory.
 
-- One agent works on the frontend.
-- Another agent builds the backend.
-- A third agent reviews changes.
-- A fourth agent investigates tests or documentation.
+## What agents can do
 
-Without a shared bus, you must manually copy updates between them. Lattice Talk gives those agents a common workspace where they can coordinate naturally.
+Once connected, each agent gets MCP tools to:
 
-With Lattice Talk, agents can:
+- Join and leave workspaces, and see who else is online
+- Send direct messages to a specific agent
+- Post to and read named rooms
+- **Receive messages instantly** — agents can wait on `pull_messages` and get woken the moment a message is published, rather than polling on a timer
+- Create and join rooms
+- Read and write shared memory and append-only notes
+- Inspect session info and OpenTelemetry trace context
 
-- Find other agents working in the same workspace.
-- Send private messages to a specific agent.
-- Talk in rooms dedicated to a feature, task, or team.
-- Share persistent project memory and notes.
-- Coordinate work across processes and machines.
-- Keep optional OpenTelemetry traces for debugging and observability.
+## The dashboard
 
-## What you get
-
-### A friendly terminal dashboard
-
-The Lattice Talk dashboard lets you:
-
-- Create named workspaces.
-- Create, open, and delete rooms.
-- Watch live agent conversations.
-- See which agents are currently online.
-- Move between rooms without restarting anything.
-- Copy a ready-to-use connection prompt for an agent.
-- Reconfigure the Redis connection when needed.
-
-The dashboard is view-only. It observes the bus without joining as an agent, so it does not appear as a participant in your agent list.
-
-### MCP tools for agents
-
-Connected agents receive tools for:
-
-- Joining and leaving workspaces.
-- Discovering peers.
-- Sending direct messages.
-- Posting and reading room messages.
-- Creating and joining rooms.
-- Saving and reading shared memory.
-- Adding and reading shared notes.
-- Reading session and trace information.
-
-## Installation
-
-Lattice Talk supports Windows, macOS, and Linux.
-
-### Requirements
-
-| Requirement | Purpose |
-| --- | --- |
-| Node.js 20 or newer | Runs the MCP server used by agent harnesses |
-| Redis | Shares messages between separate agent processes |
-| Bun, or Node.js 26.4 or newer | Runs the interactive terminal dashboard |
-
-The MCP server works with regular Node.js 20+. The dashboard uses OpenTUI, which currently requires Bun or Node.js 26.4 or newer.
-
-Redis can run locally, in Docker, on another machine, or through a managed Redis provider. Every agent must be able to reach the same Redis instance.
-
-### Recommended user flow
-
-1. Install or launch the `lattice-talk` npm package.
-2. Open the guided setup dashboard.
-3. Enter the Redis connection details and choose a workspace.
-4. Add Lattice Talk to one or more agent harnesses.
-5. Open the dashboard to create rooms and monitor conversations.
-6. Use the room prompt when you want another agent to join.
-
-The setup screen stores user-level settings in the Lattice configuration directory. Environment variables always take priority over saved settings.
-
-## Installation options
-
-### npm and npx
-
-For a published npm release, users can launch Lattice Talk through npm or npx without manually cloning the repository. The MCP harness installer generates the correct command for the operating system automatically.
-
-### Install from the repository
-
-For development, testing, or an unreleased version, clone the repository, install dependencies, and build the package locally. The generated MCP configuration can then point to the local package build.
-
-## First-time setup
-
-Start the guided setup from a terminal. It asks for four values:
-
-### Redis URL
-
-The address of the Redis server used by all agents.
-
-Examples include local Redis, a TLS Redis connection, or a remote Redis provider. If your organization uses separate Redis environment variables instead of a URL, those are also supported.
-
-### Namespace
-
-A namespace separates independent Lattice environments that use the same Redis server.
-
-For example, you can use one namespace for development, another for staging, and another for a personal workspace. The default namespace is `dev`.
-
-### Workspace
-
-A workspace is the shared session where agents meet. Rooms are created inside the workspace.
-
-The dashboard lets you switch workspaces or create a new one at any time. Agents should use the same workspace name when joining.
-
-### Join token
-
-A join token is optional. Use one when you want only authorized processes to join or inspect a workspace.
-
-The token is never accepted through an MCP tool. It must be provided through the local process environment or the saved local configuration.
-
-## Adding Lattice Talk to agent harnesses
-
-Use the MCP installer from the terminal.
-
-| Command | Purpose |
-| --- | --- |
-| `mcp add claude` | Add Lattice Talk to Claude Code |
-| `mcp add codex` | Add Lattice Talk to Codex |
-| `mcp add gemini` | Add Lattice Talk to Gemini CLI |
-| `mcp add cursor` | Add Lattice Talk to Cursor |
-| `mcp add windsurf` | Add Lattice Talk to Windsurf |
-| `mcp add all` | Add Lattice Talk to every supported harness |
-| `mcp list` | Show installation status |
-| `mcp remove <harness>` | Remove Lattice Talk from one harness |
-
-The full command prefix is `lattice-talk mcp`.
-
-The installer updates each harness's existing configuration instead of replacing it. Existing MCP servers and unrelated settings are preserved.
-
-After installation, restart the affected harness so it reloads its MCP configuration.
-
-### Existing credentials are reused
-
-When you run the installer, it automatically uses the credentials already available from:
-
-- Your current environment variables.
-- Your saved Lattice configuration.
-- Your existing Redis host and authentication variables.
-
-You should not need to enter the Redis password or join token again for every harness. The generated harness configuration receives the resolved values needed by its local Lattice Talk process.
-
-Credentials are kept out of MCP tool arguments. Treat local harness configuration files as sensitive because they may contain connection credentials.
-
-## Using the dashboard
-
-The dashboard opens in three main areas.
-
-### Setup screen
-
-Use the setup screen to enter or update Redis, namespace, workspace, and join-token settings. Lattice Talk checks the Redis connection before saving the configuration.
+Running `lattice-talk` with no arguments opens the dashboard. It is **view-only** — it watches the bus without joining as an agent, so it never appears in your agent list.
 
 ### Rooms screen
 
-The rooms screen shows the rooms in the active workspace and the number of members in each room.
-
-Available actions include:
-
 | Key | Action |
 | --- | --- |
-| Up / Down or J / K | Move through rooms |
-| Enter | Open the selected room |
-| N | Create a room |
-| D | Delete the selected room |
-| P | Show the agent connection prompt |
-| W | Switch or create a workspace |
-| S | Return to setup |
-| Q | Quit the dashboard |
+| `↑` `↓` or `j` `k` | Move through rooms |
+| `Enter` | Open the selected room |
+| `n` | Create a room |
+| `d` | Delete the selected room |
+| `p` | Show the agent connection prompt |
+| `w` | Switch or create a workspace |
+| `s` | Return to setup |
+| `q` | Quit |
 
-Room deletion removes the room's message history, membership list, and room read cursors. It does not delete the workspace or other rooms.
-
-### Room screen
-
-The room screen shows a live feed of messages and an online agent list.
+### Room screen (live feed)
 
 | Key | Action |
 | --- | --- |
-| Left / Right | Move between rooms |
-| Up / Down | Scroll the message feed |
-| F | Follow the newest messages |
-| P | Show the room connection prompt |
-| B or Escape | Return to the rooms screen |
+| `←` `→` | Switch between rooms |
+| `↑` `↓` | Scroll the message feed |
+| `f` | Follow the newest messages |
+| `p` | Show the room connection prompt |
+| `b` / `Esc` | Back to rooms |
 
-The dashboard refreshes the live feed automatically. Agents continue working normally while the dashboard is open or closed.
+The feed updates the instant a message is published — it subscribes to Redis notifications rather than polling — and shows every agent's online status live.
 
 ### Connection prompts
 
-Each room can generate a prompt that explains how an agent should connect to the workspace and room.
+Every room can generate a ready-to-paste prompt telling an agent exactly how to join the workspace and room. The prompt never contains your Redis password or join token — for protected workspaces it just tells the agent its process needs the matching `LATTICE_JOIN_TOKEN`.
 
-The prompt does not contain your Redis password or join token. If the workspace is protected, it tells the agent that its MCP process needs the matching local join-token environment variable.
+## Commands
 
-## Configuration
+| Command | What it does |
+| --- | --- |
+| `lattice-talk` | Opens the dashboard (in a terminal). Piped/non-interactive: runs the MCP server, so old configs keep working |
+| `lattice-talk setup` | Guided setup — Redis URL, namespace, workspace, join token |
+| `lattice-talk serve` | Runs the MCP stdio server explicitly (what harnesses spawn) |
+| `lattice-talk mcp add <harness>` | Installs the server into `claude`, `codex`, `gemini`, `cursor`, `windsurf`, or `all` |
+| `lattice-talk mcp list` | Shows which harnesses have Lattice Talk installed |
+| `lattice-talk mcp remove <harness>` | Removes it from a harness |
+
+The installer **merges** into each harness's existing MCP config — your other servers and settings are preserved. It also reuses credentials already set in your environment or saved config, so you don't re-enter Redis details per harness. On Windows it correctly uses `npx.cmd`; on macOS/Linux, `npx`.
 
-### Saved configuration
+After adding, restart the harness so it reloads its MCP config.
 
-The guided setup stores user-level settings in:
+## Requirements
 
-- Windows: the user's home directory under `.lattice`.
-- macOS: the user's home directory under `.lattice`.
-- Linux: the user's home directory under `.lattice`.
+| Requirement | Needed for |
+| --- | --- |
+| Node.js 20+ | The MCP server (`serve`) that harnesses run |
+| Redis | Sharing messages between agent processes — local, Docker, remote, or managed |
+| Bun, or Node.js 26.4+ | The interactive dashboard (OpenTUI renders via native FFI) |
 
-The exact path is resolved using the operating system's home directory. You can override it with `LATTICE_CONFIG_PATH`.
+The dashboard auto-detects a compatible runtime and tells you clearly if none is found. The MCP server itself needs only plain Node 20+.
 
-The saved file is written with restricted permissions where the operating system supports them. Environment variables always override saved values.
+## Configuration
 
-### Environment variables
+Setup writes user-level settings to `~/.lattice/config.json` (restricted permissions; override the location with `LATTICE_CONFIG_PATH`). Environment variables always win over saved values.
 
 | Variable | Default | Purpose |
 | --- | --- | --- |
-| `LATTICE_REDIS_URL` | None | Redis connection URL |
-| `LATTICE_NAMESPACE` | `dev` | Separates independent environments |
-| `LATTICE_DEFAULT_SESSION_ID` | None | Optional default workspace for non-interactive MCP clients |
-| `LATTICE_JOIN_TOKEN` | None | Optional authorization token |
-| `LATTICE_STORE` | `redis` | Selects Redis or in-process memory storage |
-| `LATTICE_PRESENCE_TTL` | `45` | Seconds before inactive agent presence expires |
-| `LATTICE_STREAM_MAXLEN` | `1000` | Approximate message retention limit |
-| `LATTICE_CONFIG_PATH` | User home `.lattice/config.json` | Overrides the saved configuration location |
-| `LATTICE_TUI_RUNTIME` | Automatic detection | Overrides the dashboard runtime executable |
-| `OTEL_EXPORTER_OTLP_ENDPOINT` | None | Optional OpenTelemetry endpoint |
-| `OTEL_SERVICE_NAME` | `lattice-talk` | OpenTelemetry service name |
-| `OTEL_EXPORTER_OTLP_HEADERS` | None | Optional OpenTelemetry headers |
-
-Redis can also use these variables when a URL is not supplied:
-
-- `REDIS_HOST`
-- `REDIS_PORT`
-- `REDIS_USERNAME`
-- `REDIS_PASSWORD`
-- `REDIS_DB`
-- `REDIS_SSL`
-
-### Memory storage
+| `LATTICE_REDIS_URL` | — | Redis connection URL |
+| `LATTICE_NAMESPACE` | `dev` | Isolates independent environments on one Redis |
+| `LATTICE_DEFAULT_SESSION_ID` | — | Default workspace for non-interactive MCP clients |
+| `LATTICE_JOIN_TOKEN` | — | Optional token gating joins and reads |
+| `LATTICE_STORE` | `redis` | `redis` or `memory` (single-process testing) |
+| `LATTICE_PRESENCE_TTL` | `45` | Seconds before an inactive agent shows offline |
+| `LATTICE_STREAM_MAXLEN` | `1000` | Approximate per-stream message retention |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | — | Optional OpenTelemetry export endpoint |
 
-In-process memory storage is available for local testing. It is not suitable for real multi-agent communication because separate processes cannot see one another's memory store.
+Without `LATTICE_REDIS_URL`, legacy Redis variables also work: `REDIS_HOST`, `REDIS_PORT`, `REDIS_USERNAME`, `REDIS_PASSWORD`, `REDIS_DB`, `REDIS_SSL`.
 
-Use Redis whenever Claude Code, Codex, Cursor, Gemini CLI, Windsurf, or agents on different machines need to communicate.
+## Security model
 
-## Security and privacy
+- Agent identity is owned by the joined MCP process — a model can't claim another agent's id on later calls.
+- An `agent_id` can't be claimed while its presence is live.
+- Join policy is fixed at workspace creation: open, or token-gated (only the token's hash is stored — never the token itself).
+- Secrets live only in environment variables, never in MCP tool arguments.
+- Rooms are membership-scoped; DMs go only to the recipient's channel.
+- Logs go to stderr, keeping stdout clean for MCP JSON-RPC.
 
-Lattice Talk is designed for local, process-to-process communication.
-
-- Agent identity belongs to the MCP process that joined the workspace.
-- Later tool calls cannot replace that process-owned identity with a model-supplied identity.
-- Active agent identities cannot be claimed by another live process.
-- Join tokens are checked for both joining and protected inspection.
-- Only a hash of the join token is stored in the session metadata.
-- Redis passwords and join tokens are not part of MCP tool schemas.
-- Room access is membership-scoped.
-- MCP logs go to stderr so stdout remains available for JSON-RPC traffic.
-
-Do not place passwords, API keys, or other sensitive information in room messages or shared memory.
-
-## OpenTelemetry
-
-OpenTelemetry support is optional. When configured, Lattice Talk can export traces to an OTLP endpoint and correlate activity using the workspace session ID.
-
-Tracing is useful when you need to understand how work moved between agents, investigate slow operations, or inspect a multi-agent workflow.
+Don't paste passwords, API keys, or secrets into messages or shared memory.
 
 ## Troubleshooting
 
-### The dashboard does not open
-
-Install Bun or use Node.js 26.4 or newer for the OpenTUI dashboard. The MCP server can still run with Node.js 20 or newer through the explicit `serve` command.
-
-### Agents cannot see each other
-
-Check that every harness uses:
-
-- The same Redis server.
-- The same namespace.
-- The same workspace or session.
-- The same join token when the workspace is protected.
-
-Also restart the harness after changing its MCP configuration.
-
-### The installer asks for Redis configuration again
+**Dashboard won't open** — install Bun, or Node.js 26.4+. `serve` still works on Node 20+.
 
-The installer reads the current environment first and then the saved Lattice configuration. Confirm that the variables are exported in the same terminal where the installer is run, or complete the guided setup once.
+**Agents can't see each other** — confirm every harness uses the same Redis, namespace, and workspace name, and the same `LATTICE_JOIN_TOKEN` if the workspace is protected. Restart the harness after changing MCP config.
 
-### Redis authentication fails
+**A room is empty** — the agent hasn't joined it. Press `p` on the room, paste the prompt into that agent's session; it will join the workspace and room.
 
-Verify the Redis URL or the Redis host, port, username, password, database, and TLS settings. The setup screen tests the connection before saving it.
+**Redis auth fails** — re-check the URL or host/port/user/password/TLS. The setup screen tests the connection before saving.
 
-### A room is empty
+## Links
 
-The agent may not have joined that room yet. Open the room prompt from the dashboard and give it to the agent. The agent must join the workspace and then join the room before it can participate.
-
-## Development
-
-The repository includes TypeScript source, MCP contract tests, memory-store tests, Redis integration tests, CLI tests, and a built stdio smoke test.
-
-The project uses npm for the Node-side build and Vitest for automated tests. The interactive dashboard uses OpenTUI with React and is run through Bun or a compatible Node runtime.
-
-Redis integration tests require an available Redis server. Other tests use the in-process store and do not require Redis.
-
-## Package contents
-
-The npm package contains:
-
-- The cross-platform `lattice-talk` CLI.
-- The Node-compatible MCP stdio server.
-- The OpenTUI dashboard bundle.
-- Harness installers for Claude Code, Codex, Gemini CLI, Cursor, and Windsurf.
-- Shared workspace, room, messaging, memory, and presence functionality.
+- npm: `lattice-talk` — https://www.npmjs.com/package/lattice-talk
+- Repository: https://github.com/d4rkNinja/lattice-talk
+- MCP compatibility notes: `docs/mcp-compatibility.md`
 
 ## License
 
 MIT
-
-## Project
-
-Lattice Talk is maintained as an open-source project for multi-agent coding workflows.
-
-Repository: `https://github.com/d4rkNinja/lattice-talk`