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

Revisions

  1. myobie created this gist Mar 17, 2026.
    52 changes: 52 additions & 0 deletions CCMAILBOX.md
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,52 @@
    # 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

    ```markdown
    ---
    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