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
$ pot do new --kind research --status ready -- \
    "How does fsnotify behave under APFS on macOS?"
01HXR2N7Z3WBT4VQK0S1FYEZ0M

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

# 3. 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
├── 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

inbox → ready → in_progress → done ↓ blocked (CANCEL, crash, or pot agent blocked)

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

In

Vault = source of truth
Claude Code as the agent
Bash subcommands, no MCP
Single static binary, Nix-built
Whatever chat client you already run

Out

Server, database, web UI
SSH workers, multi-host
Linear / GitHub Issues sync
Token-by-token streaming to chat
Anything aimed at a team

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 -- --version

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