Skip to content
Back to search

claude-code-ci-watch

MarketplaceWorks with Claude CodeGitHub

CI Watch: live test and CI progress for Claude Code, with a stall watchdog that wakes the agent.

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/mateuszsury--claude-code-ci-watch/badge.svg)](/listings/mateuszsury--claude-code-ci-watch)

HTML

<a href="/listings/mateuszsury--claude-code-ci-watch"><img src="/api/listings/mateuszsury--claude-code-ci-watch/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.

CI Watch needs a Claude Code build with mods (function hooks): 2.1.326 or newer. The mod API is early access and may change between releases.

At the prompt of a Claude Code terminal session:

/plugin install ci-watch --marketplace mateuszsury/claude-code-ci-watch

Answer `y` to add the marketplace, then pick the **user** scope so it loads in every session.

From a shell:

claude plugin install ci-watch --marketplace mateuszsury/claude-code-ci-watch

In the Claude desktop app, where `/plugin` does not run: click **+** next to the prompt box, then **Plugins**, **Add marketplace** with `mateuszsury/claude-code-ci-watch`, then **Add plugin**.

For GitHub Actions and PR checks, the [GitHub CLI](https://cli.github.com/) (`gh`) must be installed and signed in. The mod calls only `gh run list`, `gh run view`, `gh pr checks` and `gh pr view`; it never reruns, cancels or changes anything.

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 · 21 lines
  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "claude-code-ci-watch",
  4. "description": "CI Watch: live test and CI progress for Claude Code, with a stall watchdog that wakes the agent.",
  5. "owner": {
  6. "name": "Mateusz Sury",
  7. "url": "https://github.com/mateuszsury"
  8. },
  9. "plugins": [
  10. {
  11. "name": "ci-watch",
  12. "displayName": "CI Watch",
  13. "description": "Live panel of test and CI progress beside the chat (24/245 · test_name), with a stall watchdog that wakes the agent when tests or GitHub Actions hang or finish.",
  14. "source": "./",
  15. "category": "development",
  16. "keywords": ["ci", "tests", "github-actions", "docker", "watchdog"],
  17. "version": "0.2.0",
  18. "author": { "name": "Mateusz Sury" }
  19. }
  20. ]
  21. }
README.md · README · 191 lines
  1. # CI Watch for Claude Code
  2. [![CI](https://github.com/mateuszsury/claude-code-ci-watch/actions/workflows/ci.yml/badge.svg)](https://github.com/mateuszsury/claude-code-ci-watch/actions/workflows/ci.yml)
  3. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  4. **Live progress of tests, builds, deploys, GitHub Actions and PR checks beside the chat, and a watchdog that wakes the agent when one of them hangs.**
  5. Claude Code often starts a test suite, builds an image or pushes to CI and then just waits. When the run hangs, a container stops printing or a GitHub job sits in the queue, nothing tells the agent, and the session quietly stalls. CI Watch is a Claude Code mod that:
  6. - shows every long run of the session in a pane, live: `24/245 · 10% · tests/test_api.py::test_login`, a progress bar, ✓/✗/○ counts, ETA, the last failures;
  7. - finds the GitHub Actions runs your `git push`, `gh pr merge` or `gh workflow run` started, and the checks of a PR, and follows them job by job;
  8. - watches for silence and wakes the agent with a concrete message when a run stalls, and when CI finishes;
  9. - gives the agent a `status` tool, so it checks progress instead of sleeping or re-reading log files.
  10. ```
  11. ╭──────────────────────────────────────────────╮
  12. │ ● Running · pytest 02:14 │
  13. │ pytest -v tests/ │
  14. │ tests/test_api.py::test_login ███░░ 24/245 · 10% │
  15. │ ✓ 22 ✗ 2 ○ 0 ETA 3:40 │
  16. │ ▸ tests/test_api.py::test_login │
  17. │ ✗ tests/test_api.py::test_refund │
  18. │ [ Notify agent ] [ Stop tracking ] │
  19. ╰──────────────────────────────────────────────╯
  20. ╭──────────────────────────────────────────────╮
  21. │ ● Running · build 01:02 │
  22. │ docker build -t web:1 . │
  23. │ RUN npm ci ██████░░░░ 4/7 · 57% │
  24. ╰──────────────────────────────────────────────╯
  25. ╭──────────────────────────────────────────────╮
  26. │ ✗ Failed · GitHub Actions 06:02 │
  27. │ CI · fix login redirect │
  28. │ ✓ lint 4/4 │
  29. │ ✗ e2e › Run playwright 6/6 │
  30. │ Open on GitHub [ Remove ] │
  31. ╰──────────────────────────────────────────────╯
  32. ```
  33. When the pane is minimized it shows one line (`● 24/245 · 10% ✗ 2` and the current test), and the status line shows `🧪 24/245 · 10% · test_name` (🔨 for a build, 🚀 for a deploy, ⚙ for CI).
  34. ## Install
  35. CI Watch needs a Claude Code build with mods (function hooks): 2.1.326 or newer. The mod API is early access and may change between releases.
  36. At the prompt of a Claude Code terminal session:
  37. ```
  38. /plugin install ci-watch --marketplace mateuszsury/claude-code-ci-watch
  39. ```
  40. Answer `y` to add the marketplace, then pick the **user** scope so it loads in every session.
  41. From a shell:
  42. ```
  43. claude plugin install ci-watch --marketplace mateuszsury/claude-code-ci-watch
  44. ```
  45. In the Claude desktop app, where `/plugin` does not run: click **+** next to the prompt box, then **Plugins**, **Add marketplace** with `mateuszsury/claude-code-ci-watch`, then **Add plugin**.
  46. For GitHub Actions and PR checks, the [GitHub CLI](https://cli.github.com/) (`gh`) must be installed and signed in. The mod calls only `gh run list`, `gh run view`, `gh pr checks` and `gh pr view`; it never reruns, cancels or changes anything.
  47. ## One session at a time
  48. Installed at the user scope, the mod is on in every session, but each session sees only its own runs. Runs live in the session's own state, the hooks run in that session's process, and the watchdog wakes only that session's agent. Nothing is written to cross-session storage, so two sessions running tests side by side never mix their panels or wake each other.
  49. ## What it tracks
  50. ### Commands the agent runs
  51. Every Bash or PowerShell command is read the way a shell reads it: quotes, `$(…)`, line continuations, heredocs, `&&`/`;`/`|` chains. Wrappers are looked through (`bash -c`, `ssh host …`, `powershell -File`, `cmd /c`, `uv run`, `npx`, `docker run|exec`, `docker compose run|exec`), and only what actually runs decides. A runner named in a path, a commit message, an inline script (`node -e`, `python -c`), a heredoc body or a `--version` query never counts.
  52. | Category | Examples | Stall limit |
  53. | --- | --- | --- |
  54. | **Tests and checks** | pytest, jest, vitest, playwright test, mocha, `go test`, `cargo test/clippy/check`, `dotnet test`, gradle/mvn test, tsc, eslint, ruff, mypy, `npm run test/lint/typecheck`, `make test`, `act`, `docker compose up --abort-on-container-exit`, tests inside `docker run`/`compose run`, scripts named `ci`, `e2e`, `check`, `test`… | 5 min |
  55. | **Builds** | `docker build`, `docker buildx build`, `docker compose build`, `cargo build`, `go build`, `dotnet build/publish`, `npm run build`, `vite/next build`, gradle assemble, `cmake --build`, scripts named `build`… | 10 min |
  56. | **Deploys** | `docker push`, `docker save … \| ssh … docker load`, `kubectl apply/rollout`, `helm upgrade`, `terraform apply`, `pulumi up`, `fly/vercel/netlify/wrangler/firebase deploy`, `npm publish`, scripts and tools named `deploy`, `release`, `rollout` (also over `ssh`), but not their `status`/`logs` queries | 20 min |
  57. - A command run in the **background** is followed live: its output file is read every 2 s.
  58. - A command in the **foreground** gets a card only once it has run for 10 s, so quick checks never open the pane; it shows its result when it ends.
  59. - A command moved to the background after its timeout is followed live from then on.
  60. - `/ci <log path>` or the agent's `track` tool follows any other log file.
  61. ### GitHub Actions and PR checks
  62. | What happens | What CI Watch does |
  63. | --- | --- |
  64. | `git push` to a GitHub remote | reads the branch and the new commit from git's output, then looks for the runs of that commit a few times over the next 2 minutes (`gh run list --branch … `) and tracks each one |
  65. | `gh pr merge` | looks up the merge commit and tracks the runs it started (deploys on `main` usually start here) |
  66. | `gh workflow run <workflow>` | tracks the dispatched run |
  67. | `gh run watch|view|rerun <id>`, a run URL | tracks that run |
  68. | `gh pr checks [pr]` | tracks the PR's checks, from any CI provider that reports to GitHub |
  69. | `/ci <run id>`, `/ci pr [number]`, the `track` tool | tracks by hand |
  70. Runs are polled every 15 s (`gh run view --json`). The card lists the jobs with their current step and step counts, and links to the run. All the runs one push started are one group: the agent hears about them once, when the last one ends (`GitHub Actions for the push of 6fb617a finished: ❌ 1 of 3 failed`, with each job and the URLs).
  71. ### Output it understands
  72. | Runner | What it reads |
  73. | --- | --- |
  74. | pytest | `collected N items`, verbose `PASSED/FAILED/SKIPPED/ERROR` lines, quiet `..F.s [ 40%]` lines, xdist, the `FAILED` short summary, the final summary |
  75. | Playwright | `Running N tests`, list reporter (`✓ ✘ -`), line reporter (`[24/245]`), failure headers, final counts |
  76. | Vitest, Jest, Mocha | per-file and per-test lines, failure headers, final `Tests:` lines |
  77. | Go, Cargo, .NET | `--- PASS/FAIL`, `test x ... ok`, `Passed/Failed name [ms]` and per-assembly summaries |
  78. | tsc, eslint | each `error TS…` line, `✖ N problems (M errors…)` |
  79. | Builds | `[n/m]` step counters (docker build `#8 [builder 3/7] RUN …`, turbo), cargo `Compiling crate` and `Building [==>] n/m`, and any printed percentage (git `Receiving objects: 45%`, webpack, gradle, pip) |
  80. Docker, compose, `act` and GitHub Actions log prefixes (`tests-1 | `, `#7 0.322 `, `[CI/test] | `, timestamps) are stripped, so tests inside a container count exactly like local ones. When nothing is recognised, the card still shows the elapsed time, the silence and the last output line.
  81. ## The watchdog
  82. | Situation | Default | What happens |
  83. | --- | --- | --- |
  84. | Background tests print nothing | 5 min | the card turns amber (Stalled), a toast and a desktop notification, and the agent is told |
  85. | A background build prints nothing | 10 min | same |
  86. | A background deploy prints nothing | 20 min | same (image transfers are often quiet) |
  87. | A GitHub run or PR checks are queued | 10 min | same, "probably no runner is available or the workflow is blocked" |
  88. | A GitHub run's jobs and steps, or a PR's checks, stop changing | 20 min | same |
  89. | Tracked GitHub runs or PR checks finish | at once | the agent gets the verdict, the failed jobs and the URLs, once per push |
  90. How the agent is told depends on what it is doing:
  91. - **idle** (it ended its turn to wait): a new prompt starts a turn;
  92. - **stuck in a blocking wait** (`gh run watch`, `gh pr checks --watch`, `sleep`, a `while … sleep` loop): the wait is ended and the prompt follows;
  93. - **busy with other work**: a note is added that the agent reads with its next step.
  94. Each message starts with `[ci-watch]`, describes the run and asks the agent to find the cause and act instead of waiting again. One alert is sent per silence: new output resets it. The **Notify agent** button on a card sends the same description on demand.
  95. ## Options
  96. Set them in the config menu (`/config`, the **ci-watch** rows) or in `settings.json` under `pluginConfigs`:
  97. | Option | Default | |
  98. | --- | --- | --- |
  99. | `testStallMinutes` | 5 | silence before background tests count as stalled |
  100. | `buildStallMinutes` | 10 | the same for builds |
  101. | `deployStallMinutes` | 20 | the same for deploys |
  102. | `ciStallMinutes` | 20 | a GitHub run or PR checks with no change |
  103. | `queueStallMinutes` | 10 | a GitHub run or PR checks still queued |
  104. | `autoTrackGitHub` | true | find and track the runs after `git push`, `gh pr merge`, `gh workflow run` |
  105. | `wakeOnCiFinish` | true | tell the agent when tracked GitHub runs and PR checks end |
  106. The agent can also pass `stall_minutes` to `track` for one run that is quiet by design.
  107. ## Commands and tools
  108. | | |
  109. | --- | --- |
  110. | `/ci` | open the pane |
  111. | `/ci <run id or run URL>` | track a GitHub Actions run |
  112. | `/ci pr [number or URL]` | track a PR's checks (the current branch's without a number) |
  113. | `/ci <path>` | track a log file |
  114. | `/ci clear` | remove finished runs |
  115. | `mcp__ci-watch__status` | the agent's view of every run in the session: progress, current test, failures, silence, jobs, checks |
  116. | `mcp__ci-watch__track` | `{ gh_run_id \| pr \| log_path, repo, label, stall_minutes, notify_on_finish }` |
  117. The plugin also ships a `ci-watch` skill that tells the agent how to run tests so the pane can read them (background, unbuffered, one line per test), how to wait (the status tool, not `sleep`) and what to do with a `[ci-watch]` message. If your project's instructions forbid polling CI in a repository, the skill tells the agent to respect that; set `autoTrackGitHub` to false to stop the mod from looking up runs by itself.
  118. ## How it works
  119. The mod is a hooks module (`hooks/register.tsx`) loaded by Claude Code:
  120. - a `tool.call` hook sees each Bash/PowerShell command and classifies it (`hooks/parse.ts`); for a run in the background it reads the output file path from the tool result;
  121. - a timer reads new bytes of each output file every 2 s and feeds them to the parser, which keeps a running tally;
  122. - a `session.append` hook catches the `<task-notification>` that ends a background command and records the exit code; failures in the output win over a swallowed exit code (`pytest || true`);
  123. - after `git push`, `gh pr merge` and `gh workflow run` it looks up the runs they started; runs and PR checks are polled with `gh … --json` and mapped to cards (`hooks/github.ts`);
  124. - `turn.start` and `turn.complete` hooks track whether the agent is idle, which decides how a message is delivered;
  125. - a `ui.render` hook draws the pane on every surface (terminal, desktop, VS Code, mobile).
  126. ## Development
  127. ```
  128. claude plugin validate .
  129. claude plugin test .
  130. ```
  131. The tests cover the command classifier on commands taken from real sessions (including the false positives earlier versions had), the output parsers on real runner output (including docker compose and buildkit), the mapping of real `gh` JSON, the pane on all four surfaces, and the watchdog and GitHub flows with a mocked clock and a fake `gh`: a run that goes quiet wakes the idle agent exactly once, the workflows of one push are reported together, a quick foreground check gets no card. CI runs the same two commands on every push.
  132. To work on a copy in a session, load the folder with `claude --plugin-dir <folder>`.
  133. ## Limitations
  134. - Foreground commands show their result only when they end; run long suites in the background.
  135. - Buffered output looks like silence. Use unbuffered flags (`PYTHONUNBUFFERED=1`, `--reporter=line`), or raise the stall limit.
  136. - Test-level progress inside a running GitHub job is not available from the API; jobs, steps and checks are.
  137. - Runs are found after a push only for GitHub remotes, and only while `gh` can see the repository.
  138. - The mod API is early access; a future Claude Code release may need an update of this plugin.
  139. ## License
  140. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

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