Documentation

Diameter is an AI-native workspace. Bring your own agent , connect any AI to your workspace via our APIs. We provide the context, you provide the intelligence.

• REST API , read and write tasks, threads, and more
• Real-Time Subscribe , WebSocket connection for live workspace events
• CLI (di) , manage your workspace from the terminal
• MCP Server (diameter-mcp) , give AI agents like Claude full access to your workspace context

Quick Start

Get up and running with Diameter in five minutes.

1. Create your account

Sign up at diameter.app/signup with your invite code. You'll need to verify your email before continuing.

2. Generate an API token

In the web app, open any shared space and go to Settings. Under API Tokens, create a new token. Copy it , you'll need it for the CLI and MCP server.

3. Install the CLI binary

curl -fsSL https://raw.githubusercontent.com/dperrera/diameter/main/scripts/install.sh | sh

This installs di into ~/.diameter/bin by default.

4. Install the MCP binary

curl -fsSL https://raw.githubusercontent.com/dperrera/diameter/main/scripts/install-mcp.sh | sh

This installs diameter-mcp into ~/.diameter/bin by default.

5. Connect your agent

For Claude Desktop, add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "diameter": {
      "command": "diameter-mcp",
      "env": {
        "DIAMETER_API_TOKEN": "your_token_here",
        "DIAMETER_API_URL": "https://diameter.app"
      }
    }
  }
}

For Claude Code, add this to ~/.claude/mcp.json:

{
  "mcpServers": {
    "diameter": {
      "command": "diameter-mcp",
      "env": {
        "DIAMETER_API_TOKEN": "your_token_here",
        "DIAMETER_API_URL": "https://diameter.app"
      }
    }
  }
}

For Codex, register the same local MCP server from the CLI:

codex mcp add diameter \
  --env DIAMETER_API_TOKEN=your_token_here \
  --env DIAMETER_API_URL=https://diameter.app \
  -- diameter-mcp

6. Try it out

Ask Claude or Codex to interact with your workspace:

• "List my spaces"
• "Create a new document in our planning space about project ideas"
• "What's the context of my workspace?"
• "Create a task to review the Q1 report"

Troubleshooting

Getting Started

Install the CLI binary

curl -fsSL https://raw.githubusercontent.com/dperrera/diameter/main/scripts/install.sh | sh

This installs di into ~/.diameter/bin by default.

Install the MCP binary

curl -fsSL https://raw.githubusercontent.com/dperrera/diameter/main/scripts/install-mcp.sh | sh

Log in

Authenticate by opening a browser-based login flow:

di login --url https://diameter.app

Verify

Confirm your session is active:

di whoami

Configure Claude Desktop for MCP

Add the Diameter MCP server to your claude_desktop_config.json:

{
  "mcpServers": {
    "diameter": {
      "command": "diameter-mcp",
      "env": {
        "DIAMETER_API_TOKEN": "your_token_here",
        "DIAMETER_API_URL": "https://diameter.app"
      }
    }
  }
}

Configure Claude Code for MCP

Add the Diameter MCP server to your ~/.claude/mcp.json:

{
  "mcpServers": {
    "diameter": {
      "command": "diameter-mcp",
      "env": {
        "DIAMETER_API_TOKEN": "your_token_here",
        "DIAMETER_API_URL": "https://diameter.app"
      }
    }
  }
}

Configure Codex for MCP

Register the local MCP server directly from the Codex CLI:

codex mcp add diameter \
  --env DIAMETER_API_TOKEN=your_token_here \
  --env DIAMETER_API_URL=https://diameter.app \
  -- diameter-mcp

Verify the saved config with codex mcp get diameter --json.

Generate an API token in the Diameter web app under Settings.

REST API

All endpoints require a Bearer token with appropriate scopes. Base URL: https://api.diameter.app

curl https://api.diameter.app/v1/tasks \
  -H "Authorization: Bearer dia_your_token_here"

Endpoints

Context Endpoints

Structured summaries designed for AI consumption , everything an agent needs in one call.

Authentication

Generate an API token in the web app under Settings. Tokens use the dia_ prefix and support scoped access.

Available scopes: spaces:read spaces:write tasks:read tasks:write threads:read threads:write events:read links:read links:write

Real-Time Subscribe

Connect via WebSocket to receive workspace events in real-time. Your agent maintains one persistent connection and sends context updates over the wire.

Connect

ws://api.diameter.app/v1/subscribe?token=dia_your_token_here

Token must have the events:read scope.

Server Messages

On connect, you receive your accessible spaces:

{
  "type": "connected",
  "userId": "usr_xxx",
  "spaces": [
    { "id": "spc_xxx", "name": "My Project", "slug": "my-project", "role": "owner" }
  ]
}

When something changes, you receive an event:

{
  "type": "event",
  "event": {
    "id": "evt_xxx",
    "spaceId": "spc_xxx",
    "spaceName": "My Project",
    "type": "created",
    "entityType": "task",
    "entityId": "tsk_xxx",
    "agentName": "Dan",
    "data": { "title": "New task" },
    "createdAt": "2026-02-20T13:55:29.376Z"
  }
}

Client Messages

Tell the server what you're focused on to filter events:

// Focus on a space (only receive events from this space)
{ "type": "focus", "spaceId": "spc_xxx" }

// Focus on a specific entity
{ "type": "focus", "spaceId": "spc_xxx", "entityType": "task", "entityId": "tsk_xxx" }

// Remove focus (receive all events)
{ "type": "unfocus" }

// Keep connection alive (5 min idle timeout)
{ "type": "ping" }

Event Types

Example

const ws = new WebSocket(
  "ws://api.diameter.app/v1/subscribe?token=dia_xxx"
);

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);

  if (msg.type === "connected") {
    // Focus on a specific space
    ws.send(JSON.stringify({
      type: "focus",
      spaceId: msg.spaces[0].id
    }));
  }

  if (msg.type === "event") {
    // React to workspace changes
    console.log(msg.event.agentName, msg.event.type, msg.event.entityType);
  }
};

// Keep alive
setInterval(() => {
  ws.send(JSON.stringify({ type: "ping" }));
}, 120_000);

CLI Reference

The di CLI gives you full access to your Diameter workspace from the terminal. All commands support --help for detailed usage.

Auth

Spaces

Tasks

Threads

Context

Global flags: --json for raw output, --api-url and --token for overriding config.

MCP Server Setup

The Diameter MCP server gives Claude, Codex, and any MCP-compatible agent direct access to your workspace. It uses stdio transport, the standard mechanism for local MCP servers.

Install the standalone binary first:

curl -fsSL https://raw.githubusercontent.com/dperrera/diameter/main/scripts/install-mcp.sh | sh

The server requires two environment variables:

• DIAMETER_API_TOKEN , your API token
• DIAMETER_API_URL , URL of your Diameter instance
• DIAMETER_COLLAB_URL , WebSocket URL of the collaboration server (optional, enables real-time editing)

See Getting Started for full configuration instructions for Claude Desktop, Claude Code, and Codex.

MCP Tools Reference

These tools are available to any MCP-connected agent. Each tool maps to a Diameter API operation.

Spaces

Tasks

Threads

Links

Context

Events

Agents

Assets

Themes

Real-Time Editing

Requires DIAMETER_COLLAB_URL. These tools connect via Y.js for live collaborative editing.

MCP Resources

MCP resources provide read-only context that agents can pull into their working memory. These URIs are available via the standard MCP resource protocol.

• diameter://spaces , List of workspaces
• diameter://whoami , Current identity
• diameter://context-guide , Guide for using context tools
• diameter://space/{id} , Specific space context
• diameter://task/{id} , Specific task context