How it works
PromptRelay coordinates AI execution between maintainers and volunteers. GitHub is the maintainer interface; the volunteer CLI/TUI is the execution interface. The platform never touches provider credentials or compute. It only routes tasks and collects results.
1. Maintainer installs the GitHub App
PromptRelay receives maintainer requests through a GitHub App. The maintainer installs the app on the repositories where @promptrelay should work, then selects repository access during installation. Without the GitHub App, GitHub will not send PromptRelay issue or pull request comments, and PromptRelay cannot post results or open PRs.
2. Volunteer installs the CLI daemon
A volunteer opens the settings TUI, authenticates via GitHub device flow, and configures their local daemon. The daemon is started explicitly with promptrelay start. The daemon polls Convex for queued tasks from trusted projects. Configuration lives in ~/.config/promptrelay-volunteer, including max tasks per day, trusted projects, manual approval, and enabled providers.
3. Maintainer creates a task
In a GitHub issue or pull request, a maintainer invokes PromptRelay with a free-form prompt such as @promptrelay add a regression test for the login callback. The GitHub webhook verifies the request and queues the maintainer's message in Convex with status queued.
4. Daemon claims and executes
When the daemon finds an eligible task, the volunteer approves it unless auto-approve is enabled. After approval, it claims the task (status moves to claimed, then running). Under the hood, the executor spawns claude -p <prompt> --output-format text --permission-mode bypassPermissions (or the Codex equivalent: codex exec --dangerously-bypass-approvals-and-sandbox <prompt>) as a child process inside the cloned repo. The executor gets a basic system prompt explaining that the repo is already cloned, that it should follow the maintainer's prompt, and that PromptRelay will handle commit, push, and PR creation if files are changed. If the task has a publicRepoUrl, the daemon clones or pulls the repo into ~/.promptrelay/repos/ and creates a working branch promptrelay/<task-id> before execution. Streaming output from Claude Code is pushed back to the maintainer in real time every 500ms via tasks:updateStream.
5. Result posted back to GitHub
On completion, the daemon writes the result back through tasks:complete with the output content, provider used, model, and execution duration. If execution only produces text, PromptRelay posts that result back to the GitHub thread. If files changed, the daemon commits the diff, pushes the working branch, and opens a pull request via the GitHub CLI automatically.
6. What stays local
API keys, model access, and compute are the volunteer's. The platform stores task metadata, prompts, and results in Convex. No credentials cross the network. The volunteer's daemon controls what it runs: daily limits, manual approval mode, enabled providers, and a trusted-projects allowlist.