Walkie-Claudie

Overzicht

Walkie-Claudie is een Android-applicatie waarmee je via je smartphone met een Claude Code-sessie op je pc kunt communiceren, vergelijkbaar met het gebruik van een portofoon.

Belangrijkste functies

  • Spraakcommunicatie (Tweeweg): Communicatie tussen de gebruiker en de Claude Code-sessie op de pc.
  • PTT-knoppen (Push-to-Talk): Gebruik een zwevende knop, de volumeknoppen of de knop van een Bluetooth-oortelefoon als portofoonknop.
  • Monoloogmodus: Voor langere uitingen. De app blijft luisteren, zelfs bij lange pauzes, en verzendt de volledige tekst in één keer (tot maximaal 10 minuten).
  • Meerdere kanalen: Elke sessie wordt beschouwd als een apart kanaal. Het is mogelijk om antwoorden op andere kanalen mee te luisteren (vergelijkbaar met het scannen van kanalen bij een portofoon).
  • Lijst met openstaande taken: Toont op het scherm welke taken Claude beheert (vragen die een antwoord nodig hebben, goedkeuringen of lopende werkzaamheden).

Achtergrond

De ontwikkelaar is van beroep pakketbezorger. Tijdens het werk werd geprobeerd om via de Remote Control-functie van Claude Code te "vibe coden", maar dit bracht uitdagingen met zich mee:

  1. Het is lastig om tijdens het bezorgen gedetailleerde teksten via een toetsenbord in te voeren.
  2. Het constant schakelen tussen de bezorg-app en de Claude-app is onhandig.
  3. Het is moeilijk om de gedetailleerde antwoorden van Claude tijdens het werk te lezen.
  4. Terwijl de handen en ogen volledig bezet zijn, blijven de mond en oren onbenut.

Om deze redenen is Walkie-Claudie ontworpen: om te kunnen coderen via spraak en audio tijdens het bezorgen.

Werking

  • Spreken: Spraakherkenning op de telefoon → tekst wordt verzonden naar de walkie-plugin op de pc → de plugin geeft dit door aan de Claude Code-sessie.
  • Antwoorden: Claude laat een antwoord achter via de reply-tool van de plugin → de telefoon haalt dit op en leest het hardop voor.
  • Verbinding: De telefoon verbindt rechtstreeks met de pc zonder tussenkomst van een relaisserver.

Installatie en Uitvoering

Specificaties

  • Telefoon: Android 10 of hoger (monoloogmodus vereist Android 13 of hoger).
  • PC: Alleen getest op Linux. macOS en Windows zijn niet geverifieerd.
  • Verbinding: Directe verbinding van telefoon naar PC via poorten 7700–7709 (HTTP, uitsluitend privé-netwerkadressen).
  • Talen: Koreaans en Engels.

Vereisten

  • Claude Code (ingelogd met een claude.ai abonnement) en Bun.
  • Een netwerkverbinding waarbij de telefoon de pc kan bereiken: hetzelfde Wi-Fi-netwerk of een VPN zoals Tailscale voor extern gebruik.

Installatiestappen

Men kan Claude Code de URL van deze repository geven en vragen om de installatie uit te voeren. De stappen voor de telefoon (3-5) moeten handmatig worden gedaan.

  1. Installatie van de plugin op de PC:

``bash claude plugin marketplace add ahn4jang27/walkie-claudie claude plugin install walkie@walkie-claudie ``

  1. Start een nieuwe Claude Code-sessie met WALKIE_ENABLE=1:
  • Linux/macOS:

``bash WALKIE_ENABLE=1 claude --dangerously-load-development-channels plugin:walkie@walkie-claudie ``

  • Windows PowerShell:

``powershell $env:WALKIE_ENABLE=1; claude --dangerously-load-development-channels plugin:walkie@walkie-claudie ``

  • Opmerking: Omdat de kanaalfunctie een "research preview" is, is de development-vlag nodig. Bevestig de waarschuwing bij het opstarten met Enter. Zonder WALKIE_ENABLE=1 opent de plugin geen poorten of tools.
  • Bestaande gesprekken: Beëindig de huidige sessie en voeg --continue (laatste gesprek) of --resume (selecteer gesprek) toe aan het bovenstaande commando.
  1. Installatie van de APK op de telefoon:

Installeer de APK via de Releases of via zelf bouwen. Indien Google Play Protect de installatie blokkeert:

  • Tik op 'Meer details' → 'Toch installeren'.
  • Indien dit niet werkt: Play Store → Profiel → Play Protect → Instellingen → schakel 'Apps scannen met Play Protect' uit → installeer APK → schakel scanfunctie weer in.
  1. Koppelen:

Voer in de sessie uit stap 2 het commando /walkie:pair in. Scan de resulterende QR-code in de app via [Instellingen] › Sleutel › QR.

  • Indien de QR-code onleesbaar is: voer bun <plugin pad>/pair.ts uit in de terminal.
  • Indien scannen niet mogelijk is: kopieer de tekst uit pair.ts --text → App [Instellingen] › PC-adres › Plakken.
  1. Activatie:

Start de app → Sta microfoon en meldingen toe → Tik op [Aan] op het hoofdscherm → Volg de instructies om 'Over andere apps heen weergeven' (voor de zwevende knop) en 'Toegankelijkheid' (voor de volumeknoppen) in te schakelen.

Rechten en Toegankelijkheid

RechtGebruikGevolg bij ontbreken
Microfoon (Verplicht)Zet spraak om in tekst via de telefoon. Alleen tekst gaat naar de PC.Spreken is niet mogelijk (antwoorden worden wel afgespeeld).
Meldingen (Aanbevolen)Toont een melding dat de walkie-talkie aan staat.De app werkt, maar er is geen statusmelding.
Over andere apps heen weergevenNodig voor de zwevende knop.De zwevende knop verschijnt niet.
ToegankelijkheidNodig voor Volume $\downarrow$ (Spreken) en Volume $\uparrow$ (Monoloog).Volumeknoppen werken niet als bediening.

Toelichting Toegankelijkheid: Android staat apps alleen toe om volumeknoppen te detecteren wanneer een andere app op het scherm staat via de toegankelijkheidsdienst. De app leest geen scherminhoud, maar kijkt alleen naar de knopindrukkingen.

  • Beperkte instellingen (Android 13+): Als de schakelaar grijs is of er een melding 'Beperkte instelling' verschijnt: Ga naar App-info → tik op de drie puntjes (⋮) rechtsboven → 'Beperkte instellingen toestaan' → schakel Toegankelijkheid opnieuw in.

Configuratie (Omgevingsvariabelen)

VariabeleStandaardwaardeBetekenis
WALKIE_ENABLE(niet ingesteld)Alleen sessies met waarde 1 activeren de walkie-talkie.
WALKIE_PORT7700Poort voor het eerste kanaal (volgende sessies +1, max 10).
WALKIE_NAMESessiemap-naamDe naam van het kanaal.
WALKIESTATEDIR~/.claude/channels/walkieLocatie waar sleutels en antwoorden worden bewaard.

Zelf bouwen / Ontwikkelen

  • App: cd android && ./gradlew assembleDebug (vereist JDK 17+ en Android SDK) → APK bevindt zich in android/app/build/outputs/apk/debug/app-debug.apk.
  • Signalen herstellen: python3 tools/sounds.py android/app/src/main/res/raw.
  • Plugin testen: cd plugin && bun install && bun test.
  • Planningsdocument: docs/PRD.md.

Interface

  • Hoofdscherm: Bovenaan staan het kanaal, de verbinding en het verbruik; in het midden de openstaande taken; onderaan de geschiedenis; onderaan knoppen voor [Instellingen], [Aan/Uit] en [Spreken].
  • Statuslampje: Groen = Aan / Donker = Uit. Wanneer uitgeschakeld, is de geschiedenis vervaagd en verschijnt de tekst 'Uit'.
  • Kanalenlijst: Toegankelijk door op het bovenste LCD-scherm (CH1 naam ›) te tikken.
  • Zwevende knop: Een kleine portofoon die over andere apps heen verschijnt.
  • Groen: Verbonden.
  • Rood: Verzenden.
  • Knipperend rood: Verbinding verbroken.

Gebruik

Basisstroom

  1. Aanzetten: Tik op [Aan] → één vibratie + stijgende aan-toon.
  2. Spreken: Gebruik een van de volgende methoden (aanpasbaar in instellingen):
  • Zwevende knop: Tik op de microfoon → 'piep-piep-piep' geluid → spreken. Korte pauzes onderbreken de opname niet (max. 2 minuten).
  • Volume $\downarrow$ ingedrukt houden: Spreken zolang de knop is ingedrukt. Korte drukken blijven de normale volumefunctie behouden. Vereist dat het scherm aan is en Toegankelijkheid is ingeschakeld.
  • Bluetooth-knop: Eén of twee keer drukken om te starten. Werkt ook als het scherm uit is.
  1. Verzenden: Tik opnieuw op de zwevende/Bluetooth-knop, of laat de volumeknop los → bevestigingsgeluid zodra de PC de data ontvangt.
  2. Antwoord luisteren: Oproepsignaal → het antwoord wordt hardop voorgelezen.
  3. Uitzetten: Tik op [Uit] → twee vibraties + dalende uit-toon.

Extra functies

  • Monoloogmodus: Houd Volume $\uparrow$ ingedrukt → drie stijgende tonen → laat los en spreek → druk opnieuw op Volume $\uparrow$ om te verzenden. Lange pauzes zijn toegestaan (max. 10 minuten). Kan alleen gestart worden als het scherm aan is.
  • Kanalen (Meerdere sessies): Elke sessie met WALKIEENABLE=1 neemt een vrije poort in (7700, 7701, etc.) en wordt weergegeven als CH1, CH2, etc. De naam kan worden gewijzigd via WALKIENAME=naam.
  • Scannen (Standaard aan): Luistert naar alle openstaande kanalen. Antwoorden van andere kanalen worden voorafgegaan door een 'piep-piep' geluid. Eigen berichten gaan altijd naar het huidige actieve kanaal.
  • Stem aanpassen: Kies de engine, stem en snelheid in het scherm [Stem].
  • Tijdens bellen: De Bluetooth-knop dient dan voor opnemen/beëindigen en de volumeknoppen voor het belvolume. Antwoorden die binnenkomen tijdens een gesprek worden na afloop voorgelezen.
  • Verbindingsverlies: Verzonden berichten worden continu opnieuw verzonden tot de verbinding is hersteld.

Overige zaken

Beveiliging

  • Risico: Berichten via de app kunnen Claude opdracht geven commando's uit te voeren op de PC. Beheer de sleutel zorgvuldig.
  • Sleutel: Wordt automatisch gegenereerd bij eerste start (~/.claude/channels/walkie/key). Verzoeken met een onjuiste sleutel worden geweigerd.
  • Netwerk: Alleen verbindingen van private adressen (192.168.x, 10.x, 172.16–31.x, Tailscale 100.64–127.x) worden geaccepteerd.
  • Versleuteling: Het verkeer is niet versleuteld. Op openbare Wi-Fi kan de inhoud worden onderschept. Gebruik Tailscale voor versleutelde communicatie.
  • Sleutel lekken: Verwijder het sleutelfil → start de sessie opnieuw → koppel de apparaten opnieuw.

Probleemoplossing

  • App blijft op 'Verbroken': Controleer of de telefoon de PC kan bereiken, of de firewall poorten 7700–7709 toestaat en of de sessie is gestart met WALKIE_ENABLE=1.
  • 'HTTP 401': De sleutel is onjuist → koppel opnieuw via /walkie:pair.
  • Bluetooth-knop werkt niet: Een muziek- of podcast-app heeft de knop mogelijk geclaimd → houd de zwevende knop lang ingedrukt.
  • Installatie geblokkeerd: Zie de instructies voor Play Protect bij de installatie.
  • Toegankelijkheidsschakelaar is grijs: Geef eerst 'Beperkte instellingen toestaan' via App-info.
  • Volumeknop verandert alleen volume: Toegankelijkheid is uitgeschakeld → ga naar [Instellingen] › 'Toegankelijkheid uit' › [Handleiding].
  • Verbruik is niet zichtbaar: De verbruikscontrole is een niet-officiële functie en kan door updates van Claude Code stoppen. Voeg "statusLine": {"type": "command", "command": "bun <plugin pad>/statusline.ts"} toe aan settings.json.
  • Knoptoetsen testen: Gebruik [Instellingen] › Knoptest.