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.
- 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
/cancelwhen you do want to interrupt the current task. /newguides you through workspace, folder, installed agent, and model selection. Reply with numbers, use0to 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.
/agentopens 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
1to allow once or2to 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 onor/sync offkeeps your explicit choice across restarts;/unmuterestores 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.
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.setupEnter 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 →
- 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 /unmutevalidate 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.
- Phone permission cards accept ordinary
1or2replies 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.
/recentsends conversations oldest-first with five seconds between confirmed conversation batches. Live replies do not wait for catch-up./lastand/recentuse 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.
- Clear status labels use
Request submitted...andWorking...for progress, thenDone.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 appsduring folder selection so plainlsand 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.
- 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.
- One executable hosts bridge and messaging in one managed service. Chat upgrades keep the existing worker service name.
/update confirmneeds 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.
- 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/previousnavigation and restart-safe selection. Barelsclears 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
/cancelclears 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.
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.
- Check the inviter against the bridge public key printed by setup, then accept the session's chat invitation.
- Send
/statusto check the connection. Send a prompt to continue that session. - 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.
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 →
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  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.
Planned work and completed items.
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.
Send /new to choose an existing workspace or create one. Nothing starts before the final confirmation.
Send /model in an idle OpenCode chat to browse providers. The current model stays unchanged until confirmation.
Read working status and task progress in the session chat. Editable checklists require edit_responses = true.
Alex invited Sam to the Garden planner chat. Sam can discuss the project, but only Alex's messages reach the agent.
Attach a design from your phone so the agent can review the downloaded image.
Record a message on your phone; local speech-to-text turns it into an agent prompt.
Reply with a number to answer a supported OpenCode question without returning to the terminal.
Read the agent's review in the same chat, alongside the matching herdr session.
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.
Operating reference · Changelog · Releases
Built on herdr, White Noise, MDK, and the Marmot protocol. Full credits.