{"skill":{"slug":"claw-radio","displayName":"claw-radio","summary":"Operate a radio station. Teaches you how to be an AI radio host and work with the claw radio cli.","description":"---\nname: claw-radio\ndescription: Operate a radio station. Teaches you how to be an AI radio host and work with the claw radio cli.\n---\n\nImportant rule: read this skill description with your full attention and follow it closely.\n\n## Installation\n\n### Brew install cli radio tool\n\n```bash\nbrew install vossenwout/tap/claw-radio-cli\n```\n\n### Brew install cli-radio dependencies\n\n```bash\nbrew install tmux mpv yt-dlp ffmpeg docker colima\n```\n\nColima provides the local container runtime used by Docker on macOS.\n\nBefore starting Colima or SearxNG, first check whether they are already running.\nDo not start a second instance if the existing one is healthy.\n\nCheck Colima:\n\n```bash\ncolima status\n```\n\nIf Colima is not running, start it:\n\n```bash\ncolima start\n```\n\n### SearxNG (required for `claw-radio search`)\n\n`claw-radio search` requires SearxNG to allow **JSON output** (`format=json`). The\nstock container config often allows **html only**, which causes `403 Forbidden` on\nJSON.\n\n#### 1) Check whether SearxNG is usable\n\n```bash\ndocker ps --filter name=searxng\n\n# Preflight: must return JSON (not HTML / 403)\ncurl -fsS \"http://localhost:8888/search?q=test&format=json\" | head -c 1 | grep '{'\n```\n\n#### 2) If SearxNG isn’t running OR the JSON preflight fails: bootstrap a persistent config\n\nBootstrap once (generates a valid full settings.yml from the container image):\n\n```bash\n# Start once without a mount so the container generates a valid settings.yml\ndocker rm -f searxng 2>/dev/null || true\ndocker run -d --name searxng -p 127.0.0.1:8888:8080 searxng/searxng:latest\n\n# Copy generated config to a persistent location\nmkdir -p ~/.openclaw/searxng\ndocker cp searxng:/etc/searxng/settings.yml ~/.openclaw/searxng/settings.yml\n```\n\nPatch `search.formats` to include JSON (+ rss optional):\n\n```bash\npython3 - <<'PY'\nfrom pathlib import Path\nimport re\n\np = Path.home()/'.openclaw/searxng/settings.yml'\nt = p.read_text()\n\nm = re.search(r'(?ms)^search:\\n(.*?)(^server:)', t)\nassert m, \"Could not locate search: block in settings.yml\"\n\nsb = t[m.start():m.end()]\nsb2 = re.sub(\n    r'(?ms)^  formats:\\n(?:\\s*-\\s*.*\\n)+',\n    '  formats:\\n    - html\\n    - json\\n    - rss\\n',\n    sb\n)\n\nif sb2 == sb:\n    sb2 = sb.replace('\\n\\nserver:', '\\n  formats:\\n    - html\\n    - json\\n    - rss\\n\\nserver:')\n\np.with_suffix('.yml.bak').write_text(t)\np.write_text(t[:m.start()] + sb2 + t[m.end():])\nprint('Patched search.formats to include json')\nPY\n```\n\nRecreate the container with the mounted config:\n\n```bash\ndocker rm -f searxng\ndocker run -d \\\n  --name searxng \\\n  -p 127.0.0.1:8888:8080 \\\n  -v ~/.openclaw/searxng:/etc/searxng \\\n  searxng/searxng:latest\n```\n\nRe-run the JSON preflight:\n\n```bash\ncurl -fsS \"http://localhost:8888/search?q=test&format=json\" | head -c 1 | grep '{'\n```\n\n`claw-radio` expects SearxNG at `http://localhost:8888` by default. If it runs at a\ndifferent address, update `search.searxng_url` in the config.\n\n## Persistent session required\n\n`claw-radio start` should be run in a persistent terminal session. If the terminal that started it exits, playback may stop.\n\nFor AI agents:\n\n1. Run the radio inside one persistent `tmux` session.\n2. Send every `claw-radio` command into that same `tmux` session.\n3. Read output with `tmux capture-pane`.\n4. Do not control the station from multiple terminals in parallel.\n\n## Strict Agent Rules\n\nAgents must follow the simplest possible control flow and stay patient.\n\nRequired behavior:\n\n1. Create one `tmux` session.\n2. Build the playlist.\n3. Queue intro banter with `say`.\n4. Send `start` exactly once.\n5. Wait until the pane shows `radio started`.\n6. Then repeat this exact loop:\n   - send one `poll --timeout 30s`\n   - read the newest cue from the `tmux` pane\n   - execute exactly one matching `claw-radio` command in the same `tmux` session\n   - then poll again\n7. Only send `start` again if a cue explicitly reports `event=engine_stopped`.\n\nPersona rule:\n\n- The agent should infer and invent the radio host persona from the user's requested station vibe.\n- Do not ask the user to come up with the host character.\n- Only ask follow-up questions if the requested station vibe itself is unclear.\n\nEscalation rule:\n\n- If something unexpected happens or the tool seems broken, stop and tell the user.\n- Do not improvise with extra scripts, retries, restarts, or alternate workflows unless this skill explicitly says to.\n- Say what you ran, what you expected, and what happened instead.\n\nForbidden behavior:\n\n- Do not use Python, shell loops, `nohup`, background jobs, helper scripts, or external controller processes to run the station.\n- Do not create autonomous polling daemons or automation wrappers.\n- Do not issue speculative recovery actions.\n- Do not restart the station just because nothing happened yet.\n- Do not treat waiting as failure.\n- Do not optimize away the manual poll-read-react loop.\n\nIf a poll returns `timeout` or `buffering`, that is normal. Do nothing except poll again.\n\nRecommended session name:\n\n```bash\ntmux new-session -d -s claw-radio -c \"$PWD\"\n```\n\nIf `claw-radio` is available as a local binary such as `./claw-radio`, prefer using that exact path consistently for all commands in the session.\n\n## What you do?\n\n1. Ask the user what kind of radio station you should play as. The user is free in how to define it. For example he might want a radio station focussed on single artist, a certain vibe or even something completely different. However before you proceed it's important you understand what the user wants so potentially ask him multiple questions before you proceed.\n2. Come up with a role / character for you as the radio host yourself. Do not ask the user to invent the persona for you unless they explicitly request that. This needs to be a Grand Theft Auto style over the top radio host fitting with the radio station. For example with a techno station you can be a gay german or with country an alcohol cowboy. You are free to define a character you seem fit.\n3. Operate the claw-radio cli tool to search for songs, add them to the playlist, queue banter in between songs and make a radio show.\n\n## How to operate claw-radio CLI?\n\n### Search for songs\n\nUse the `claw radio search` method to search for songs so you don't entirely rely on your own domain knowledge.\nThis returns a list of song and artist names you can use to build the playlist. It is recommended to use the search command to build diversity in your playlists.\nImportant: `claw-radio search` requires SearxNG to already be running and reachable at the configured `search.searxng_url`.\nYou can use the following search modes by use the --mode flag.\n\n- `raw`: exact query text (best for precision/debug)\n- `artist-top`: popular songs for an artist\n- `artist-year`: artist+year targeting\n- `chart-year`: chart/year discovery\n- `genre-top`: broad genre discovery\n\nCommon patterns:\n\n```bash\nclaw-radio search \"Billboard Year-End Hot 100 2009\" --mode chart-year\nclaw-radio search \"Miley Cyrus\" --mode artist-top\nclaw-radio search \"best synthpop songs\" --mode genre-top\nclaw-radio search \"Katy Perry tracklist site:musicbrainz.org\" --mode raw\n```\n\n### Build a playlist\n\nThe radio station works by autoplaying a playlist you build with the following commands. After you have searched and found appropriate songs you can use the followign commands to manage the playlist\n\nTry to aim for around 25-50 songs. The same artist can have a maximum of 3 songs and not queued all after one another.\n\n- `playlist add` appends songs to the upcoming queue.\n- Queue is consumable: songs are removed as they start playing.\n- `playlist view` shows only still-upcoming songs.\n- `playlist reset` clears upcoming songs only.\n- `stop` ends session and fully resets station state/cache.\n\nPlaylist payload format:\n\n- JSON array of strings\n- preferred format per item: `Artist - Title`\n\nExample:\n\n```bash\nclaw-radio playlist add '[\n  \"Kendrick Lamar - Alright\",\n  \"SZA - Saturn\",\n  \"Outkast - Hey Ya!\",\n  \"Daft Punk - One More Time\"\n]'\n```\n\nFor long playlists, prefer passing the JSON with a literal here-doc instead of hand-escaped inline quoting. This avoids shell breakage on titles containing `'`, `\"`, `&`, or parentheses.\n\n```bash\nclaw-radio playlist add \"$(cat <<'EOF'\n[\"The Notorious B.I.G. - Juicy\",\"Foxy Brown - I'll Be\",\"DMX - Ruff Ryders' Anthem\"]\nEOF\n)\"\n```\n\n### Speaking / banter\n\nAs you are a GTA style radio host it's important you inject banter in between the songs and also put in banter before the first song to introduce the radio station. This can be done with the say command.\n\nBefore the radio is started the say command queues banter that will play using a TTS system before the first song. Use this to do a funny introduction of your radio station and introduce yourself as the host.\n\nimportant: You are required to put banter before the first song introducing yourself as host.\n\nExample:\n`claw-radio say \"Welcome, I am Gunther and you are listening to radio Berlin with the best undeground techno.\"`\n\nAfter that each say will queue banter after the song that is currently playing. You will also get cue's for that with a prompt what you should say. More on that later.\n\n`claw-radio say \"Next up one of my favorite songs Darude Sandstorm\"`\n\n### Starting and stopping\n\nThe start command starts playing any songs you added to the playlist and the banter you cueued. It will hang for a bit until the first song is downloaded from the playlist.\n`claw-radio start`\n\nImportant: don't do anything else until the claw-radio returns succesfully.\n\nFor AI agents, run `start` in the persistent `tmux` session and wait until the pane shows `radio started` before polling. Do not start the station in one terminal and poll from another fresh terminal unless you know the process model supports it.\n\nThe stop command stops the radio station and resets the playlist. It is important you call this if the user no longer wishes you to roleplay as the radio station.\n`claw-radio stop`\n\nWhen cleaning up a `tmux`-driven session, do both:\n\n```bash\ntmux send-keys -t claw-radio \"claw-radio stop\" C-m\ntmux kill-session -t claw-radio\n```\n\nThis stops the radio engine and removes the persistent terminal used by the agent.\n\n### Polling Is Mandatory\n\nAfter you started the radio station, instructions / events on what to do will be send to you. You are required to do active polling for this.\n`claw-radio poll` is the core control loop. Keep polling continuously while the radio is active. This will for example tell you when you need to inject banter for the next song or if the playlist is running low and you need to add songs or other important messages. If you don't need to do anything a timeout event will appear.\n\nWhy:\n\n- without polling, you miss `banter_needed` and `queue_low`\n- missed cues cause awkward transitions and empty queue risk\n- `status` is a snapshot, not an event loop\n\nRequired loop:\n\n1. Poll one cue.\n2. Execute matching action.\n3. Poll again.\n\n### Text to speech\n\nWith `claw-radio tts install` you can install a chatterbox tts system which gives you a less robotic voice.\nBy default a system voice is used, this is a good fallback if the user doesn't have a gpu, weak pc.\nYou can swap between chatterbox and system ts using `claw-radio tts use`\n\n### Canonical Agent Loop\n\n```bash\n# 0) Create one persistent shell for the station\ntmux new-session -d -s claw-radio -c \"$PWD\"\n\n# 1) Build queue by executing lots of searches\ntmux send-keys -t claw-radio 'claw-radio search \"best 2000s pop songs\" --mode chart-year,genre-top' C-m\ntmux send-keys -t claw-radio 'claw-radio playlist add \"[\\\"Fergie - Glamorous\\\",\\\"Miley Cyrus - Party In The U.S.A.\\\"]\"' C-m\n\n# 2) Required intro of the radio station. DON't forget this\ntmux send-keys -t claw-radio 'claw-radio say \"Hello this is... and you are listing to\"' C-m\n\n# 3) Start show\ntmux send-keys -t claw-radio 'claw-radio start' C-m\n\n#4) Wait for the radio to start, don't do anything else like polling or something until the radio says \"radio started\". This can take a few minutes so don't cancle the radio start.\n\n# 5) Begin mandatory poll loop in the same tmux session\ntmux send-keys -t claw-radio 'claw-radio poll --timeout 30s' C-m\n\n# 6) react to events, queue banter, songs ...\n\n# 7) stop when user doesn't want you to roleplay anymore\ntmux send-keys -t claw-radio 'claw-radio stop' C-m\ntmux kill-session -t claw-radio\n```\n\nBad agent behavior:\n\n- starting extra sessions\n- restarting without an `engine_stopped` cue\n- using Python to scrape or parse `tmux`\n- launching background pollers\n- trying to automate away waiting\n\nGood agent behavior:\n\n- one persistent `tmux` session\n- one `start`\n- patient wait for `radio started`\n- one `poll`\n- one response to the returned cue\n- one `poll` again\n\nCue contract:\n\n- Every cue contains `event` and usually `prompt`.\n- If `command` is present, run it exactly.\n- If `command_template` is present, fill placeholders and run it.\n- If no command field is present (`timeout`, `buffering`), keep the poll loop moving.\n\nPossible events:\n\n- `banter_needed`\n  - `prompt` explains what kind of banter is needed.\n  - If `upcoming_song` is present, mention or react to it naturally.\n  - `command_template`: `claw-radio say \"<banter>\"`\n\n- `queue_low`\n  - Add more songs immediately.\n  - Use `suggested_add_count` as refill target.\n  - `command_template`: `claw-radio playlist add '[\"Artist - Title\", ...]'`\n\n- `buffering`\n  - Station is preparing songs; wait briefly and poll again.\n  - No extra command is needed beyond continuing the poll loop.\n\n- `timeout`\n  - No new cue yet; poll again.\n  - No extra command is needed beyond continuing the poll loop.\n\n- `engine_stopped`\n  - `command`: `claw-radio start`\n\n## Common errors\n\n- Sandbox rules from codex or other ai agents can prevent the search command for working. Instruct the user to fix his sandbox if this happens.\n- No songs start playing if you don't wait for claw-radio start to finish.\n- If `radio started` appears but playback dies right after the agent command returns, the agent likely used a non-persistent terminal. Move the whole workflow into one `tmux` session.\n- If intro banter seems to disappear, it may have been consumed by a failed `start` attempt. Re-queue the banter before retrying.\n\n## Operational Rules\n\n- Use one persistent `tmux` session named `claw-radio`.\n- Use the same terminal session for `say`, `start`, `poll`, and `stop`.\n- Do not issue radio control commands from multiple terminals in parallel.\n- Do not use Python, bash loops, background jobs, or helper processes to control the station.\n- Do not send `start` again unless `poll` explicitly returns `engine_stopped`.\n- If something unexpected happens, stop and report it to the user instead of improvising.\n- Do not stop polling while radio is active.\n- Do not treat `timeout` as an error.\n- Do not treat `buffering` as an error.\n- One `banter_needed` cue -> one `say` line.\n- Refill immediately on `queue_low`.","tags":{"latest":"1.0.1"},"stats":{"comments":0,"downloads":515,"installsAllTime":0,"installsCurrent":0,"stars":0,"versions":2},"createdAt":1773343521034,"updatedAt":1778491865024},"latestVersion":{"version":"1.0.1","createdAt":1773345266784,"changelog":"- Added detailed SearxNG setup instructions, including persistent configuration and patching to enable JSON output required by `claw-radio search`.\n- Included preflight steps to check SearxNG's availability and correct output format.\n- Clarified the SearxNG container run and configuration process.\n- No functional or workflow changes to the rest of the skill.","license":"MIT-0"},"metadata":null,"owner":{"handle":"vossenwout","userId":"s17bat2t3vtmb37j7wg7p5m5wn8853wj","displayName":"Wout Vossen","image":"https://avatars.githubusercontent.com/u/47829242?v=4"},"moderation":null}