Skip to content

Instantly share code, notes, and snippets.

@myobie

myobie/CCMAILBOX.md

Created March 17, 2026 14:33
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save myobie/b5c102af0e5181aa25019ed35b92572d to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save myobie/b5c102af0e5181aa25019ed35b92572d to your computer and use it in GitHub Desktop.
Download ZIP
ccmailbox pattern — just files + a real Claude Code session for async bidirectional communication
Raw
CCMAILBOX.md

ccmailbox pattern

Just files + a real Claude Code session. A folder with simple conventions that gives any local process fully async conversational, bidirectional communication with a running Claude Code session. No special hooks, no SDK, no patches. The Claude Code session continues to work, is not blocked, you can still work there too.

How it works

  1. Agree on the folder location. The local process (web server?) sees all files Claude Code wrote into the folder.
  2. The local process writes a file to requests/ (the mailbox folder) (web server can expose a POST so any browser can make new requests at any time)
  3. CronCreate inside Claude Code polls the mailbox folder every minute
  4. Claude reads the request, does work, and writes/edits files on disk into the folder
  5. The local process detects the file changes in the folder and picks up Claude's responses

That's it. The file system is the entire communication bus. The conventions — markdown + frontmatter with status: pending, short-id linking, the cron prompt — are what turn a folder into a conversation.

The folder

Claude Code creates this and fills it with whatever the initial context is. It also creates an empty requests/ mailbox folder.

The mailbox

---
status: pending
created: 2026-03-17T22:14:03Z
---

The message for Claude.

Add whatever fields make sense. The only required one is status: pending. Claude deletes the file after processing — the response lives wherever Claude wrote it (edited files, new files, inline in a doc, etc.).

The cron

CronCreate: "*/1 * * * *", recurring: true
Prompt: "List <mailbox>/, read any pending files, process them, delete when done"

Why this works

  • Just files — any language, any runtime, any process can participate
  • No external dependencies, no SDK, no hooks, no patches
  • Bidirectional — local process writes requests, Claude writes responses
  • Composable — multiple processes can write to the same mailbox
  • Local web apps can trigger Claude Code to do things (explain this, update this, go research this, etc) and then display the results
  • Works today with stock Claude Code

Limitations

  • 1-minute minimum latency (CronCreate granularity)
  • Session-scoped — dies when Claude exits (3-day auto-expiry)
  • Tokens consumed on every poll, even when empty
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment