Readless

hwjustin4stars

Let your coding agent talk: spoken summaries, progress and blocker questions for Claude Code, Cursor, Codex and any MCP agent. Free edge-tts, no API key.

Speech Voice Agents

Install Run on PlugMCP

GitHub

Run on PlugMCP

1# Readless

README.mdMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

Install from the publisher. Not a PlugMCP endpoint.

Run on PlugMCP

Host a copy with our keys and logs.

No packaged release in the registry yet. Follow the repository README.

RepositoryPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
License: Apache-2.0
Last checked: 2026-10-27

Stars: 4
Tools: —
Uptime: —

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install Readless?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Readless need an API key?

No required environment variable is listed on this record.

What transport does Readless use?

Readless runs locally over stdio.

When was Readless last checked?

Last checked 2026-10-27. Let your coding agent talk: spoken summaries, progress and blocker questions for Claude Code, Cursor, Codex and any MCP agent. Free edge-tts, no API key.

From the publisher

Documentation

readless

English · 中文

Claude Code plugin (MCP-based) that speaks status, summaries, and blocker questions out loud — so you can walk away from a long task and still know what's happening.

Three agent-callable tools:

Tool	When the agent calls it	Spoken length
`speak_summary(headline, details="")`	End of every turn, or when a user-visible task finishes	≤ 50 words
`speak_status(message)`	Mid-task heartbeat during work expected to run > 2 min (server throttles to 1/min)	≤ 10 words
`speak_blocker(question)`	Agent is stuck and needs your input. Bypasses quiet hours, interrupts current speech.	≤ 20 words

Default TTS backend is edge-tts — Microsoft's free online TTS endpoint. No API key, no signup, no model download, and the default voice zh-CN-XiaoxiaoNeural handles Chinese + English code-switching naturally. Falls back to your OS's built-in voice if the network is unreachable. Optional OpenAI / ElevenLabs backends are available if you want your own voice — keys are entered through a separate CLI so they never touch the Claude conversation.

Install

You need uv (Astral's Python launcher) on PATH — that's it. uv provisions Python automatically, so you do not need to install Python 3.10+ yourself or manage virtualenvs.

# 1. Install uv (skip if you already have it)
curl -LsSf https://astral.sh/uv/install.sh | sh        # macOS / Linux
# brew install uv                                       # macOS via Homebrew
# irm https://astral.sh/uv/install.ps1 | iex            # Windows PowerShell

Then in Claude Code:

/plugin marketplace add hwjustin/readless
/plugin install readless
/readless:setup

/readless:setup:

Verifies uv is on PATH (re-prompts if not) and pre-warms uvx --from readless-mcp readless so the first MCP startup is instant.
Asks whether you want the Chinese or English instruction block, then appends it to ~/.claude/CLAUDE.md (marker-bounded, idempotent) so the agent knows to call speak_summary at the end of every turn.

After setup, fully restart Claude Code (not just a new chat — close the CLI / IDE host so the new PATH is picked up). /mcp should show readless ✓ Connected.

Why uv? The MCP SDK requires Python ≥3.10. macOS ships 3.9 system-wide, and asking users to install Homebrew Python or manage a venv was the #1 source of "it doesn't work." uv downloads a suitable Python on demand into its own cache (~/.cache/uv/), runs readless-mcp from PyPI in isolation, and leaves the system Python untouched. This is the pattern recommended by the official MCP servers repo.

Switching to OpenAI / ElevenLabs (optional)

The default edge-tts backend is good enough for most people. If you want OpenAI or ElevenLabs voices, set the key in your own terminal — don't paste the key into Claude:

# OpenAI
uvx --from 'readless-mcp[openai]' readless-setkey openai     # prompts for key, input hidden

# ElevenLabs
uvx --from 'readless-mcp[elevenlabs]' readless-setkey elevenlabs

readless-setkey uses getpass to read the key without echoing it, writes it to ~/.readless/config.yaml (chmod 600), and flips tts_provider for you. Use readless-setkey clear openai (or elevenlabs) to wipe a saved key.

Env vars OPENAI_API_KEY / ELEVENLABS_API_KEY always override the config file if you prefer shell-rc-managed secrets.

Configure

~/.readless/config.yaml is auto-created from defaults on first run. Common edits:

edge_voice: en-US-AriaNeural — pick a different edge-tts voice (edge-tts --list-voices to list)
edge_rate: "+20%" — speed up the default voice
tts_provider: system — force OS-native TTS (useful for fully offline machines)
system_voice: Tingting — pick a macOS voice (say -v '?' to list)
quiet_hours.start / end — opt-in night-silencing for speak_summary / speak_status (off by default; speak_blocker still plays even if enabled)
tools.speak_status: false (etc.) — disable individual tools
status_throttle_seconds: 60 — limit speak_status rate

See config.example.yaml.

Tune the agent

CLAUDE_EXAMPLE.md is the source of truth for "when should the agent call which tool." Edit your ~/.claude/CLAUDE.md block to make the agent more or less chatty — that's the lever, not the code.

Logs

All tool calls append to ~/.readless/log.jsonl:

{"ts": "2026-05-14T22:30:00+08:00", "kind": "summary", "headline": "Build passed, all 3 tests green", "details": ""}

License

Apache 2.0 — see LICENSE.

Structure

.claude-plugin/
  plugin.json          plugin metadata (name, version, description)
  marketplace.json     /plugin marketplace add metadata
.mcp.json              MCP server declaration (uvx --from readless-mcp readless)
commands/
  setup.md             /readless:setup — ensure `uv` is installed + CLAUDE.md append
src/readless/
  server.py            FastMCP entry + tool definitions
  tts.py               edge / system / openai / elevenlabs backends
  setkey.py            readless-setkey CLI — secure API-key entry
  config.py            YAML loading + quiet-hours math (built-in YAML fallback)
  throttle.py          StatusThrottle (1 call/min default)
  logger.py            JSONL append-only log
CLAUDE_EXAMPLE.md      agent instruction blocks (Chinese + English)

Readless

hwjustin4stars

Let your coding agent talk: spoken summaries, progress and blocker questions for Claude Code, Cursor, Codex and any MCP agent. Free edge-tts, no API key.

Speech Voice Agents

Install Run on PlugMCP

GitHub

Run on PlugMCP

1# Readless

README.mdMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

Install from the publisher. Not a PlugMCP endpoint.

Run on PlugMCP

Host a copy with our keys and logs.

No packaged release in the registry yet. Follow the repository README.

RepositoryPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
License: Apache-2.0
Last checked: 2026-10-27

Stars: 4
Tools: —
Uptime: —

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install Readless?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Readless need an API key?

No required environment variable is listed on this record.

What transport does Readless use?

Readless runs locally over stdio.

When was Readless last checked?

Last checked 2026-10-27. Let your coding agent talk: spoken summaries, progress and blocker questions for Claude Code, Cursor, Codex and any MCP agent. Free edge-tts, no API key.

From the publisher

Documentation

readless

English · 中文

Claude Code plugin (MCP-based) that speaks status, summaries, and blocker questions out loud — so you can walk away from a long task and still know what's happening.

Three agent-callable tools:

Tool	When the agent calls it	Spoken length
`speak_summary(headline, details="")`	End of every turn, or when a user-visible task finishes	≤ 50 words
`speak_status(message)`	Mid-task heartbeat during work expected to run > 2 min (server throttles to 1/min)	≤ 10 words
`speak_blocker(question)`	Agent is stuck and needs your input. Bypasses quiet hours, interrupts current speech.	≤ 20 words

Install

You need uv (Astral's Python launcher) on PATH — that's it. uv provisions Python automatically, so you do not need to install Python 3.10+ yourself or manage virtualenvs.

# 1. Install uv (skip if you already have it)
curl -LsSf https://astral.sh/uv/install.sh | sh        # macOS / Linux
# brew install uv                                       # macOS via Homebrew
# irm https://astral.sh/uv/install.ps1 | iex            # Windows PowerShell

Then in Claude Code:

/plugin marketplace add hwjustin/readless
/plugin install readless
/readless:setup

/readless:setup:

Verifies uv is on PATH (re-prompts if not) and pre-warms uvx --from readless-mcp readless so the first MCP startup is instant.
Asks whether you want the Chinese or English instruction block, then appends it to ~/.claude/CLAUDE.md (marker-bounded, idempotent) so the agent knows to call speak_summary at the end of every turn.

After setup, fully restart Claude Code (not just a new chat — close the CLI / IDE host so the new PATH is picked up). /mcp should show readless ✓ Connected.

Why uv? The MCP SDK requires Python ≥3.10. macOS ships 3.9 system-wide, and asking users to install Homebrew Python or manage a venv was the #1 source of "it doesn't work." uv downloads a suitable Python on demand into its own cache (~/.cache/uv/), runs readless-mcp from PyPI in isolation, and leaves the system Python untouched. This is the pattern recommended by the official MCP servers repo.

Switching to OpenAI / ElevenLabs (optional)

The default edge-tts backend is good enough for most people. If you want OpenAI or ElevenLabs voices, set the key in your own terminal — don't paste the key into Claude:

# OpenAI
uvx --from 'readless-mcp[openai]' readless-setkey openai     # prompts for key, input hidden

# ElevenLabs
uvx --from 'readless-mcp[elevenlabs]' readless-setkey elevenlabs

Env vars OPENAI_API_KEY / ELEVENLABS_API_KEY always override the config file if you prefer shell-rc-managed secrets.

Configure

~/.readless/config.yaml is auto-created from defaults on first run. Common edits:

edge_voice: en-US-AriaNeural — pick a different edge-tts voice (edge-tts --list-voices to list)
edge_rate: "+20%" — speed up the default voice
tts_provider: system — force OS-native TTS (useful for fully offline machines)
system_voice: Tingting — pick a macOS voice (say -v '?' to list)
quiet_hours.start / end — opt-in night-silencing for speak_summary / speak_status (off by default; speak_blocker still plays even if enabled)
tools.speak_status: false (etc.) — disable individual tools
status_throttle_seconds: 60 — limit speak_status rate

See config.example.yaml.

Tune the agent

CLAUDE_EXAMPLE.md is the source of truth for "when should the agent call which tool." Edit your ~/.claude/CLAUDE.md block to make the agent more or less chatty — that's the lever, not the code.

Logs

All tool calls append to ~/.readless/log.jsonl:

{"ts": "2026-05-14T22:30:00+08:00", "kind": "summary", "headline": "Build passed, all 3 tests green", "details": ""}

License

Apache 2.0 — see LICENSE.

Structure

.claude-plugin/
  plugin.json          plugin metadata (name, version, description)
  marketplace.json     /plugin marketplace add metadata
.mcp.json              MCP server declaration (uvx --from readless-mcp readless)
commands/
  setup.md             /readless:setup — ensure `uv` is installed + CLAUDE.md append
src/readless/
  server.py            FastMCP entry + tool definitions
  tts.py               edge / system / openai / elevenlabs backends
  setkey.py            readless-setkey CLI — secure API-key entry
  config.py            YAML loading + quiet-hours math (built-in YAML fallback)
  throttle.py          StatusThrottle (1 call/min default)
  logger.py            JSONL append-only log
CLAUDE_EXAMPLE.md      agent instruction blocks (Chinese + English)