Skip to content
tidleyPublic

About

Encrypted White Noise chats for local herdr coding agents. Primary source, issues, PRs, CI and releases: https://github.com/tidley/codr. Independent ngit mirror linked below.

Resources

Contributing

Stars

7 stars

Watchers

0 watching

Forks

Latest commit

 

History

137 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

codr

codr connects coding agent sessions in herdr to White Noise, with one encrypted chat per session. Send a message from your phone to continue coding, create a project, choose an agent or model, and read the replies in the same chat.

Supported agents: OpenCode, Codex, and Claude Code on Linux and macOS.

The current setup code uses 👾 as the public name and display name when it creates an account. The supported 0.9.0 fresh-account bootstrap keeps its original naming behaviour. Existing profiles stay unchanged. Verify the full bridge public key printed by setup, not its display name.

Behaviour

  • Chat names pair the herdr tab and workspace: review (Acme). Fresh-session chats add the agent name only to distinguish a matching live project in the same workspace. Descriptions contain workspace and agent details.
  • With editable progress enabled, one active bubble carries status and checklist updates. Final replies stay separate.
  • Phone text is handed straight to the agent, including while it is working, unless an earlier submission has unconfirmed native acceptance. Images, files and voice follow as soon as download/transcription completes, without waiting for idle. The agent handles its own input; codr does not interrupt it. Send /cancel when you do want to interrupt the current task.
  • /new guides you through workspace, folder, installed agent, and model selection. Reply with numbers, use 0 to cancel, and type the repository folder name to confirm the final preview. The destination workspace is shown separately.
  • Choose the default model or browse a provider's full model list. OpenCode uses its authenticated model catalogue; variants are selected separately. /agent opens a separate chat without moving old history.
  • Supported OpenCode questions accept a number or option label as a reply. V2 questions with custom input also accept text answers, such as a version number.
  • For OpenCode V2 permission cards, send 1 to allow once or 2 to deny as a normal chat message. No quoted reply or approval code is needed.
  • OpenCode V2 multi-part forms show one question at a time. Saved answers survive restart; the final answer submits the complete form together.
  • New groups make your configured account an admin, so you can invite participants and rename the group. Only the owner can prompt the agent. Group setup
  • In automatic sync mode, local prompts mute all chats and an owner phone message resumes them. /sync on or /sync off keeps your explicit choice across restarts; /unmute restores automatic mode.
  • Phone history commands collect in the background without holding the worker's input loop. Pending requests survive restart and reuse the native history cache.

Install

The unpublished 0.12.0 release candidate updates MDK to 0.17.0. Its account-storage migration is not an automatic update from the released 0.14 cohort. Keep the running installation unchanged until a separately approved, backed-up migration; see the combined-runtime storage boundary.

0.11.2 targets existing accounts. Fresh accounts use the supported 0.9.0 setup below, then the owner-confirmed chat handover. See the 0.11.2 release notes and combined runtime/handover guide.

Needs Linux x86_64 or aarch64 or macOS on Apple silicon or Intel, a per-user service manager (systemd or launchd), Python 3.11+, Git, and herdr 0.9.1+. No Rust toolchain required.

herdr plugin install tidley/codr --ref v0.9.0
herdr plugin action invoke local.white-noise.setup

Enter your White Noise public key (npub) during setup. Get White Noise for iOS or Android.

Or give your coding agent this prompt, with your own public key:

Install https://github.com/tidley/codr. My White Noise public key is npub1…. Follow docs/INSTALL.md and report what you verified.

Full installation and upgrade guide →

In the 0.12.0 release candidate (unpublished)

  • OpenCode V2 phone prompts use the configured authenticated local API, with a saved message ID and native acceptance receipt. Uncertain submissions reconcile by ID without another POST or fallback terminal typing. Other agents retain terminal delivery; acceptance does not mean task completion.
  • Serial controls such as /recent /unmute validate together and run left-to-right. Launches, updates and permission answers still need separate messages.
  • Wide Markdown tables display as labelled rows on phones, preserving links and formatting without changing native history.
  • An exited or panicked embedded messaging worker stops the combined service so the existing supervisor can recover it.
  • Linux packaging selects the musl linker for MDK Markdown's math dependency. All four platform package lanes still need to qualify the repaired source.

See the 0.12.0 notes for credits and the MDK storage boundary, and the release handoff for evidence and outstanding checks. These are source changes, not an installed update.

Released in 0.11.2

  • Phone permission cards accept ordinary 1 or 2 replies for allow-once or deny. Scrolling command blocks remain, without approval codes or quoted replies.
  • OpenCode V2 multi-part questions save each answer across restarts and submit the complete form after the final part.
  • /recent sends conversations oldest-first with five seconds between confirmed conversation batches. Live replies do not wait for catch-up.
  • /last and /recent use shared native readers and collect in the background. Their pending requests survive restarts without holding phone input dispatch.
  • Unchanged state no longer causes repeated writes, syncs or JSON encoding. Cached forwarding controls, targeted read completion and shared histories reduce repeated reads, copies and session scans.
  • Background recovery uses bounded payload storage and retry backoff. Full-history scans still recover unseen older messages without pruning receipts.
  • Late native acceptance clears stale delivery warnings. Interrupted OpenCode service reads retry once, without retrying submissions or replacing the server.

See the release notes for measurements, verification limits, upgrade guidance and contributor credits.

Retained from 0.11.1

  • Clear status labels use Request submitted... and Working... for progress, then Done. for completion. Acceptance checks and safety warnings remain.
  • Native acceptance checks distinguish terminal delivery from agent receipt. Unconfirmed submissions produce a warning and pause that chat, without retries.
  • Editable image/file receipts show preparation, download, completion, waiting, or failure without adding a new bubble for each stage.
  • Confirmed phone answers resume the current question turn's future replies, without replaying old muted replies or overriding /sync off.
  • Project setup accepts nested paths and ls apps/ to browse a subfolder's directories and non-selectable files before confirmation. Use /cd apps during folder selection so plain ls and new paths use that location.
  • Resuming after a question brings a fresh working/checklist bubble to the bottom of the chat, leaving Task continued below. in the old progress message.
  • Question cards show the question and choices without internal headings or repeated titles. Required changed-question safety notices remain.
  • Ordinary follow-ups no longer answer a completed custom question. Explicit stale answers remain blocked, including after a restart.
  • Mobile-created agents clear their temporary codr-… name after startup.
  • Fresh-session chat titles include an agent suffix only while another live project chat shares the same tab/workspace title.
  • The current account-creation helper defaults to 👾. Existing profiles and the supported 0.9.0 bootstrap keep their naming behaviour.

See the release notes for scope and credits, and the readiness record for verification and publication gates.

Retained from 0.11.0

  • Completed Claude replies reach the phone while background tasks keep the session working. System task notifications do not count as local typing or mute forwarding, and completed same-turn replies remain available.
  • Progress keeps its existing bubble until the session settles, without leaving an unfinished replacement after a completed background reply.
  • A no-update check says No new version available. Currently running codr VERSION. It does not claim that an installation occurred.
  • Integrates Juraj Bednar's PR #20. Corrected adaptations of PRs #17–19 remain from 0.9.0.

Retained from 0.10.0

  • One executable hosts bridge and messaging in one managed service. Chat upgrades keep the existing worker service name.
  • /update confirm needs no code and updates both embedded components together.
  • Existing 0.9 users have a two-stage chat upgrade: first the bridge-only update, then a separately confirmed cold backup and combined-service handover. The first step still uses 0.9's old confirmation code. Supported managed installations need no terminal commands. Upgrade details. This implementation targets existing accounts.
  • Large OpenCode histories use bounded 100-message pages instead of full exports, so the 128 MiB reader limit no longer blocks synchronization of the whole export.
  • New verified native sessions get separate chats, including on reused terminals. Native V2 decision choices use their verified form API, and project menus are shorter.

Retained from 0.9.0

  • Read this chat's latest message with /last, or several with /last4, without resuming sync. /recent [hours] keeps its three-message excerpt per active chat.
  • Search existing project folders with ls <part> in /new. Results keep 200-folder pages, next/previous navigation and restart-safe selection. Bare ls clears the search and refreshes the full list.
  • Use an optional non-owning OpenCode HTTP reader: failed reads cannot start or replace the shared server. CLI fallback retries only incomplete JSON.
  • Start fresh Claude chats before a transcript exists, and reduce repeated warnings without hiding first-occurrence errors when the logging cache fills.
  • Keep history and accepted deliveries when /cancel clears stale chat controls. History excerpts show original UTC source dates rather than the request time.

Juraj Bednar's folder filtering, fresh-Claude-session and logging contributions are adapted with fixes and regression tests. His approved macOS launchd fix is retained. See the release notes for contributor credits and scope.

Usage

Upgrading from 0.6.0 or an older MDK 0.13 installation? 0.7.0 uses MDK 0.14. Before first opening that storage with the new connector, stop the services and keep a private, device-local backup of the complete connector home and secret-store credentials. The migration is one-way; downgrading to MDK 0.13 is unsupported. Setup refuses an automatic cross-cohort upgrade. Follow the upgrade guide and 0.7.0 notes; do not bypass the backup gate. Existing MDK 0.14 installations retain their account and chat history.

  1. Check the inviter against the bridge public key printed by setup, then accept the session's chat invitation.
  2. Send /status to check the connection. Send a prompt to continue that session.
  3. Read the reply in the same chat. For a supported decision, reply 1, 2, or an exact option label.
Command What it does
/help Show commands and the current sync mode.
/update Check stable ngit releases. Confirm an application update or the separate 0.9-to-combined service handover.
/status Show connection, state and pending deliveries; resume sync in automatic mode.
/recent [hours] Get the newest three text messages from each chat active in the past hour, or the specified number of hours. /recent2 and /recent 2 are equivalent. Send conversations oldest-first, with five seconds between confirmed batches. Skip messages already delivered or pending.
/last [count] Replay the newest message in this chat without unmuting. /last4 and /last 4 replay four messages, including already delivered text. Count: 1–100.
/new Set up a project, with a final name confirmation.
/agent Choose an agent in a separate session and chat.
/model Choose a model; OpenCode supports a confirmed idle-session change in place.
/cancel Clear pending questions and menus in this chat and interrupt its current task, keeping history and accepted deliveries.
/queue Inspect pending media, accepted deliveries and native-acceptance state.
/unmute Resume all chats and clear a forced sync mode.
/sync auto|on|off Use automatic sync, always on, or always off. The choice persists across restarts.

In 0.7.0, /recent replaces the old catch-up /sync command. It sends each eligible chat's excerpt to that chat, with You and Agent labels. Help and history retrieval do not prompt agents or change sync mode. /last is an explicit replay for the current agent chat only; it does not use /recent's activity window or skip already delivered text.

Catch-up messages include each source message's date and time in UTC under its sender label. Missing or invalid source timestamps show Date unknown, not the time of the catch-up request. Adding dates does not reset duplicate protection.

/cancel is a chat-scoped soft reset, including when the agent is idle. It clears cached questions, permission cards, pending setup/model menus and update offers. It does not restart services, stop other sessions, change the selected model, or discard accepted deliveries. Records of uncertain external operations remain for reconciliation. An interrupt acknowledgement does not prove the agent has stopped.

New phone text does not join a worker-scheduled task queue. Messages are delivered without an interrupt; a backend can still use its own native inbox. A blocked permission or decision requires its supported answer or /cancel, not an arbitrary prompt. After 60 seconds without confirmed native acceptance, Codr warns and pauses new submissions in that chat; inspect the native session before local clear-prompt. Media still needs download/transcription, and accepted deliveries are preserved across upgrades. /clear-queue is retired and does not discard those deliveries. An uncertain submission is never automatically retried.

Handoff is automatic. Manual controls remain available through herdr's White Noise forwarding: At desk / Away action. Controls and limits →

Phone updates: /update shows an offer; reply /update confirm within ten minutes in 0.10, with no code. /update cancel dismisses it. The first 0.9-to-0.10 update keeps the external connector and still uses 0.9's displayed code. Send /update again in 0.10 to confirm the private cold backup and combined-service handover. Supported standard installations need no shell commands. Later combined updates replace bridge and messaging together. Unsupported layouts and storage migrations still require local setup. Upgrade details → · Update safety →

To test an update, wait for the stable release and its verified ngit/Blossom mirror, then send /update from the owner's phone. Check the offered version before using the confirmation command. A CI artifact or GitHub-only release is not discoverable by this command. Cancel if the version is not the one you intend to test; do not bypass the signature, checksum or connector-cohort checks.

Control chat

Session chats are tied to native agent sessions. Their history remains after a session ends, and restoring that session reconnects its existing chat. Set control_chat = true in the bridge config and restart the worker to add one owner-only chat called codr control. The bridge invites your phone on the next start and keeps the chat when sessions are renamed or end.

Send /new there to start a project, or use /help, /status, /recent, /queue, /sync, and /unmute. /agent, /model, and /cancel need a session chat. Plain text gets a short hint instead of reaching an agent. This is also where /new works on a fresh install before any session chat exists. Control chat reference →

How it works

White Noise ↔ MDK ↔ codr ↔ herdr ↔ your agent

MDK handles identity, encrypted messaging, and relays. codr routes prompts through herdr and reads completed replies from existing agent transcripts.

Reply collection uses existing transcripts without an additional model call or terminal scraping. Behaviour and recovery

OpenCode can use incremental, read-only SQLite reads instead of full exports. Reader configuration

Limits: Decision replies support OpenCode single-choice questions with 1–9 options. Other dialogs need the terminal. Avoid simultaneous terminal/phone answers. Decision compatibility · Media and audio

Agent screenshots: A new completed reply containing ![Screenshot](path/to/screenshot.png) sends the image as an encrypted White Noise attachment. Files must be inside that session's working directory or /tmp/opencode. Ordinary links are not uploaded. Existing installations need the connector's private outbound-media spool enabled; see outbound images.

Roadmap

Planned work and completed items.

Features in action

Explore the fictional Garden planner project through real herdr and White Noise interfaces. Phone close-ups show real command replies in the stock Android app; click them for the full app view. Side-by-side demos use scripted agent replies, encrypted messages, and local speech-to-text. Capture details.

Start a project

Send /new to choose an existing workspace or create one. Nothing starts before the final confirmation.

The phone sends /new, then codr replies with workspace choices and 0. Cancel

Choose a model

Send /model in an idle OpenCode chat to browse providers. The current model stays unchanged until confirmation.

The phone sends /model, then codr replies with OpenAI, Claude, and Free provider choices

Follow progress

Read working status and task progress in the session chat. Editable checklists require edit_responses = true.

herdr with the Garden planner task checklist beside matching working status and editable tasks in White Noise

Share a project

Alex invited Sam to the Garden planner chat. Sam can discuss the project, but only Alex's messages reach the agent.

Alex, Sam, and codr in a three-member White Noise chat, with only Alex's request shown in herdr

Send an image

Attach a design from your phone so the agent can review the downloaded image.

A watering-reminder design uploaded in White Noise beside its downloaded local image path and scripted review in OpenCode

Send a voice message

Record a message on your phone; local speech-to-text turns it into an agent prompt.

A White Noise audio message and transcribing status beside the actual Phonon-2 transcript sent to the demo agent

Answer a decision

Reply with a number to answer a supported OpenCode question without returning to the terminal.

A ten-minute snooze decision in OpenCode beside the White Noise question card, phone reply 1, and choice confirmation

Read a review

Read the agent's review in the same chat, alongside the matching herdr session.

The herdr review tab beside its White Noise chat, both showing checks for the Garden planner watering reminder

Keep sessions separate

Each herdr session has its own chat. To collect them in one place, open White Noise's Folders settings, create an intelligent folder, and filter it by the bridge account (the full public key is printed during setup). New codr chats join the folder automatically, and renaming a chat does not move it out.

Six Garden planner session tabs in herdr beside their six matching chats in a White Noise Garden folder


Operating reference · Changelog · Releases

Built on herdr, White Noise, MDK, and the Marmot protocol. Full credits.

About

Encrypted White Noise chats for local herdr coding agents. Primary source, issues, PRs, CI and releases: https://github.com/tidley/codr. Independent ngit mirror linked below.

Resources

Contributing

Stars

7 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages