Markdown files in.
Markdown files out.
Claude in between.

A single Haskell binary watches a directory of task files, claims any one marked ready, runs claude -p against the working directory it names, and writes the result back into the same vault. No server. No database. No MCP.

The whole protocol

# 1. drop a task in the vault (starts in inbox)
$ pot do new --kind research \
    --title "How does fsnotify behave under APFS on macOS?"
01HXR2N7Z3WBT4VQK0S1FYEZ0M

# 2. promote when you're ready for it to run
$ pot do ready 01HXR2N7Z3WBT4VQK0S1FYEZ0M

# 3. run the watcher (or let systemd do it)
$ pot do watch --vault ./vault

# 4. read what came back
$ cat vault/tasks/01HXR.../findings.md

What the vault looks like

vault/tasks/01HXR2N7Z3.../
├── task.md            # the prompt + frontmatter
├── transcript.md      # everything Claude did, in order
├── transcript.jsonl   # the raw claude -p stream, one event per line
├── findings.md        # the answer (for research / design)
├── plan.md            # proposed plan (delegate mode)
├── questions/
│   ├── 001.md         # Claude asks
│   └── 001.answer.md  # you (or your chat bot) reply
└── meta.yaml          # session id, cost, tokens, thread binding

How a task moves

Human-in-the-loop, by default

Claude can stop mid-task and ask for a decision. pot agent ask writes a question file and blocks until you answer — from a terminal, an editor, or a chat bot watching the same directory.

# inside the spawned claude:
$ pot agent ask "Should this ship as a CLI or a daemon?" \
    --options "cli,daemon,both"
(blocks until questions/001.answer.md appears)
cli

What's in / what's out

The chat surface is yours

Mobile and desktop interaction goes through any vault-aware chat client. Horizon (Telegram-native) and OpenClaw (multi-channel) are the two reference integrations; anything that can watch files and run bash can play the role. Potentiality doesn't know whether a chat surface exists.

Run it

$ nix run github:purplenoodlesoop/potentiality -- --help