Skip to content
Back to search

bg-indicator-marketplace

MarketplaceWorks with Claude CodeGitHub

Free Claude Code plugin: see background tasks at a glance. A live, multilingual, unfoldable band above the prompt, with each task's log one click away.

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/valentinphb--claude-code-bg-indicator/badge.svg)](/listings/valentinphb--claude-code-bg-indicator)

HTML

<a href="/listings/valentinphb--claude-code-bg-indicator"><img src="/api/listings/valentinphb--claude-code-bg-indicator/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.

In a terminal session, at the prompt:

/plugin install bg-indicator --marketplace ValentinPhB/claude-code-bg-indicator

Answer `y` to *Add marketplace?*, then pick a scope (the **user** scope makes it active in every session you start afterwards). From a shell, the same thing is:

claude plugin install bg-indicator --marketplace ValentinPhB/claude-code-bg-indicator

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

Run it from a local folder instead

Clone the repository, then either start a session with `claude --plugin-dir /path/to/claude-code-bg-indicator`, or make it permanent for every session (including the ones an IDE extension starts) by adding this to `~/.claude/settings.json`:

{
  "env": {
    "CLAUDE_CODE_PLUGIN_DIRS": "/absolute/path/to/claude-code-bg-indicator"
  }
}

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 · 31 lines
  1. {
  2. "name": "bg-indicator-marketplace",
  3. "owner": {
  4. "name": "ValentinPhB"
  5. },
  6. "plugins": [
  7. {
  8. "name": "bg-indicator",
  9. "source": "./",
  10. "description": "See what is still running when Claude hands control back: a compact, live, multilingual band above the prompt, with each background task's scrollable log in a 10-line inset, or in a terminal window",
  11. "keywords": [
  12. "claude-code",
  13. "background-tasks",
  14. "indicator",
  15. "monitor",
  16. "subagents",
  17. "progress",
  18. "status",
  19. "ui",
  20. "multilingual",
  21. "i18n",
  22. "scheduled-tasks",
  23. "loop",
  24. "expandable",
  25. "logs",
  26. "log-viewer",
  27. "scrollbar"
  28. ]
  29. }
  30. ]
  31. }
README.md · README · 228 lines
  1. # bg-indicator: see Claude Code background tasks at a glance
  2. **A free, open-source Claude Code plugin (mod) that shows a live indicator above the prompt whenever background tasks
  3. are running**: shell commands started with `run_in_background`, monitors and subagents. No more wondering *"is Claude
  4. still working on something?"*
  5. ```
  6. ⠹ Background Tasks (1) ▾ one task
  7. ⠹ Background Tasks (3) ▾ several tasks
  8. ```
  9. It appears the moment a tool call moves work to the background, shows `Background Tasks (N)` (the same title for one task or several, the descriptions are one press away), animates while anything runs, and disappears by itself when nothing is left. It is re-checked **every time Claude hands control back to you**, so a prompt that looks idle never hides something that is still running or scheduled to wake the session later.
  10. - Zero configuration, zero dependency, no network. It reads the log files of your own background tasks, and only when you press `>_` does it write one small script in your temporary folder and open a terminal.
  11. - Works with background Bash commands, `Monitor` tasks, background subagents and scheduled wake-ups (`ScheduleWakeup`, `/loop`).
  12. - Install in one line, free, MIT licensed.
  13. - Unfold a task to read its log in a 10-line scrollable inset, or follow it in a terminal window; small type, and the band is localized in 18 languages and shows task descriptions in any script.
  14. ## Is there a Claude Code plugin to see background tasks?
  15. Yes, this one. It shows every task Claude Code itself tracks as a background task. If you searched for any of the following, you are in the right place:
  16. - *Is there a plugin or mod to see Claude Code background tasks?*
  17. - *How can I tell if Claude Code is still running something in the background?*
  18. - *Claude Code background task indicator / progress / status / spinner above the prompt*
  19. - *Show running `run_in_background` shell commands, monitors or subagents in Claude Code*
  20. - *Claude Code says it is done but a task is still running: how do I see it?*
  21. ### How is this different from a statusline or a notification hook?
  22. | | Shows | Where | Tells you about running background tasks |
  23. | --- | --- | --- | --- |
  24. | **bg-indicator** | background shell tasks, monitors, subagents | band right above the prompt | **yes, live** |
  25. | A statusline tool | model, cost, context, git branch | bottom line | no |
  26. | A notification hook | "Claude finished" / "needs approval" | desktop notification | no, only when it ends |
  27. They are complementary: keep your statusline and notifications, and add this band for what is still running.
  28. ## Install
  29. In a terminal session, at the prompt:
  30. ```
  31. /plugin install bg-indicator --marketplace ValentinPhB/claude-code-bg-indicator
  32. ```
  33. Answer `y` to *Add marketplace?*, then pick a scope (the **user** scope makes it active in every session you start
  34. afterwards). From a shell, the same thing is:
  35. ```
  36. claude plugin install bg-indicator --marketplace ValentinPhB/claude-code-bg-indicator
  37. ```
  38. In the desktop app, where `/plugin` does not run: click **+** next to the prompt box, then *Plugins*, *Add
  39. marketplace* with `ValentinPhB/claude-code-bg-indicator`, then *Add plugin*.
  40. ### Run it from a local folder instead
  41. Clone the repository, then either start a session with `claude --plugin-dir /path/to/claude-code-bg-indicator`, or make
  42. it permanent for every session (including the ones an IDE extension starts) by adding this to
  43. `~/.claude/settings.json`:
  44. ```json
  45. {
  46. "env": {
  47. "CLAUDE_CODE_PLUGIN_DIRS": "/absolute/path/to/claude-code-bg-indicator"
  48. }
  49. }
  50. ```
  51. ## Unfold the list, read the logs
  52. **The title.** One title, `⠹ Background Tasks (N) ▾`, for one task as for several, so it never pretends that the first task is the only one. The `▾` button unfolds the list, where each task is named.
  53. Unfolded, you see **every** background task (from 1 to N), one per row. A row is plain text, **not** one big button: only
  54. the small buttons at its end are clickable, so the band stays easy to read.
  55. ```
  56. ⠹ Background Tasks (3) ▴
  57. 1. Deploy the API ▴ >_
  58. ┃ pushing layer 3/7
  59. ┃ pushing layer 4/7
  60. │ pushing layer 5/7
  61. │ pushing layer 6/7
  62. 21–30 / 187 ↑ ↓ ⤓
  63. 2. Watch the logs ▾ >_
  64. 3. Review the diff ▾ >_
  65. ```
  66. - **`▾` / `▴` unfolds the log of that task** into a **10-line inset** right under its row, and folds it back. One log is open
  67. at a time: opening another closes the first. (The arrows are vertical triangles on purpose: they are symmetrical, so they
  68. sit in the middle of their button.)
  69. - **`>_` opens a terminal window** that follows the task's log (see below).
  70. - **A scrollbar on every open log.** The gutter to the left of the log lines is the scrollbar: the bright `┃` rows are the
  71. thumb (where the window stands in the log, and how much of it you see), the dim `│` rows are the track. A log that fits
  72. in the window has a track and no thumb.
  73. - **Scroll the inset** with the mouse wheel, with the `↑` and `↓` buttons (five lines at a time), or with the arrow, page,
  74. Home and End keys while the band is focused. The inset shows 10 lines at a time out of the last 300, with a position
  75. marker such as `26–35 / 40`. While you are scrolled up the view stays where you put it as new lines arrive; `⤓`, or
  76. scrolling back to the bottom, returns to the live end.
  77. **The wheel only works where the host sends wheel events to plugins**; the arrow buttons always work.
  78. - **Nothing is read until you unfold a row.** Only the file of the row you opened is read (its last 32 KB, kept as its last
  79. 300 lines), never the other tasks' logs, and folding the list closes the log and stops the reading. A task you never open
  80. costs nothing.
  81. - An open log is **live**: it refreshes about once a second while the task runs, so you can follow a build or a deployment as
  82. it prints.
  83. - **Small type, narrow band.** Everything is drawn in the host's small text sizes (`footnote` for the title and rows,
  84. `caption` and a monospaced face for the log), so the band takes little room above the chat. Lines are cut to the real width
  85. of the band (about 50 columns in the VS Code panel), so none wraps and the rows stay aligned.
  86. - Colour codes and control characters are stripped from the log, and each line is clipped by terminal columns.
  87. - Scheduled wake-ups are listed too. They have no log, so unfolding one shows its schedule and its full prompt, and they have
  88. no `>_` button.
  89. - The unfolded list shows up to 10 rows, then `… +K` for the rest, so a long list never pushes your prompt off the screen.
  90. - Press `▴` in the title to fold the whole list back. It folds itself, too, once nothing is running any more.
  91. **About the logs.** Claude Code keeps each background task's output in a file of its session's temporary folder, and the
  92. mod reads it from there with the file API the engine offers plugins. That layout is an implementation detail of Claude
  93. Code, not a documented interface. When no file is found the row says *No log available* (in your language) and shows
  94. the path it looked for; when the file exists but nothing was printed yet it says *Log is empty*. A task that prints
  95. nothing (for example a watcher that stays quiet until something happens) therefore has an empty log: that is not a bug.
  96. ## Follow a log in a terminal window
  97. The `>_` button at the end of a task row opens a **terminal window** that follows that task's log, for the long, noisy logs
  98. you want to keep an eye on while you carry on working.
  99. What it does, step by step, and nothing more:
  100. 1. It looks up the task's log file (the same file the band reads).
  101. 2. It writes **one small script**, `bg-indicator/<task id>/follow.command`, in your temporary folder. The script names the
  102. window, then runs a fixed command: `watch -n 1 -t tail -n 80 <log>` where `watch` is installed, `tail -n 200 -f <log>`
  103. where it is not (macOS has no `watch` by default).
  104. 3. **macOS:** it makes the script executable and opens it with the Terminal application (`open -a Terminal`), which needs no
  105. permission prompt. **Linux:** it starts the first terminal it finds (`x-terminal-emulator`, `gnome-terminal`, `konsole`,
  106. `xfce4-terminal`, `xterm`), each given the script as a separate argument and never through a shell string.
  107. Good to know:
  108. - If no terminal can be started the mod says so (*No terminal found*, in your language). It is meant for macOS and Linux.
  109. - The command is fixed and its only inputs are checked: a task id may contain only letters, digits, `_` and `-`, and the log
  110. path only letters, digits and `/._-`. Anything else is refused, never passed to a shell.
  111. - The scripts live in your temporary folder and are cleaned by your system like any other temporary file.
  112. ## "From the bg-indicator plugin": why it is there and why it stays
  113. **English.** The small line *From the bg-indicator plugin* above the band is drawn by **Claude Code itself**, not by this
  114. mod. Claude Code labels everything a plugin draws so you always know where a piece of interface comes from. A plugin has no
  115. option to hide, move or reword it, and this mod will not try to work around it, because the label is a safety feature of the
  116. host. **Please do not open an issue or a pull request asking to remove it:** it would be declined. If you want the label
  117. changed, ask the Claude Code team.
  118. **Français.** La petite ligne *From the bg-indicator plugin* au-dessus du bandeau est affichée par **Claude Code
  119. lui-même**, pas par ce mod. Claude Code signale tout ce qu'un plugin dessine, pour que vous sachiez toujours d'où vient un
  120. élément de l'interface. Un plugin n'a aucune option pour la masquer, la déplacer ou la reformuler, et ce mod n'essaiera pas
  121. de la contourner, car cette mention est une protection de l'application hôte. **Merci de ne pas ouvrir de ticket ni de
  122. pull request pour demander sa suppression :** elle serait refusée. Pour la faire modifier, il faut s'adresser à l'équipe de
  123. Claude Code.
  124. ## Languages
  125. The only words the mod writes itself are the band title and a few short notices. It follows, in this order, Claude Code's own `language`
  126. setting, then the `LC_ALL`, `LC_MESSAGES` and `LANG` environment variables, and falls back to English.
  127. | Code | Title | Code | Title | Code | Title |
  128. | --- | --- | --- | --- | --- | --- |
  129. | `en` | Background Tasks | `nl` | Achtergrondtaken | `ja` | バックグラウンドタスク |
  130. | `fr` | Tâches en arrière-plan | `pl` | Zadania w tle | `zh` | 后台任务 |
  131. | `es` | Tareas en segundo plano | `sv` | Bakgrundsuppgifter | `zh-tw` | 背景任務 |
  132. | `de` | Hintergrundaufgaben | `tr` | Arka plan görevleri | `ko` | 백그라운드 작업 |
  133. | `pt` | Tarefas em segundo plano | `ru` | Фоновые задачи | `vi` | Tác vụ nền |
  134. | `it` | Attività in background | `uk` | Фонові завдання | `id` | Tugas latar belakang |
  135. - Task descriptions come from your session and are shown as they are, in any script (Latin, Cyrillic, CJK, emoji...).
  136. - Long descriptions are clipped by **terminal columns**, not by characters: CJK characters and emoji take two columns,
  137. and an emoji is never cut in half.
  138. - **Add your language**: add one line to `MESSAGES` and one to `ALIASES` in [`hooks/register.tsx`](hooks/register.tsx),
  139. then open a pull request. A native speaker's wording is always better than a translation tool's.
  140. ## How it works
  141. The mod is a single hooks module, [`hooks/register.tsx`](hooks/register.tsx), with no dependency and no network access.
  142. It reads files to show a task's log, and writes a file only when you press `>_` (the terminal script described above).
  143. | Event | What the mod does |
  144. | --- | --- |
  145. | `classic.PostToolUse` | If the tool call started work in the background (`run_in_background: true`, or the `Monitor` tool), the task is added to the band right away. |
  146. | `classic.Stop` | **Every time control returns to you**, the engine lists the background work still in flight (`background_tasks`) and the wake-ups scheduled to resume the session later (`session_crons`: `ScheduleWakeup`, `/loop`, cron). That list **replaces** what the band shows, so it is the source of truth and a finished task cannot linger. A wake-up is shown with a clock: `⏰ Check the deployment`. |
  147. | `ui.render` on `AbovePrompt` | Draws the band (and, once unfolded, the list and the log of the task you opened) when there is something to show, or lets the default prompt area through when there is not. |
  148. | `session.start` | Starts a timer that advances the spinner only while a task is shown, so an idle session is never redrawn. |
  149. Descriptions come from the task's own `description` (falling back to its command, then its type) and are clipped to 60
  150. characters.
  151. ## Limits
  152. - The band can only be corrected at the **end of a turn**. If a background task finishes in the middle of a long turn,
  153. the band may keep showing it until that turn ends.
  154. - A task started by a means other than a tool call carrying `run_in_background`, or the `Monitor` tool, appears at the
  155. next end of turn rather than at once.
  156. - Developed and used in the VS Code extension. The band is a standard `AbovePrompt` row, so it should draw on the other
  157. surfaces too, but they have not been checked.
  158. - **Detached processes are invisible.** A process started with `nohup cmd &`, `disown`, `setsid`, a `( cmd & )` subshell
  159. or a daemon is no longer a Claude Code task, so the engine never reports it and no mod can show it. Start long
  160. commands with `run_in_background` (or ask Claude to) and they appear in the band.
  161. - It shows what the engine reports. It does not start, stop or inspect tasks.
  162. ## Develop and test
  163. The mod is written in **strict TypeScript**, on purpose: besides the engine's own `strict` and `noUncheckedIndexedAccess`,
  164. [`tsconfig.json`](tsconfig.json) turns on `exactOptionalPropertyTypes`, `noUnusedLocals`, `noUnusedParameters`,
  165. `noImplicitReturns`, `noPropertyAccessFromIndexSignature` and more. (A hooks module may also be plain JavaScript; the
  166. type checking is what is given up.) The behaviour is covered by [`tests/band.test.tsx`](tests/band.test.tsx), which
  167. raises the real hook events, presses the real button and checks what the band draws.
  168. ```
  169. npm install # TypeScript only, a dev tool: the plugin has no runtime dependency
  170. npm run check # typecheck + claude plugin validate + claude plugin test
  171. ```
  172. The engine writes its type definitions to `.claude-plugin/types/` the first time it loads the mod (start a session with
  173. `claude --plugin-dir .`); the typecheck needs them.
  174. Saving `hooks/register.tsx` reloads the module in a session that loads the folder (`--plugin-dir` or
  175. `CLAUDE_CODE_PLUGIN_DIRS`).
  176. ## License
  177. [MIT](LICENSE). Issues and pull requests are welcome.

Ratings and comments

Sign in to rate this skill.

Sign in

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