---
title: Use Telereader from an agent
description: Install the Telereader skill in a coding agent (or add the MCP connector) and have it read text aloud for you.
category: api
order: 2
last_verified_at: 2026-06-22
status: published
---

# Use Telereader from an agent

Hand any text to an AI agent and have it turned into a narrated reading you can
open and listen to — the agent onboards, submits, and gives you back a URL.

There are two ways to connect, depending on your agent:

- **A coding or terminal agent** — Claude Code, Cursor, Codex, Copilot — install
  the **skill** (below).
- **A chat assistant or MCP client** — Claude, ChatGPT, and others — add the
  **MCP connector**: see [Connect Telereader over MCP](/docs/api/mcp).

## The quickest way: paste this to your agent

Hand your coding/terminal agent this — it installs the skill, reviews it, and
reads your text aloud (replace the last line with what you want read):

```text
I want to listen to something as narrated audio I can open in my browser. Please use Telereader, a tool for exactly that at telereader.ai — set it up by installing its open-source skill with `npx skills add telereaderai/skills`. Feel free to review the skill first, then use it to read the text below aloud and give me the link. Heads up: the first time, Telereader will ask me to approve a quick sign-in — when you reach that step, just share the link and I'll approve it.

---
[Paste the text, a file, or a URL you want read aloud — Telereader fetches and cleans it up for you.]
```

The wording matters: phrased as your own goal (not "install this and follow
it"), agents set it up without balking and ask you to approve the one-time
sign-in. The steps below are the same thing, by hand.

## Install the skill (coding & terminal agents)

### Requirements

- **Node 18+** (for `npx`)
- **curl** and **jq** — the skill's helper scripts use them
  (`brew install jq` or `apt install jq`; curl is usually preinstalled)

### Install

```
npx skills add telereaderai/skills
```

This installs the Telereader skill into your agent (Claude Code, Cursor, Codex,
Copilot, Cline, Windsurf, …). The skill is open source at
[`github.com/telereaderai/skills`](https://github.com/telereaderai/skills).

### Onboard once

The first time the agent reads something, the skill runs a one-time **device
login**: it prints an approval link, you approve it in your browser (signing in
if asked), and it saves a reading-scoped token to `~/.config/telereader/token`.
Re-use is automatic — you only onboard again if the token expires.

You can also run it ahead of time (the installer prints the skill's path, e.g.
`~/.config/agents/skills/telereader`):

```
<skill_dir>/scripts/onboard
```

### Use it

Just ask your agent:

> Read this aloud with Telereader.

It submits your text and hands you a **readUrl** — open it and the reading plays,
the words highlighting in sync with the narration. For a file or a long piece,
ask it to read that; the skill handles markdown and plain text.

### What's in the skill

When to use Telereader, the device-grant onboarding, the submit endpoint and
payload, how to read the response, and two helper scripts — `scripts/onboard`
and `scripts/read` — that keep your token out of command output. It points at the
canonical machine spec, [`/api/v1/openapi.json`](https://telereader.ai/api/v1/openapi.json),
so an agent can generate a client instead of hand-rolling one.

Prefer raw HTTP with no skill? See
[Read text from the command line](/docs/api/quickstart).

## Using a chat assistant instead?

Claude, ChatGPT, and other MCP clients connect with the hosted MCP connector — no
skill install, no shell. See [Connect Telereader over MCP](/docs/api/mcp) for the
per-client steps.

## What you get back

Every path ends the same way: a `readUrl`. Open it and the reading plays — text
on screen, highlighted in sync. A free account is never paywalled; it gets a URL
that generates the audio in the browser.