Skip to content
Back to search

skydiscover

MarketplaceWorks with Claude CodeGitHub

SkyDiscover plugins for Claude Code. SkySynth builds a system specialized for your workload, hardware, and requirements, and checks it with tests or proofs.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/skydiscover-ai--skydiscover/badge.svg)](/listings/skydiscover-ai--skydiscover)

HTML

<a href="/listings/skydiscover-ai--skydiscover"><img src="/api/listings/skydiscover-ai--skydiscover/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires Python 3.10 to 3.13 and [uv](https://docs.astral.sh/uv/).

git clone https://github.com/skydiscover-ai/skydiscover.git
cd skydiscover
uv sync

Optimize needs an LLM API key; Synthesize needs a coding agent (each set up in its section below).

More setup options are in the [installation guide](docs/content/docs/installation.mdx).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 16 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "skydiscover",
  3. "owner": {
  4. "name": "SkyDiscover team"
  5. },
  6. "plugins": [
  7. {
  8. "name": "skysynth",
  9. "displayName": "SkySynth",
  10. "version": "0.2.0",
  11. "description": "/skysynth: coding agents build a system specialized for your workload, checked by tests or machine-checked proofs. Includes the /skysynth skill, the agent roles, and the hook that runs the tests before anything is delivered. Also install the skydiscover Python package: uv pip install git+https://github.com/skydiscover-ai/skydiscover (or run from a source checkout).",
  12. "source": "./skydiscover/synthesize/workflow"
  13. }
  14. ],
  15. "description": "SkyDiscover plugins for Claude Code. SkySynth builds a system specialized for your workload, hardware, and requirements, and checks it with tests or proofs."
  16. }
README.md · README · 218 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <h1 align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="assets/lockup-dark-bg.svg">
  4. <source media="(prefers-color-scheme: light)" srcset="assets/lockup-light-bg.svg">
  5. <img src="assets/lockup-light-bg.svg" height="80" alt="SkyDiscover logo" style="vertical-align: middle;">
  6. </picture>
  7. </h1>
  8. <p align="center">AI-driven scientific, algorithmic, and end-to-end systems discovery</p>
  9. <div align="center">
  10. [![Blog](https://img.shields.io/badge/Blog-FF6F00?logo=rss&logoColor=white)](https://skydiscover-ai.github.io/blogs.html)
  11. [![Documentation](https://img.shields.io/badge/Documentation-blue?logo=readthedocs&logoColor=white)](docs/)
  12. [![Slack](https://img.shields.io/badge/Slack-4A154B?logo=data%3Aimage/svg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NDggNTEyIj48cGF0aCBmaWxsPSJ3aGl0ZSIgZD0iTTk0LjEyIDMxNS4xYzAgMjUuOS0yMS4xNiA0Ny4wNi00Ny4wNiA0Ny4wNlMwIDM0MSAwIDMxNS4xYzAtMjUuOSAyMS4xNi00Ny4wNiA0Ny4wNi00Ny4wNmg0Ny4wNnY0Ny4wNnptMjMuNzIgMGMwLTI1LjkgMjEuMTYtNDcuMDYgNDcuMDYtNDcuMDZzNDcuMDYgMjEuMTYgNDcuMDYgNDcuMDZ2MTE3Ljg0YzAgMjUuOS0yMS4xNiA0Ny4wNi00Ny4wNiA0Ny4wNnMtNDcuMDYtMjEuMTYtNDcuMDYtNDcuMDZWMzE1LjF6bTQ3LjA2LTE4OC45OGMtMjUuOSAwLTQ3LjA2LTIxLjE2LTQ3LjA2LTQ3LjA2UzEzOSAzMiAxNjQuOSAzMnM0Ny4wNiAyMS4xNiA0Ny4wNiA0Ny4wNnY0Ny4wNkgxNjQuOXptMCAyMy43MmMyNS45IDAgNDcuMDYgMjEuMTYgNDcuMDYgNDcuMDZzLTIxLjE2IDQ3LjA2LTQ3LjA2IDQ3LjA2SDQ3LjA2QzIxLjE2IDI0My45NiAwIDIyMi44IDAgMTk2LjlzMjEuMTYtNDcuMDYgNDcuMDYtNDcuMDZIMTY0Ljl6bTE4OC45OCA0Ny4wNmMwLTI1LjkgMjEuMTYtNDcuMDYgNDcuMDYtNDcuMDYgMjUuOSAwIDQ3LjA2IDIxLjE2IDQ3LjA2IDQ3LjA2cy0yMS4xNiA0Ny4wNi00Ny4wNiA0Ny4wNmgtNDcuMDZWMTk2Ljl6bS0yMy43MiAwYzAgMjUuOS0yMS4xNiA0Ny4wNi00Ny4wNiA0Ny4wNi0yNS45IDAtNDcuMDYtMjEuMTYtNDcuMDYtNDcuMDZWNzkuMDZjMC0yNS45IDIxLjE2LTQ3LjA2IDQ3LjA2LTQ3LjA2IDI1LjkgMCA0Ny4wNiAyMS4xNiA0Ny4wNiA0Ny4wNlYxOTYuOXpNMjgzLjEgMzg1Ljg4YzI1LjkgMCA0Ny4wNiAyMS4xNiA0Ny4wNiA0Ny4wNiAwIDI1LjktMjEuMTYgNDcuMDYtNDcuMDYgNDcuMDYtMjUuOSAwLTQ3LjA2LTIxLjE2LTQ3LjA2LTQ3LjA2di00Ny4wNmg0Ny4wNnptMC0yMy43MmMtMjUuOSAwLTQ3LjA2LTIxLjE2LTQ3LjA2LTQ3LjA2IDAtMjUuOSAyMS4xNi00Ny4wNiA0Ny4wNi00Ny4wNmgxMTcuODRjMjUuOSAwIDQ3LjA2IDIxLjE2IDQ3LjA2IDQ3LjA2IDAgMjUuOS0yMS4xNiA0Ny4wNi00Ny4wNiA0Ny4wNkgyODMuMXoiLz48L3N2Zz4%3D)](https://join.slack.com/t/skydiscover/shared_invite/zt-48y5bloat-iZCMDv98OQTo3TXX97s80g)
  13. [![License](https://img.shields.io/badge/License-Apache%202.0-2EA44F)](LICENSE)
  14. </div>
  15. SkyDiscover is an open-source framework from UC Berkeley that uses AI to discover better algorithms and build complete systems.
  16. 1. **Optimize**: improve an algorithm or a component of your system. You provide a way to score solutions, and evolutionary search finds programs that score better and better.
  17. 2. **Synthesize**: build an end-to-end system. You describe it in plain text or a formal spec, and coding agents build it specialized Just-in-Time for your workload, hardware, and requirements.
  18. SkyDiscover works with Claude Code, Codex, Cursor, and Pi, and with any OpenAI-compatible model.
  19. <p align="center">
  20. <img src="assets/skydiscover_overview.png" width="900" alt="SkyDiscover: Optimize evolves algorithms, prompts, and system components; Synthesize builds end-to-end specialized systems">
  21. </p>
  22. ## 📰 News
  23. - **[2026/09]** 🎉 We released SkyDiscover-Synthesize (SkySynth), which lets you build trustworthy Just-in-Time systems specialized for your workload! [[Blog](https://skydiscover-ai.github.io/blog-skysynth.html)]
  24. - **[2026/07]** 🎉 EvoX is accepted to COLM 2026!
  25. - **[2026/05]** 🎉 We released two papers on synthesizing end-to-end systems that are correct by proof [[Paper](https://arxiv.org/abs/2605.23109)] or by test [[Paper](https://arxiv.org/abs/2605.24096)]!
  26. - **[2026/03]** 🎉 SkyDiscover is accepted as an Industrial Spotlight paper at CAIS '26! [[Paper](https://doi.org/10.1145/3786335.3813221)]
  27. - **[2026/02]** 🎉 We open-sourced SkyDiscover, along with our two adaptive optimization algorithms, AdaEvolve [[Paper](https://arxiv.org/abs/2602.20133)] and EvoX [[Paper](https://arxiv.org/abs/2602.23413)]!
  28. ## 📦 Installation
  29. Requires Python 3.10 to 3.13 and [uv](https://docs.astral.sh/uv/).
  30. ```bash
  31. git clone https://github.com/skydiscover-ai/skydiscover.git
  32. cd skydiscover
  33. uv sync
  34. ```
  35. Optimize needs an LLM API key; Synthesize needs a coding agent (each set up in its section below).
  36. More setup options are in the [installation guide](docs/content/docs/installation.mdx).
  37. ## 🧬 SkyDiscover-Optimize
  38. SkyDiscover-Optimize evolves programs against your scoring function. Its two search algorithms, AdaEvolve and EvoX, achieve the strongest open-source results across ~200 benchmarks, and are used across industry including Google and Uber.
  39. - **Frontier-CS (172 problems)**: ~34% higher median score than OpenEvolve, GEPA, and ShinkaEvolve under the same budget
  40. - **Math + systems (14 tasks)**: matches or exceeds AlphaEvolve and human SOTA on 6/6 systems and 6/8 math tasks
  41. - **Real-world systems**: 41% lower cross-cloud transfer cost, 14% better GPU load balance for MoE serving, 29% lower KV-cache pressure
  42. ### Quick start
  43. Set the API key for your model provider, then evolve a program against your scoring function:
  44. ```bash
  45. export OPENAI_API_KEY=<your-key> # or ANTHROPIC_API_KEY / GEMINI_API_KEY
  46. uv run skydiscover optimize evaluator.py --search adaevolve --model gpt-5 -i 100
  47. # uv run skydiscover optimize evaluator.py --search evox --model gpt-5 -i 100
  48. ```
  49. | Algorithm | Flag | Description |
  50. |:---|:---|:---|
  51. | ⭐&nbsp;**AdaEvolve** | `--search adaevolve` | Adaptive search that tunes its own settings as it runs |
  52. | 🧠&nbsp;**EvoX** | `--search evox` | AI that optimizes its own optimization process |
  53. The [full Optimize guide](skydiscover/optimize/README.md) covers six more algorithms, evaluator formats, the Python API, and complete benchmark results.
  54. ## 🏗️ SkyDiscover-Synthesize
  55. SkyDiscover-Synthesize lets you build a system specialized for your own hardware, workload, and requirements, instead of adopting a one-size-fits-all one.
  56. It has synthesized key-value stores up to 2.3x faster than Redis and FASTER (plus formally verified distributed ones), LLM inference engines with up to 2.2x the throughput of vLLM and SGLang, and model routers at up to 48% lower cost; each is a checked-in [example](skydiscover/synthesize/examples/README.md) you can run.
  57. | Approach | Use it when | How it works |
  58. |:---|:---|:---|
  59. | [Formal-proof-driven](https://arxiv.org/abs/2605.23109) | You have a formal spec (e.g. Rocq) | Synthesizes the code and its machine-checked proof together, step by step |
  60. | [Test-driven](https://arxiv.org/abs/2605.24096) | You have a plain-text description | Agents iterate on the implementation; an auditor turns every reward hack it finds (a change that raises the score while breaking what you meant) into a new test |
  61. ### Quick start
  62. Install the `/skysynth` skill into the coding agent of your choice:
  63. ```bash
  64. uv run skydiscover init # wires every coding agent found on PATH; or --agent claude|cursor|codex|pi
  65. ```
  66. Then prompt the agent:
  67. ```
  68. /skysynth build me a fast in-memory key-value store
  69. ```
  70. On Claude Code or Codex you can also install it as a plugin:
  71. ```bash
  72. /plugin marketplace add skydiscover-ai/skydiscover # Claude Code
  73. /plugin install skysynth
  74. codex plugin marketplace add skydiscover-ai/skydiscover # Codex
  75. codex plugin add skysynth
  76. ```
  77. Your system lands in `outputs/synthesize/<slug>_<timestamp>/best/artifact/` (`<slug>` is a short name made from your prompt), with `spec.md` beside it saying what it guarantees and how it scored. The [full Synthesize guide](skydiscover/synthesize/README.md) covers how the agents work, both approaches, and adding a domain. The [tutorial](skydiscover/synthesize/examples/tutorial/) walks through a full synthesis; its notebook replays our run.
  78. ## 🤝 Contributing
  79. Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and pull request guidelines.
  80. ## ✍️ Citation
  81. If you use SkyDiscover, please cite the framework paper:
  82. ```bibtex
  83. @inproceedings{liu2026skydiscover,
  84. author = {Liu, Shu and Cemri, Mert and Agarwal, Shubham and Krentsel, Alexander and Naren, Ashwin and Mang, Qiuyang and Li, Zhifei and Gupta, Akshat and Maheswaran, Monishwaran and Cheng, Audrey and Pan, Melissa and Boneh, Ethan and Ramchandran, Kannan and Sen, Koushik and Zaharia, Matei and Dimakis, Alexandros G. and Stoica, Ion},
  85. title = {SkyDiscover: A Flexible, Adaptive Framework for AI-Driven Scientific and Algorithmic Discovery},
  86. booktitle = {Proceedings of the ACM Conference on AI and Agentic Systems},
  87. series = {CAIS '26},
  88. year = {2026},
  89. pages = {1223--1227},
  90. publisher = {Association for Computing Machinery},
  91. doi = {10.1145/3786335.3813221},
  92. url = {https://doi.org/10.1145/3786335.3813221}
  93. }
  94. ```
  95. If you use SkyDiscover-Synthesize, please also cite:
  96. ```bibtex
  97. @misc{liu2026skysynth,
  98. author = {Shu Liu and Shubham Agarwal and Alexander Krentsel and Mert Cemri and Sidharth Sankhe and Ziming Mao and Alexandros G. Dimakis and Matei Zaharia and Ion Stoica},
  99. title = {Building Specialized Systems that We Can Trust with Agents},
  100. year = {2026},
  101. month = sep,
  102. howpublished = {SkyDiscover Blog},
  103. url = {https://skydiscover-ai.github.io/blog-skysynth.html}
  104. }
  105. ```
  106. <details>
  107. <summary><b>Citations for the papers behind SkyDiscover-Optimize</b></summary>
  108. If you use the **AdaEvolve** search algorithm:
  109. ```bibtex
  110. @misc{cemri2026adaevolve,
  111. author = {Mert Cemri and Shubham Agrawal and Akshat Gupta and Shu Liu and Audrey Cheng and Qiuyang Mang and Ashwin Naren and Lutfi Eren Erdogan and Koushik Sen and Matei Zaharia and Alex Dimakis and Ion Stoica},
  112. title = {AdaEvolve: Adaptive LLM Driven Zeroth-Order Optimization},
  113. year = {2026},
  114. eprint = {2602.20133},
  115. archivePrefix = {arXiv},
  116. primaryClass = {cs.NE},
  117. url = {https://arxiv.org/abs/2602.20133}
  118. }
  119. ```
  120. If you use the **EvoX** search algorithm:
  121. ```bibtex
  122. @misc{liu2026evox,
  123. author = {Shu Liu and Shubham Agarwal and Monishwaran Maheswaran and Mert Cemri and Zhifei Li and Qiuyang Mang and Ashwin Naren and Ethan Boneh and Audrey Cheng and Melissa Z. Pan and Alexander Du and Kurt Keutzer and Alvin Cheung and Alexandros G. Dimakis and Koushik Sen and Matei Zaharia and Ion Stoica},
  124. title = {EvoX: Meta-Evolution for Automated Discovery},
  125. year = {2026},
  126. eprint = {2602.23413},
  127. archivePrefix = {arXiv},
  128. primaryClass = {cs.LG},
  129. url = {https://arxiv.org/abs/2602.23413}
  130. }
  131. ```
  132. </details>
  133. <details>
  134. <summary><b>Citations for the papers behind SkyDiscover-Synthesize</b></summary>
  135. If you use **formal-proof-driven synthesis** (Inductive Deductive Synthesis):
  136. ```bibtex
  137. @misc{agarwal2026ids,
  138. author = {Shubham Agarwal and Alexander Krentsel and Shu Liu and Mert Cemri and Audrey Cheng and Rui Meng and Tomas Pfister and Chun-Liang Li and Sylvia Ratnasamy and Aditya Parameswaran and Matei Zaharia and Ion Stoica and Mohsen Lesani},
  139. title = {Inductive Deductive Synthesis: Enabling AI to Generate Formally Verified Systems},
  140. year = {2026},
  141. eprint = {2605.23109},
  142. archivePrefix = {arXiv},
  143. primaryClass = {cs.AI},
  144. url = {https://arxiv.org/abs/2605.23109}
  145. }
  146. ```
  147. If you use **test-driven synthesis** (Just-in-Time Systems):
  148. ```bibtex
  149. @misc{liu2026jitsystems,
  150. author = {Shu Liu and Alexander Krentsel and Shubham Agarwal and Mert Cemri and Ziming Mao and Soujanya Ponnapalli and Alexandros G. Dimakis and Sylvia Ratnasamy and Matei Zaharia and Aditya Parameswaran and Ion Stoica},
  151. title = {The Time is Here for Just-in-Time Systems: Challenges and Opportunities},
  152. year = {2026},
  153. eprint = {2605.24096},
  154. archivePrefix = {arXiv},
  155. primaryClass = {cs.DB},
  156. url = {https://arxiv.org/abs/2605.24096}
  157. }
  158. ```
  159. </details>
  160. ## 📬 Contact Us
  161. Join our [Slack community](https://join.slack.com/t/skydiscover/shared_invite/zt-48y5bloat-iZCMDv98OQTo3TXX97s80g) for questions and discussion, or reach out to us directly:
  162. [lshu@berkeley.edu](mailto:lshu@berkeley.edu) · [akrentsel@berkeley.edu](mailto:akrentsel@berkeley.edu) · [mert_cemri@berkeley.edu](mailto:mert_cemri@berkeley.edu) · [shubham3@berkeley.edu](mailto:shubham3@berkeley.edu) · [sidharth_sankhe@berkeley.edu](mailto:sidharth_sankhe@berkeley.edu)
skydiscover/synthesize/workflow/scripts/unattended/supervisor.sh · Bundled script · 240 lines · 1 finding marked
  1. #!/usr/bin/env bash
  2. # Keep one tmux-hosted claude run driving itself: approve permission prompts, resume a dead run
  3. # from disk, and nudge a stalled one (no new on-disk artifact for a while) to checkpoint and continue.
  4. # Never restarts from scratch and never acts while a human is in the pane. Detection keys off the
  5. # pane's own process tree, not a global process match or the footer text. Exits once `run
  6. # finish` leaves .skydiscover/<slug>.done, or after MAX_RESTARTS restarts without progress. Provider env, if any, comes
  7. # from "<runs>/env.sh" (the runs folder: .skydiscover by default).
  8. #
  9. # Usage: supervisor.sh <tmux-session> <run-dir> [tmux-socket]
  10. # <run-dir> the root that contains .skydiscover/<slug>/
  11. # <tmux-socket> default ${TMPDIR:-/tmp}/skydiscover.<uid>.sock
  12. set -uo pipefail
  13. SESS="${1:?usage: supervisor.sh <session> <run-dir> [socket]}"
  14. RUNDIR="${2:?usage: supervisor.sh <session> <run-dir> [socket]}"
  15. SOCK="${3:-${TMPDIR:-/tmp}/skydiscover.$(id -u).sock}"
  16. POLL="${SKYDISCOVER_SUP_POLL:-60}" # seconds between checks
  17. STALL_STRIKES=25 # checks at an idle prompt with no new artifact before the run is nudged
  18. GEN_STALL_STRIKES=45 # checks while generating with no new artifact before the generation is cut;
  19. # a coding agent legitimately generates for many minutes, so the number is larger
  20. SAT_STALL_STRIKES=12 # checks for a lead whose context is full ("100% context used") before it is compacted
  21. DEAD_STRIKES=2 # checks with no claude process before the run is resumed
  22. FRESH_LEAD_AFTER=2 # compacts with no new artifact between them before a fresh lead is started;
  23. # a lead that compaction cannot recover refills its context at once
  24. CODING_AGENT_MAX_MIN=30 # a single coding agent running this long with no new code artifact is treated like a
  25. # saturated lead: compacted, then cut and re-driven by a fresh lead
  26. CPU_BUSY=20 # a non-claude process above this %CPU in the run's tree counts as heavy compute
  27. MAX_RESTARTS="${SKYDISCOVER_SUP_MAX_RESTARTS:-3}"
  28. # consecutive restarts with no on-disk progress between them before the supervisor
  29. # stops and exits with a diagnostic; any new artifact resets the count
  30. RUNS_REL="${SKYDISCOVER_RUNS:-$(python3 -m skydiscover.synthesize.spec.paths runs 2>/dev/null || echo .skydiscover)}"
  31. case "$RUNS_REL" in /*) RUNS="$RUNS_REL" ;; *) RUNS="$RUNDIR/$RUNS_REL" ;; esac # where the runs live (spec/paths.py runs())
  32. LOG="$RUNS/supervisor.$SESS.log"
  33. STOP="$RUNS/supervisor.$SESS.stop" # terminal marker; keepalive's watchdog honors it
  34. mkdir -p "$(dirname "$LOG")" 2>/dev/null || true
  35. say(){ echo "[$(date +%F' '%T)] $*" >> "$LOG"; }
  36. # Terminal condition. A finished run looks the same as a stuck one (no new artifacts, an idle prompt),
  37. # so completion is the .skydiscover/<slug>.done marker `run finish` leaves after deleting the run
  38. # directory. Only a marker newer than this session's start counts, so an earlier run's marker in the
  39. # same project does not end a new one. finish also drops a stop marker so the keepalive watchdog
  40. # does not relaunch the supervisor.
  41. START="$RUNS/supervisor.$SESS.start"
  42. [ -f "$START" ] || : > "$START"
  43. run_done(){ [ -n "$(find "$RUNS" -maxdepth 1 -name '*.done' -newer "$START" 2>/dev/null | head -1)" ]; }
  44. finish(){ # $1 = log line. Always exit 0: a nonzero exit would make systemd Restart= relaunch us.
  45. say "$1"
  46. : > "$STOP" 2>/dev/null || true
  47. rm -f "$START"
  48. exit 0
  49. }
  50. # Generic resume/continue prompt: point the agent at its OWN on-disk state. No domain text. The last
  51. # sentence is what lets the supervisor ever stop; it is the only completion signal it can trust.
  52. CONT="Continue the in-progress skysynth run from disk. Read the newest $RUNS_REL/<slug>/ directory (its README.md, task.md, decision log, specification/, and synthesis/bench/leaderboard.json) and resume EXACTLY where it left off; do NOT restart from scratch or re-create the layout. Work in small tested steps and checkpoint progress to the decision log as you go; fix+test every real defect; prod-ready is blocked while any defect is open; honest verified numbers only. The run is complete when the report is written and \`run finish <run> --export-to .\` exits 0: it publishes the result, deletes the run directory, and leaves $RUNS_REL/<slug>.done, which is the completion signal. If no $RUNS_REL/<slug>/ exists but a $RUNS_REL/<slug>.done does, the run is finished; do nothing. Hands-off."
  53. tm(){ tmux -S "$SOCK" "$@"; } # every tmux call on the run's socket
  54. send_prompt(){ # send a multi-line prompt then submit (double Enter clears the paste-collapse)
  55. tm send-keys -t "$SESS" -l "$1"; sleep 1
  56. tm send-keys -t "$SESS" Enter; sleep 1
  57. tm send-keys -t "$SESS" Enter
  58. }
  59. start_agent(){ # ensure a session exists and (re)launch claude, sourcing optional deployment env
  60. tm has-session -t "$SESS" 2>/dev/null || tm new-session -d -s "$SESS" -c "$RUNDIR"
  61. local rd_q runs_q; rd_q="$(printf '%q' "$RUNDIR")"; runs_q="$(printf '%q' "$RUNS")" # shell-escape (a quote/space can't inject)
  62. tm send-keys -t "$SESS" \
  63. "cd $rd_q; [ -f $runs_q/env.sh ] && . $runs_q/env.sh; claude --dangerously-skip-permissions" Enter
  64. sleep 15
  65. }
  66. # The pane's process tree: the pane_pid and every descendant, one PID per line.
  67. # This is what makes death/stall detection run-scoped instead of box-wide.
  68. proc_tree(){
  69. local p="$1" c
  70. [ -n "$p" ] || return 0
  71. printf '%s\n' "$p"
  72. for c in $(pgrep -P "$p" 2>/dev/null); do proc_tree "$c"; done
  73. }
  74. # Compact the lead's context, then tell it to continue from disk. Shared by the idle-stall and
  75. # hung-generation paths, so a lead whose context is full is actually freed, not re-prompted onto it.
  76. compact_and_continue(){
  77. tm send-keys -t "$SESS" Escape; sleep 1; tm send-keys -t "$SESS" Escape; sleep 2
  78. tm send-keys -t "$SESS" -l "/compact"; sleep 1; tm send-keys -t "$SESS" Enter
  79. for _i in $(seq 1 30); do sleep 10; tm capture-pane -p -t "$SESS" 2>/dev/null | grep -q "Compacting" || break; done
  80. send_prompt "$CONT"
  81. }
  82. # Start a fresh lead: kill every claude in this run's tree so the death-recovery path below relaunches a
  83. # clean agent that continues from disk. This is the escalation for a lead that /compact cannot free,
  84. # because a compacted context refills at once and a clean one does not. Never a restart from scratch.
  85. fresh_lead_restart(){
  86. local pid
  87. for pid in $tree; do case "$(tr '\0' ' ' < "/proc/$pid/cmdline" 2>/dev/null)" in *claude*) kill "$pid" 2>/dev/null;; esac; done
  88. sleep 3
  89. for pid in $tree; do case "$(tr '\0' ' ' < "/proc/$pid/cmdline" 2>/dev/null)" in *claude*) kill -9 "$pid" 2>/dev/null;; esac; done
  90. }
  91. # Free a stalled or saturated lead: compact in place, and escalate to a fresh lead once repeated
  92. # compacts stop producing on-disk progress. The compact count resets whenever a real artifact appears.
  93. unchoke(){
  94. compacts=$((compacts+1))
  95. if [ "$compacts" -ge "$FRESH_LEAD_AFTER" ]; then
  96. restarts=$((restarts+1))
  97. if [ "$restarts" -gt "$MAX_RESTARTS" ]; then
  98. finish "GIVING UP: $MAX_RESTARTS consecutive restarts produced no new on-disk artifact; the run is \
  99. finished or stuck, and re-driving it would only churn. Inspect $RUNS and this log, then delete \
  100. $STOP and relaunch the supervisor to resume."
  101. fi
  102. say "CHURN: ${compacts} compacts, still no new artifact -> FRESH-LEAD restart (clean context, continue-from-disk; restart $restarts/$MAX_RESTARTS)"
  103. fresh_lead_restart; compacts=0
  104. else
  105. compact_and_continue
  106. fi
  107. }
  108. say "supervisor start: session=$SESS rundir=$RUNDIR socket=$SOCK"
  109. dead=0; stall=0; genstall=0; compacts=0; restarts=0
  110. while true; do
  111. # Terminal: the run said it is done. Stop cleanly instead of re-driving a finished run forever.
  112. run_done && finish "run finished ($RUNS_REL/<slug>.done present); supervisor exiting"
  113. # A human interacting (copy-mode / scrollback / selection) -> never touch the session.
  114. if [ "$(tm display-message -p -t "$SESS" '#{pane_in_mode}' 2>/dev/null || echo 0)" = "1" ]; then
  115. dead=0; stall=0; genstall=0; sleep "$POLL"; continue
  116. fi
  117. pane="$(tm capture-pane -p -t "$SESS" 2>/dev/null || true)"
  118. pane_pid="$(tm display-message -p -t "$SESS" '#{pane_pid}' 2>/dev/null || true)"
  119. tree="$(proc_tree "$pane_pid" | sort -u | tr '\n' ' ')"
  120. # 1) auto-approve a permission prompt; ONLY when the prompt box is actually at the BOTTOM of the pane
  121. # (last few non-empty lines) AND shows both the question line and the "1. Yes" option. Matching the
  122. # full signature at the tail (not anywhere on screen) stops a rendered diff or quoted text from
  123. # triggering a stray "1<Enter>" into the running agent.
  124. tail_pane="$(printf '%s\n' "$pane" | grep -v '^[[:space:]]*$' | tail -8)"
  125. # (a) a normal permission prompt, or (b) the first-launch "trust this folder" dialog that a fresh
  126. # resume (after a death) hits; both are answered with option 1 ("Yes"). Handling the trust
  127. # dialog is REQUIRED so death-recovery on a fresh checkout isn't blocked forever at it.
  128. if { printf '%s' "$tail_pane" | grep -q 'Do you want to proceed' \
  129. || printf '%s' "$tail_pane" | grep -qiE 'trust (this|the) folder|created or one you trust'; } \
  130. && printf '%s' "$tail_pane" | grep -qE '(❯[[:space:]]*)?1\.[[:space:]]*Yes'; then
  131. tm send-keys -t "$SESS" 1; sleep 1; tm send-keys -t "$SESS" Enter; sleep 1
  132. say "approved a prompt (permission or trust-folder)"; continue
  133. fi
  134. # 2) agent gone from THIS session's tree -> resume from disk (after DEAD_STRIKES).
  135. # Screen-independent: match the live process by its cmdline in the pane's own tree, not the
  136. # footer text and not a global pgrep. Auto-compaction keeps the process alive, so it won't trip.
  137. agent_live=""
  138. for pid in $tree; do
  139. if tr '\0' ' ' < "/proc/$pid/cmdline" 2>/dev/null | grep -q 'claude'; then agent_live=1; break; fi
  140. done
  141. if [ -z "$agent_live" ]; then
  142. dead=$((dead+1)); say "agent absent from session tree (strike $dead/$DEAD_STRIKES)"
  143. if [ "$dead" -ge "$DEAD_STRIKES" ]; then
  144. restarts=$((restarts+1))
  145. if [ "$restarts" -gt "$MAX_RESTARTS" ]; then
  146. finish "GIVING UP: $MAX_RESTARTS consecutive restarts produced no new on-disk artifact; the run is \
  147. finished or stuck, and re-driving it would only churn. Inspect $RUNS and this log, then delete \
  148. $STOP and relaunch the supervisor to resume."
  149. fi
  150. say "RESUME (death): fresh claude + continue-from-disk (restart $restarts/$MAX_RESTARTS)"
  151. start_agent; send_prompt "$CONT"; dead=0; stall=0
  152. fi
  153. sleep "$POLL"; continue
  154. fi
  155. dead=0
  156. # 3) stall: no new artifact under the run dir and no heavy compute in this run's process tree.
  157. # Scoped to the run, so a neighbor's job on a shared machine cannot mask a stall and the run's
  158. # own long build or benchmark (CPU-bound, logging only at phase boundaries) does not look like
  159. # one. "Heavy compute" is any non-claude process in the tree above the CPU threshold.
  160. # Only real progress counts: the supervisor's own log, heartbeat files, and benchmark logs are
  161. # ignored, since a lead that re-runs the same benchmark or only emits heartbeats is not progressing.
  162. fresh_artifact="$(find "$RUNS" -type f -newermt "-2 min" \
  163. ! -name 'supervisor.*' ! -iname '*heartbeat*' ! -iname '*liveness*' ! -iname '*keepalive*' \
  164. ! -path '*/logs/*' ! -name '*.log' 2>/dev/null | head -1)"
  165. # Heavy compute: any process in the tree other than the agent itself above the CPU threshold. The
  166. # agent is excluded by its command line, not its comm (which is "node"), so a spinning agent is not
  167. # mistaken for compute.
  168. heavy_compute=""
  169. for pid in $tree; do
  170. case "$(tr '\0' ' ' < "/proc/$pid/cmdline" 2>/dev/null)" in *claude*) continue;; esac
  171. pc="$(LC_ALL=C ps -o pcpu= -p "$pid" 2>/dev/null | tr -d ' ')" # LC_ALL=C -> dot decimal (not "23,4")
  172. [ -n "$pc" ] || continue
  173. if [ "${pc%[.,]*}" -gt "$CPU_BUSY" ] 2>/dev/null; then heavy_compute="$pid:$pc"; break; fi
  174. done
  175. # Is the agent generating? Claude Code shows "esc to interrupt" in the footer only while a turn is
  176. # generating. A coding-agent subagent can generate for many minutes with no new artifact and almost no
  177. # local CPU, so generating counts as progress; only a very long generation with no artifact is cut.
  178. generating=""; printf '%s' "$pane" | grep -q 'esc to interrupt' && generating=1
  179. # Is a SUBAGENT actively running? The agent list shows a running teammate as "◯ <name> … <Xm Ys>" with
  180. # an elapsed timer. A delegated coding agent can run a long bench that is disk-I/O-bound at ~0% CPU (so
  181. # heavy_compute misses it) and leaves the footer NOT "generating"; without this it is false-nudged on
  182. # the idle path. An active subagent is progress; treat it like generating (bounded by the same ceiling).
  183. subagent_active=""; printf '%s' "$pane" | grep -qE '◯[[:space:]].+[0-9]+m[[:space:]]+[0-9]+s' && subagent_active=1
  184. # SATURATED = the lead's context is ~full ("100% context used"): a /compact can't create lasting headroom,
  185. # so for it, burning CPU on the same binary is NOT progress; only a real new code/decision-log artifact is.
  186. saturated=""; printf '%s' "$pane" | grep -qE '(100|9[0-9])% context used' && saturated=1
  187. # PER-CODING-AGENT TIME-BOX: the longest-running delegated sub-agent's elapsed minutes (from "◯ <name> … <Xm Ys>").
  188. # A single coding agent past CODING_AGENT_MAX_MIN with NO new code artifact is monopolizing the cycle -> treat like saturation.
  189. # Match the elapsed timer "<Xh >Ym Zs" on subagent lines (handles hour-plus + names containing digits), convert
  190. # to total minutes, take the max across subagents.
  191. sub_min="$(printf '%s' "$pane" | grep '◯' | grep -oE '([0-9]+h[[:space:]]+)?[0-9]+m[[:space:]]+[0-9]+s' \
  192. | awk '{h=0;m=0; for(i=1;i<=NF;i++){ if($i ~ /h$/) h=$i+0; else if($i ~ /m$/) m=$i+0 } print h*60+m }' \
  193. | sort -n | tail -1)"
  194. long_coding_agent=""; [ -n "$sub_min" ] && [ "$sub_min" -ge "$CODING_AGENT_MAX_MIN" ] 2>/dev/null && [ -z "$fresh_artifact" ] && long_coding_agent=1
  195. # RESET the churn only on REAL progress: a new source/decision-log/test artifact, OR local heavy compute when the lead
  196. # is NOT saturated AND no coding agent is over its time-box (a fresh coding agent legitimately builds/benches). A SATURATED
  197. # lead; or an over-time-box coding agent; burning CPU with no new artifact must NOT reset, else escalation never fires.
  198. if [ -n "$fresh_artifact" ] || { [ -n "$heavy_compute" ] && [ -z "$saturated" ] && [ -z "$long_coding_agent" ]; }; then
  199. stall=0; genstall=0; compacts=0
  200. [ -n "$fresh_artifact" ] && restarts=0 # a real artifact = the last restart worked; re-arm the budget
  201. elif [ -n "$generating" ] || [ -n "$subagent_active" ] || [ -n "$heavy_compute" ]; then
  202. genstall=$((genstall+1)); stall=0
  203. # A saturated lead, or a coding agent past its time-box, generating with no new code artifact gets the
  204. # shorter ceiling; repeated compacts without progress escalate to a fresh lead (see unchoke()).
  205. # A coding agent within its time-box legitimately generates for many minutes and gets the full ceiling.
  206. ceil="$GEN_STALL_STRIKES"; { [ -n "$saturated" ] || [ -n "$long_coding_agent" ]; } && ceil="$SAT_STALL_STRIKES"
  207. say "generating/benching, no new code artifact (gen $genstall/$ceil${saturated:+ · saturated}${long_coding_agent:+ · coding agent ${sub_min}m})"
  208. if [ "$genstall" -ge "$ceil" ]; then
  209. say "GEN-STALL (ceil=$ceil): compact; fresh lead if it keeps churning"
  210. unchoke; genstall=0; stall=0
  211. fi
  212. else
  213. # idle at the prompt, no artifact, no compute -> a genuine stall.
  214. stall=$((stall+1)); say "idle, no new artifact (strike $stall/$STALL_STRIKES)"
  215. if [ "$stall" -ge "$STALL_STRIKES" ]; then
  216. say "STALL: compact; fresh lead if it keeps churning"
  217. unchoke; stall=0; genstall=0
  218. fi
  219. fi
  220. sleep "$POLL"
  221. done

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.