{"id":49118812,"url":"https://github.com/ryan-guo123/relay-codex","last_synced_at":"2026-05-31T02:03:15.556Z","repository":{"id":351295410,"uuid":"1210371527","full_name":"Ryan-Guo123/relay-codex","owner":"Ryan-Guo123","description":"App-native project relay for Codex: repo-local state, drift detection, stuck recovery, and automation packs.","archived":false,"fork":false,"pushed_at":"2026-04-14T11:32:17.000Z","size":572,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-21T09:47:54.903Z","etag":null,"topics":["ai-agent","codex","codex-app","developer-tools","open-source","productivity","workflow-automation"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ryan-Guo123.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-14T10:55:30.000Z","updated_at":"2026-04-14T11:32:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Ryan-Guo123/relay-codex","commit_stats":null,"previous_names":["ryan-guo123/relay-codex"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Ryan-Guo123/relay-codex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ryan-Guo123%2Frelay-codex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ryan-Guo123%2Frelay-codex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ryan-Guo123%2Frelay-codex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ryan-Guo123%2Frelay-codex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ryan-Guo123","download_url":"https://codeload.github.com/Ryan-Guo123/relay-codex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ryan-Guo123%2Frelay-codex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33716342,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","codex","codex-app","developer-tools","open-source","productivity","workflow-automation"],"created_at":"2026-04-21T09:35:42.183Z","updated_at":"2026-05-31T02:03:15.551Z","avatar_url":"https://github.com/Ryan-Guo123.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Relay for Codex\n\n![Relay for Codex hero](docs/assets/relay-cover.png)\n\n[![Tests](https://github.com/Ryan-Guo123/relay-codex/actions/workflows/tests.yml/badge.svg)](https://github.com/Ryan-Guo123/relay-codex/actions/workflows/tests.yml)\n[![MIT License](https://img.shields.io/badge/license-MIT-0f172a.svg)](LICENSE)\n[![Codex App](https://img.shields.io/badge/Codex%20App-native-f97316.svg)](plugins/relay-codex/.codex-plugin/plugin.json)\n[![Stars](https://img.shields.io/github/stars/Ryan-Guo123/relay-codex?style=social)](https://github.com/Ryan-Guo123/relay-codex/stargazers)\n\nRelay for Codex is an open-source maintainer workflow layer for long-running Codex work: triage, review, stuck recovery, and release handoff.\n\nRelay does not try to run agents, replace Codex Goals, become another kanban board, or compete with local-first memory tools. It is a narrow Codex App-native handoff adapter: after a Codex run, it produces GitHub-ready maintainer artifacts inside the repo.\n\n![Relay demo: repo state to handoff and release checklist](docs/assets/relay-demo.gif)\n\nIf Relay saves you from session drift or endless test churn, give the repo a star.\n\n## Why this exists\n\nCodex Goals can keep work moving inside a thread. The failure mode starts later, when that work has to become something a maintainer can review, merge, or release:\n\n- the thread summary is hard to reuse in GitHub\n- the PR description misses evidence, risks, or review notes\n- release readiness lives in chat instead of the repo\n- a future maintainer cannot tell what changed, what was checked, and what still needs review\n\nRelay exists for the moment after a Codex Goal or agent run:\n\n```text\nissue/task -\u003e Codex Goal/run -\u003e repo evidence -\u003e PR comment or release gate\n```\n\nIt answers one maintainer question:\n\n\u003e \"What can I paste into GitHub so a maintainer understands what happened, what was checked, and what still needs review?\"\n\nRelay adds a thin repo-local packaging layer on top of Codex App:\n\n- repo-local state under `.relay/`\n- a four-state verdict:\n  - `continue`\n  - `paused`\n  - `needs_human`\n  - `needs_review`\n- lightweight hooks for activity tracking\n- recovery notes when work starts to churn\n- handoff and release artifacts that can be reused in PRs and release notes\n\n## Is this already solved?\n\nPartly. The agent-tooling market is crowded:\n\n- Codex Goals track a thread-scoped objective and completion contract.\n- Claude Managed Agents and OpenAI Symphony point toward hosted or orchestrated long-running agent work.\n- Paperclip, vibe-kanban, and Warp-style workflows make agent work visible through dashboards, boards, branches, and PR UI.\n- agentmemory stores broad cross-agent recall.\n- skills packs package reusable engineering workflows.\n\nRelay should not compete with those layers.\n\nRelay's narrow job is downstream of them: after an agent run touches a repository, Relay writes the maintainer evidence that should survive the session.\n\n```text\nNot:  \"Run my agents.\"\nNot:  \"Remember everything.\"\nNot:  \"Replace my issue tracker.\"\nYes:  \"Turn this Codex run into a maintainer-readable PR or release handoff.\"\n```\n\nIf that handoff is not better than asking Codex to summarize the thread, Relay should shrink, pivot, or stop. The current product bet is intentionally small.\n\n## What makes Relay different\n\n- App-native, not CLI-first\n  - Relay is built around Codex App primitives such as skills, hooks, automations, and review-oriented follow-up.\n- Repo-local and handoff-friendly\n  - Project state lives in files that another human or agent can inspect.\n- Built to catch churn\n  - Repeated failures, test-only loops, and stalled progress are treated as signals, not “keep going harder” instructions.\n- Small surface area\n  - Relay focuses on keeping work moving. It does not try to become another prompt marketplace or agent framework.\n\nThe product strategy lives in [docs/product-strategy.md](docs/product-strategy.md), the stricter market map lives in [docs/market-map.md](docs/market-map.md), community pain research lives in [docs/community-research.md](docs/community-research.md), the validation plan lives in [docs/validation-plan.md](docs/validation-plan.md), and the `.relay/` artifact protocol lives in [docs/relay-protocol.md](docs/relay-protocol.md). The short version: Relay should be a GitHub handoff adapter for Codex-heavy work, not a clone of broader multi-agent control planes, memory engines, or local-first evidence ledgers.\n\n## Core pieces\n\n### 1. Project Relay\n\nTurns the current repository into a Relay-managed workspace by creating:\n\n- `.relay/mission.md`\n- `.relay/state.md`\n- `.relay/queue.md`\n- `.relay/guardrails.md`\n- `.relay/automations.md`\n- `.relay/events.jsonl`\n\n### 2. Handoff Monitor\n\nThe runtime inspects repo context, recent events, and repeated failure patterns to package the current work state as:\n\n- continue\n- pause\n- escalate to a human\n- switch into recovery mode\n\nThat status is an input to PR and release handoff, not a replacement for Codex Goals.\n\n### 3. Automation Packs\n\nRelay renders three starter packs:\n\n- `Continue Working`\n  - Preserve a clear follow-up note when the repo state says more work is safe.\n- `Daily Triage`\n  - Produce a concise daily project status summary.\n- `Stuck Recovery`\n  - Generate a recovery brief when the project starts looping or failing repeatedly.\n\n## How it works\n\n1. Install `Relay for Codex`.\n2. In a repo, run `Enable Relay in this repo`.\n3. Relay creates `.relay/` and infers the project stack, commands, queue, and guardrails.\n4. The `PostToolUse` hook records events into `.relay/events.jsonl`.\n5. `inspect-relay-state` or `continue-with-relay` reads the latest verdict before more work is requested.\n6. `recover-stuck-project` rewrites the queue into smaller, recovery-first steps when the repo is stuck.\n7. `generate-relay-handoff` writes `.relay/handoff.md` for PR, release, or future-Codex pickup.\n8. `generate-release-checklist` writes `.relay/release-checklist.md` before tags or GitHub releases.\n9. `install-relay-automations` turns the current state into repeatable Codex App follow-up.\n\n## Example `.relay/` snapshot\n\n```text\n.relay/\n  mission.md       -\u003e What this repo is trying to achieve\n  state.md         -\u003e Current verdict, recent progress, current blockers\n  queue.md         -\u003e The next concrete tasks\n  guardrails.md    -\u003e When to stop, escalate, or recover\n  handoff.md       -\u003e Maintainer-ready PR or release handoff\n  release-checklist.md -\u003e Verification, versioning, tag, and approval steps\n  automations.md   -\u003e Suggested automation packs\n  events.jsonl     -\u003e Lightweight event log from hooks\n```\n\n## Quick start\n\n### Option A: use the local plugin bundle\n\n1. Clone this repository.\n2. Make sure the local marketplace entry remains available at `.agents/plugins/marketplace.json`.\n3. Open the workspace in Codex App and install `Relay for Codex`.\n4. In the target repository, use `Enable Relay in this repo`.\n\nFor full setup steps, success checks, and troubleshooting, see [docs/install.md](docs/install.md).\n\nSee [docs/demo-usage.md](docs/demo-usage.md) for a concrete PR triage and stuck-recovery example. The demo GIF is generated from real Relay runtime output; its storyboard and acceptance criteria live in [docs/demo-storyboard.md](docs/demo-storyboard.md).\n\n### Option B: develop the plugin itself\n\n1. Open this repository in Codex App.\n2. Edit files under `plugins/relay-codex/`.\n3. Run the validation suite:\n\n```bash\npython3 -m unittest discover -s tests -p 'test_*.py'\n```\n\n## Included skills\n\n- `enable-relay`\n- `continue-with-relay`\n- `inspect-relay-state`\n- `recover-stuck-project`\n- `generate-relay-handoff`\n- `generate-release-checklist`\n- `install-relay-automations`\n\n## Repository layout\n\n```text\n.agents/plugins/marketplace.json\nplugins/relay-codex/\n  .codex-plugin/plugin.json\n  assets/\n  hooks.json\n  scripts/relay_runtime.py\n  skills/\ntests/\ndocs/\ntools/\n```\n\n## Current status\n\nRelay is intentionally narrow in v1. It already covers:\n\n- repo-local state bootstrapping\n- hook-driven event tracking\n- stuck-project detection\n- recovery queue generation\n- maintainer handoff generation\n- release checklist generation\n- automation pack rendering\n- fixture-backed tests for empty, in-progress, and stuck repositories\n\nPlanned next:\n\n- packaged marketplace distribution once the plugin leaves local-bundle install\n- higher-quality narrated walkthrough after the first runtime-generated GIF\n- validation workflows for PR handoff, stuck recovery, and release handoff\n- more opinionated automation setup\n- stronger review queue handoff patterns\n- a tighter boundary with Codex's native goal and continuation features\n\n## Contributing\n\nBug reports, repro cases, workflow ideas, and pull requests are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md). Security boundaries and reporting guidance live in [SECURITY.md](SECURITY.md).\n\n## Launch notes\n\nIf you want this project to travel, do not just ship code. Ship a clear before/after story, a real PR/release handoff demo, and a short clip that shows Relay turning Codex work into a maintainer-readable artifact. A maintainer-facing launch checklist lives in [docs/launch-playbook.md](docs/launch-playbook.md), and the first runtime-generated demo lives in [docs/assets/relay-demo.gif](docs/assets/relay-demo.gif).\n\n## 中文简介\n\nRelay for Codex 是一个专门为 Codex App 设计的维护者交接插件。它不是另一个 prompt 包，也不是 Codex Goals 的替代品，而是在 Codex 跑完之后，把工作整理成 GitHub PR / release 能直接复用的交接材料：\n\n- 把项目状态落到仓库本地的 `.relay/` 文件里\n- 把验证、风险、review focus 和下一步写成可审阅的 handoff\n- 在发现反复失败、空转测试、重复提问时，明确标出需要人工 review 的点\n- 给出适合 PR 更新、release checklist 和后续 Codex App 跟进的材料\n\n### 它解决的问题\n\n- Codex 线程里的结论很难直接搬到 GitHub\n- PR 描述容易漏掉测试、风险和人工 review 点\n- release 前的检查步骤散落在聊天记录里\n- 后来的维护者不知道哪些已经做过、哪些还需要看\n\n### 快速开始\n\n1. 安装 `Relay for Codex`\n2. 在仓库里执行 `Enable Relay in this repo`\n3. 查看生成的 `.relay/` 文件\n4. 按需要继续使用：\n   - `inspect-relay-state`\n   - `continue-with-relay`\n   - `recover-stuck-project`\n   - `install-relay-automations`\n\n### 为什么更容易被 star\n\n因为它讲的不是“再造一个 agent runtime”，而是一个更具体的结果：\n\n- 把 Codex 的长任务输出变成维护者能审阅的 GitHub 交接物\n- 让仓库里有可见、可交接、可发布前检查的状态\n- 避开 Codex Goals、memory tools 和 kanban products 已经占住的地盘\n\nLicense: MIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryan-guo123%2Frelay-codex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fryan-guo123%2Frelay-codex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryan-guo123%2Frelay-codex/lists"}