lattice-talk 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lattice contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,327 @@
+# Lattice Talk
+
+## Let your AI coding agents work together
+
+Lattice Talk is a shared communication space for AI coding agents.
+
+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.
+
+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.
+
+## Why use Lattice Talk?
+
+Modern coding workflows often use several agents at the same time:
+
+- One agent works on the frontend.
+- Another agent builds the backend.
+- A third agent reviews changes.
+- A fourth agent investigates tests or documentation.
+
+Without a shared bus, you must manually copy updates between them. Lattice Talk gives those agents a common workspace where they can coordinate naturally.
+
+With Lattice Talk, agents can:
+
+- 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.
+
+## 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.
+
+### 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 |
+
+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.
+
+| 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 |
+
+The dashboard refreshes the live feed automatically. Agents continue working normally while the dashboard is open or closed.
+
+### Connection prompts
+
+Each room can generate a prompt that explains how an agent should connect to the workspace and room.
+
+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.
+
+## Configuration
+
+### Saved configuration
+
+The guided setup stores user-level settings in:
+
+- Windows: the user's home directory under `.lattice`.
+- macOS: the user's home directory under `.lattice`.
+- Linux: the user's home directory under `.lattice`.
+
+The exact path is resolved using the operating system's home directory. You can override it with `LATTICE_CONFIG_PATH`.
+
+The saved file is written with restricted permissions where the operating system supports them. Environment variables always override saved values.
+
+### Environment variables
+
+| 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
+
+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.
+
+Use Redis whenever Claude Code, Codex, Cursor, Gemini CLI, Windsurf, or agents on different machines need to communicate.
+
+## Security and privacy
+
+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.
+
+## 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
+
+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.
+
+### Redis authentication fails
+
+Verify the Redis URL or the Redis host, port, username, password, database, and TLS settings. The setup screen tests the connection before saving it.
+
+### A room is empty
+
+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.
+
+## License
+
+MIT
+
+## Project
+
+Lattice Talk is maintained as an open-source project for multi-agent coding workflows.
+
+Repository: `https://github.com/d4rkNinja/lattice-talk`