npm package: @liteio/bridge
Description: MCP bridge for agent.liteio.dev. Connects Claude Code to Telegram, Slack, and agent memory.
Latest version: 0.2.4

# @liteio/bridge

Give Claude Code a persistent memory, a unique identity, and real-time messaging from Telegram and Slack.

## Why

Claude Code is powerful, but each session starts from scratch. It forgets what you told it yesterday, has no way to receive messages while you are away, and cannot talk to anyone outside your terminal.

This bridge fixes that. After a one-time setup, your Claude Code session can:

- **Remember things** across sessions, projects, and machines
- **Receive and reply to Telegram messages** in real time
- **Receive and reply to Slack DMs and mentions** in real time
- **Track goals** and report status
- **Have an identity** with a unique name (like `quick-steel-lemur`)

Everything is stored on [agent.liteio.dev](https://agent.liteio.dev) and synced to every Claude Code session you open.

## How it works

```
                       stdio                 HTTPS / WebSocket
  +--------------+  <--------->  +--------+  <--------------->  +-------------------+
  |  Claude Code |               | bridge |                     | agent.liteio.dev  |
  +--------------+  <--------->  +--------+  <--------------->  +-------------------+
                    MCP tools      local                          |             |
                    + channels     process                        v             v
                                                             Telegram        Slack
```

The bridge runs as a local process on your machine. It connects to Claude Code over stdio and to agent.liteio.dev over the network. Telegram and Slack messages arrive through agent.liteio.dev and are pushed into your Claude Code session as [channel notifications](https://code.claude.com/docs/en/channels-reference.md).

The bridge must run locally because Claude Code can only receive channel notifications from a local [MCP server](https://code.claude.com/docs/en/mcp.md) on stdio.

## Getting started

You need [Claude Code](https://claude.ai/code) and either [Node.js](https://nodejs.org) 18+ or [Bun](https://bun.sh).

### Step 1: Install skills

Run the bridge once to install the setup [skills](https://code.claude.com/docs/en/skills.md):

```bash
npx -y @liteio/bridge
```

Or with Bun:

```bash
bunx @liteio/bridge
```

This copies three skills to `~/.claude/skills/`, making the `/agent-setup`, `/agent-setup-telegram`, and `/agent-setup-slack` commands available in Claude Code. You can close the process after you see `[bridge] MCP server started on stdio`.

### Step 2: Start Claude Code with the agent channel

```bash
claude --dangerously-load-development-channels server:agent
```

The [`--dangerously-load-development-channels`](https://code.claude.com/docs/en/channels.md#research-preview) flag is required during the [Channels research preview](https://code.claude.com/docs/en/channels.md). It tells Claude Code to load the bridge as a development channel.

### Step 3: Run setup

Inside Claude Code, type:

```
/agent-setup
```

This registers a new agent, creates an auth token, and saves the config to `~/.claude.json`. Because this is a [user-level config](https://code.claude.com/docs/en/mcp.md), the bridge auto-starts in every future Claude Code session from any directory.

After setup, restart Claude Code. You should see:

```
[bridge] Loaded tools from https://agent.liteio.dev
[bridge] Connected to https://agent.liteio.dev
Bridge connected. Listening for messages.
```

### Step 4: Connect Telegram or Slack (optional)

```
/agent-setup-telegram
```

or

```
/agent-setup-slack
```

Follow the pairing instructions. Once paired, messages sent to your bot appear inside Claude Code in real time.

## What you can do

| Capability | How |
|------------|-----|
| Store and recall information across sessions | Ask Claude to remember something, or use the memory tools directly |
| Check your agent identity and profile | `/agent-setup` shows your name; `agent_reflect` returns your full profile |
| Set and track goals | Tell Claude your goals; it keeps a running list |
| Report what you are working on | Claude can update your status so other tools can query it |
| Receive and reply to Telegram messages | Pair with `/agent-setup-telegram`, then messages appear in your session |
| Receive and reply to Slack DMs and mentions | Pair with `/agent-setup-slack`, then messages appear in your session |

## Configuration

The `/agent-setup` skill writes this to `~/.claude.json`:

```json
{
  "mcpServers": {
    "agent": {
      "command": "npx",
      "args": ["-y", "@liteio/bridge"],
      "env": {
        "AGENT_URL": "https://agent.liteio.dev",
        "AGENT_AUTH_TOKEN": "agt_..."
      }
    }
  }
}
```

You do not need to edit this file manually. If you prefer Bun, replace `"npx"` with `"bunx"` and `["-y", "@liteio/bridge"]` with `["@liteio/bridge"]`.

| Variable | Default | Description |
|----------|---------|-------------|
| `AGENT_URL` | `https://agent.liteio.dev` | The server URL |
| `AGENT_AUTH_TOKEN` | (none) | Your auth token, created by `/agent-setup` |

## Multiple sessions

Each Claude Code session spawns its own bridge process. All bridges connect to the same server, so each session receives messages independently. This is expected.

## Troubleshooting

**`command not found: bridge`**
Clear the npm cache and try again:

```bash
npm cache clean --force && npx -y @liteio/bridge
```

**`ENOENT: no such file or directory, uv_cwd`**
Your terminal's current directory was deleted. Switch to a valid directory first:

```bash
cd ~ && npx -y @liteio/bridge
```

**Bridge starts but loads 0 tools**
The `AGENT_AUTH_TOKEN` is missing or invalid. Run `/agent-setup` again.

**No messages arriving from Telegram or Slack**
Make sure you completed the pairing step with `/agent-setup-telegram` or `/agent-setup-slack`. The bot must be paired to your agent before messages are forwarded.

## Links

- [Claude Code](https://claude.ai/code)
- [MCP servers](https://code.claude.com/docs/en/mcp.md)
- [Channels](https://code.claude.com/docs/en/channels.md)
- [Channels reference](https://code.claude.com/docs/en/channels-reference.md)
- [Skills](https://code.claude.com/docs/en/skills.md)