Tell

Install

Get started with the Tell Protocol tooling. All packages require Node.js 20+.

Prerequisites: Node.js 20+ and npm (included with Node.js). Verify with node --version.

Quickstart

Install the CLI globally and initialise your first portfolio in seconds.

$ npm install -g @tell-protocol/cli
$ tell init --name "My Portfolio" --org "My Org"
$ tell bet add "Users prefer AI summaries" --horizon 6m
$ tell status

What happens

  • 1tell init creates a .tell/ directory with your portfolio file, evidence store, and version history.
  • 2tell bet add adds your first strategic bet — a falsifiable hypothesis your organisation is testing with real resources.
  • 3tell status shows a health overview of your portfolio: bet counts, assumption states, and evidence totals.

Packages

@tell-protocol/cli(binary: tell)

Command-line tool for managing strategic portfolios

$ npm install -g @tell-protocol/cli

@tell-protocol/mcp-server(binary: tell-mcp)

MCP server exposing Tell tools to AI agents

$ npm install -g @tell-protocol/mcp-server

@tell-protocol/core

Types, algorithms, and store interface for building Tell-compatible tools

$ npm install @tell-protocol/core

@tell-protocol/schema

JSON Schema definitions and validation for Tell documents

$ npm install @tell-protocol/schema

MCP Server Setup

Configure the Tell MCP server for your AI agent.

Claude Desktop

Add to your claude_desktop_config.json:

claude_desktop_config.json
{
  "mcpServers": {
    "tell": {
      "command": "tell-mcp",
      "env": {
        "TELL_DIR": "/path/to/your/project/.tell"
      }
    }
  }
}

Claude Code

Add to your project's .mcp.json:

.mcp.json
{
  "mcpServers": {
    "tell": {
      "command": "tell-mcp"
    }
  }
}

Library Usage

Build Tell-compatible tools with the core library.

TypeScript
import { InMemoryStore, generateId, nowISO } from '@tell-protocol/core'
import { serialize } from '@tell-protocol/core'

const store = new InMemoryStore()
const bet = await store.addBet({
  thesis: 'Users prefer AI summaries',
  status: 'active',
  assumptions: [],
})
const asm = await store.addAssumption(bet.id, {
  statement: 'Users engage 3x more with summaries',
})
const portfolio = await store.getPortfolio()
const json = serialize(portfolio)  // → valid .tell.json

Next steps

Now that you have the tooling installed, learn how to model your organisation's strategic intent.

Getting Started GuideCLI ReferenceFull Specification