Readless — Spoken Status Updates for Coding Agents

    1

    Hear when your agent finishes, how long tasks are going, and when it needs you, so you can walk away from the screen.

    Free

    1 useSecurity scanned

    Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 more

    Readless — Spoken Status Updates for Coding Agents

    Example session with this skill installed

    I'm heading out for lunch. Migrate the remaining API routes to the new auth middleware and run the test suite. Keep me posted by voice.

    • Read your context and instructions
    • Compiled the readless

    Summary

    The agent did the migration while you were away and kept you informed with short spoken updates. When it hit a real decision it asked out loud instead of waiting silently on screen.

    What you heard (example session)

    TimeToolSpoken aloud
    0:40speak_status"Starting the route migration."
    4:10speak_status"About half the routes migrated."
    7:55speak_blocker"Two old admin routes have no tests. Delete them, or keep and migrate?"
    you reply: "keep and migrate"
    12:30speak_status"Test suite running."
    14:05speak_summary"Done. All twenty routes use the new auth middleware and the tests pass."

    What was logged for later (not spoken)

    speak_summary takes an optional details field that goes only to the local log, so specifics stay out of your ears but are there when you get back:

    {"kind": "summary", "headline": "Done. All twenty routes use the new auth middleware and the tests pass.", "details": "Migrated 20 routes; kept and migrated the two legacy admin routes per user; full suite green."}
    

    Why it sounds like this

    • Outcome first, short sentences. No file paths, code, hashes or stack traces read aloud.
    • Heartbeats only at milestones. The server plays at most one status per minute, so it never chatters.

    Blockers interrupt. A question is spoken immediately, even over other speech or during quiet hours, so you never come back to an agent that stalled twenty minutes ago.

    • Your language. Write to the agent in Chinese and it speaks Chinese.

    Next steps

    • Make it permanent: ask your agent to add the readless rules block to your CLAUDE.md or AGENTS.md.
    • Prefer an English voice? Set edge_voice: en-US-AriaNeural in ~/.readless/config.yaml and restart your agent.
    • Like it? Star the project on GitHub: https://github.com/hwjustin/readless
    ask your agent to add the readless rules block to your CLAUDE.md

    Connects securely to your tools. The creator never sees your data.

    About this skill

    ⭐ Free and open source: github.com/hwjustin/readless. A star on GitHub is the best way to support it.

    Long agent runs mean either staring at the terminal or coming back to find the agent stopped twenty minutes ago to ask you something. Readless lets your coding agent talk to you out loud.

    What it does

    The skill teaches your agent three habits, backed by the open-source readless MCP server:

    • End-of-turn summary. After every reply the agent says, in a sentence, what happened: "Fixed the session bug. All tests pass."
    • Heartbeats on long tasks. At milestones during work that takes more than a couple of minutes, a short spoken status, capped at one per minute.
    • Blockers you can't miss. When the agent needs a decision, or before anything destructive, it interrupts and asks out loud, even during quiet hours.

    It also teaches the agent to write for the ear: outcome first, no file paths, code or stack traces read aloud, and the user's own language (Chinese and English work out of the box).

    Setup is part of the skill

    If the MCP server isn't installed yet, the skill walks your agent through setup for Claude Code, Cursor, VS Code Copilot, Codex CLI, Gemini CLI, Windsurf or any MCP client. It can optionally add a short rules block to your agent's instructions file so voice updates stay on every session.

    Voice backends

    • edge-tts (default): free Microsoft voices, no API key, no signup. The default voice is a bilingual Chinese/English one; English speakers can switch to en-US-AriaNeural with one config line.
    • System voice: fully offline (macOS say, Linux espeak-ng, Windows SAPI).
    • OpenAI / ElevenLabs: your own key, entered through a separate terminal command so it never enters the chat.

    What leaves your machine

    • Default backend: the spoken text is sent to Microsoft's online edge-tts service. It falls back to the local OS voice when offline.
    • Optional OpenAI / ElevenLabs backends send the spoken text to that provider with your own key.
    • tts_provider: system keeps everything local.
    • Every call is logged locally to ~/.readless/log.jsonl. Nothing is sent to the author or to any analytics service.
    • The skill itself is Markdown instructions only, no scripts.

    Requires the readless MCP server (installed via uvx). Spoken text is sent to Microsoft's online TTS by default; set tts_provider: system to keep it local. The default voice is a bilingual Chinese/English one; set edge_voice (e.g. en-US-AriaNeural) for a native English voice. On Linux, audio playback needs mpg123 or ffplay, and the offline voice needs espeak-ng.

    How to use

    1. 1

      Connect your agent to the Agensi MCP

      Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup

    2. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before any payment.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill goes through the trust checks below.

    Security scanned

    Checked by our 8-point scan before listing

    1 use

    Times used to date

    Free forever

    No account required to browse

    Trust & safety

    Security scan

    Security scan passed 1 month ago

    • Free with an Agensi account

    Requires

    Astral
    Readless (PyPI: Readless Mcp) MCP
    uv (Python tool runner)
    mpg123 or ffplay (Linux only)
    Python
    macOS

    Permissions

    Terminal / Shell
    Network Access
    Read Files
    Write Files

    Allowed Hosts

    astral.sh

    File Scopes

    ~/.readless/**
    ~/.claude/CLAUDE.md
    AGENTS.md
    (optional
    rules
    block)
    Agent
    MCP
    config
    (e.g.
    ~/.cursor/mcp.json)
    only
    during
    setup

    Terminal: only to check that uv is installed and, if the user agrees, run the documented install commands. Read/Write files: the agent edits its own MCP config and, only with the user's OK, appends a marker-bounded rules block to CLAUDE.md / AGENTS.md. Network: the MCP server is fetched from PyPI via uvx, and the default edge-tts backend sends the spoken text to Microsoft's TTS service (set tts_provider: system for fully offline). API keys for optional OpenAI / ElevenLabs voices are entered by the user in their own terminal, never through the agent.

    Listed1 month ago

    What's inside

    Frequently Asked Questions

    Any agent that supports MCP servers: Claude Code, Cursor, VS Code with GitHub Copilot, Codex CLI, Gemini CLI, Windsurf, Claude Desktop and others. The skill includes setup instructions for each of these.

    Not necessarily. The default edge-tts backend uses Microsoft's free online voices and falls back to your OS voice when offline. Set tts_provider: system in ~/.readless/config.yaml to stay fully offline. OpenAI and ElevenLabs voices are optional and use your own key.

    Asking an agent to read its output aloud gets you file paths, code and stack traces read out word by word. This skill gives the agent clear rules: when to speak (end of every turn, milestones on long tasks, and before it needs you), how long, and how to phrase it for the ear. The readless server adds the parts a prompt can't: real audio playback, a one-per-minute limit on status updates, interrupting speech for blockers, and a local log.

    Yes. In ~/.readless/config.yaml you can set quiet hours (summaries and status updates go silent; blocker questions still play), change the minimum gap between status updates, change voice and speed, or turn any of the three tools off.

    Install uv, add the readless MCP server to your agent (one line: uvx --from readless-mcp readless), and restart the agent. If the server isn't installed yet, the skill walks your agent through these steps for your specific tool. Claude Code users can also install it as a plugin and run /readless:setup.

    Readless includes a local logging feature that saves every status update and technical detail to a JSONL file. This allows you to review the full technical history at your desk even if you only heard the brief summary while away.

    New in Agents & Orchestration