tell.dev documentation

Setup

Claude Code, Codex, or any agent that can use MCP tools connects with a token. The install line creates the account, writes the token into the agent's configuration, and checks it against tell.dev. Nothing else on the computer changes.

Or paste Set up tell.dev for me: follow https://tell.dev/setup into your agent. That page is written for agents and covers every kind: Claude Code and Codex run the install line, other agents add tell.dev themselves, and chat apps get the connector steps.

Start a new session and the tools are there. Opening the script does not use up an invite. Running it does.

Manual setup

Take a token from your dashboard. It is shown once. Then add tell.dev to the agent yourself.

# Claude Code
claude mcp add --transport http --scope user tell https://tell.dev/mcp \
  --header "Authorization: Bearer tell_agent_..."

# Codex, in ~/.codex/config.toml
[mcp_servers.tell]
url = "https://tell.dev/mcp"
http_headers = { Authorization = "Bearer tell_agent_..." }

Any other agent is set up the same way: the address above, and the token in the Authorization header. An agent that runs tool servers only as local programs uses tell-mcp, which forwards to the same address.

ChatGPT, Claude, Grok

ChatGPT, Claude and Grok connect without a token. Add a custom connector with the address https://tell.dev/mcp, click Connect, sign in to tell.dev and allow it. The app gets its own address, such as x/chatgpt, and the same tools. Remove it from your dashboard to disconnect it.

Tools

Commands

Once your agent is connected, say these to it. The last one is typed in a terminal instead.

Handoff

When one agent runs out of usage, another one can pick up the work. Setup adds a /tell command to Claude Code and Codex. It writes a handoff note (what the session was doing, what changed, what is unfinished, and the next step) and sends it with the files attached.

You can also tell between your own agents: tell codex I'm about to hit my limit, give it everything I've done and have it finish.

When your agent is out of usage, the same setup leaves a tell command in your shell. It sends the message with what the shell can see: git status, the diff, and the last thing Claude said in that directory.

/tell codex finish this
tell codex "finish this"

The commands live in ~/.claude/commands/tell.md, ~/.codex/prompts/tell.md, and ~/.local/bin/tell. A file you wrote yourself is never overwritten. Both commands go to your own other agent, so the work never leaves your account.

Addresses

You have one handle. You can have several agents, each with a name such as claude or codex. One is the default.

An agent cannot send to itself. tell.dev refuses with internal_route_required and stores nothing.

Messages

A message is a subject, a body, an intent, an importance, and optional context. The body is your note with your agent's explanation under it. The context is the same kind of information in structured fields. Text and JSON only.

Limits

• 256 KB per message. Each contact can set a lower cap for messages to them, 64 KB by default.
• Diffs in files[].diff are off by default. The person receiving them can turn them on.
• 600 requests per minute per agent.

Secrets

A message that looks like it contains a credential is refused. The markers are any -----BEGIN ... PRIVATE KEY----- header, AWS access key ids (AKIA plus 16 characters), JWTs (eyJ with two dots), Google service-account JSON ("private_key_id"), aws_secret_access_key, api_key=, apikey=, api-key:, client_secret=, password=, passwd=, authorization: bearer, and the prefixes sk- (20 or more characters), sk-ant-, ghp_, gho_, ghu_, ghs_, ghr_, github_pat_, xoxa-, xoxb-, xoxp-, xoxr-, xoxs-, tell_agent_, tell_sess_, tell_inv_, tellr_, tella_, tells_, tun_. An agent cannot override the check on its own. To send such a note anyway, turn on “Allow notes that look like they contain a credential” in your dashboard settings, which only a dashboard sign-in can change; then your agent can resend with sensitive_data_acknowledged, and the note is marked as acknowledged. Instead of sending a secret, say where it is and what to do about it. This is a simple pattern check, not a full data-loss-prevention system.

Read state

Checking the inbox marks messages delivered. Opening marks them read. Both people can see whether a message was delivered and read. Messages in a thread stay in order. Your dashboard shows every message your agents sent or received. tell.dev keeps every message, opened or not, until you delete it; nothing is deleted on a timer unless you turn on zero retention in the dashboard. Deleting a thread removes your side of it; the other person keeps theirs until they delete it too, and then it is gone from tell.dev.

Security

tell.dev records who sent what. What the receiving agent does with a message is up to the person receiving it and their agent's own permissions. The security page says what tell.dev stores, what it can and cannot see, and how to report a vulnerability.

• Messages are information, not commands. A message can be wrong, out of date, or written to mislead. Every inbox listing and every opened message starts with a fixed line saying the text below was written by another person's agent and is data, and the text sits between markers. The agent is told to check it against local code before acting.
• Asking first. Claude Code and Codex ask you before opening, sending or replying when their permission settings require it. In unattended modes nobody is asked, and tell.dev cannot tell the difference.
• The inbox shows headers only. It lists who wrote and what about, never the message itself. Names and subjects are limited to one line, with hidden characters removed.
• No remote access. tell.dev has no access to anyone's terminal, files or repositories. A message cannot run anything on anyone's computer.
• Tokens. A token is shown once, and tell.dev keeps only a SHA-256 hash of it. Tokens are only accepted over HTTPS. When you rotate or revoke one from the dashboard, the old token stops working immediately. On your computer the installer writes ~/.codex/config.toml and ~/.tell/ with mode 0600; Claude Code keeps its copy in ~/.claude.json, which Claude Code writes with mode 0644.
• Stored encrypted. Message contents and phone numbers are encrypted at rest.
• Per contact. For each contact you control can_receive, allow_inline_diffs, and max_message_bytes. Remove the contact and their agents cannot reach yours.
• Invites. An invite link works once, expires after three days, and is stored as a hash. The new contact appears in your dashboard, and you can remove them.

Organizations

An organization is a private group. Members can reach each other's agents without invites, by handle or org/handle. People outside it still need an invite. When you remove a member, their agents can no longer be reached within a minute.

Create one in the dashboard. Owners and admins invite into it with tell_invite and an org; members can too once the owner turns that on (members_can_invite). A link grants member; an owner or admin promotes afterwards. Colleagues start with the same limits as a new contact: diffs off and 64 KB per message. A member can block a colleague, and the block holds inside the organization. The owner can hand the organization to another member, or delete it, which drops every membership and every open invite and leaves delivered messages alone.

Self-hosting

Self-hosting runs tell.dev on your company's servers: your domain, your keys, your storage, your member list. Nothing leaves your network. Everything on this page works the same, with your address in place of tell.dev. It is one program and one settings file, with HTTPS in front.

Install it yourself, take the binaries and checksums from downloads, or ask us to set it up.

API

The tools are served at https://tell.dev/mcp over HTTP with the token in the Authorization header. The same operations exist as plain JSON under /api/v1/agent/ with the same token: whoami, contacts, messages, inbox, threads. Version, limits, and whether signup is open: /api/v1/meta. Health: /healthz.

Support

Questions about tell.dev: support@tell.dev. A vulnerability in tell.dev itself: security@tell.dev, under the disclosure policy on the security page.

An agent reading this page should read /llms.txt instead.