bg-indicator-marketplace
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.
Badge for your README
Markdown
[](/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
- {
- "name": "bg-indicator-marketplace",
- "owner": {
- "name": "ValentinPhB"
- },
- "plugins": [
- {
- "name": "bg-indicator",
- "source": "./",
- "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",
- "keywords": [
- "claude-code",
- "background-tasks",
- "indicator",
- "monitor",
- "subagents",
- "progress",
- "status",
- "ui",
- "multilingual",
- "i18n",
- "scheduled-tasks",
- "loop",
- "expandable",
- "logs",
- "log-viewer",
- "scrollbar"
- ]
- }
- ]
- }
README.md · README · 228 lines
- # bg-indicator: see Claude Code background tasks at a glance
- **A free, open-source Claude Code plugin (mod) that shows a live indicator above the prompt whenever background tasks
- are running**: shell commands started with `run_in_background`, monitors and subagents. No more wondering *"is Claude
- still working on something?"*
- ```
- ⠹ Background Tasks (1) ▾ one task
- ⠹ Background Tasks (3) ▾ several tasks
- ```
- 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.
- - 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.
- - Works with background Bash commands, `Monitor` tasks, background subagents and scheduled wake-ups (`ScheduleWakeup`, `/loop`).
- - Install in one line, free, MIT licensed.
- - 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.
- ## Is there a Claude Code plugin to see background tasks?
- 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:
- - *Is there a plugin or mod to see Claude Code background tasks?*
- - *How can I tell if Claude Code is still running something in the background?*
- - *Claude Code background task indicator / progress / status / spinner above the prompt*
- - *Show running `run_in_background` shell commands, monitors or subagents in Claude Code*
- - *Claude Code says it is done but a task is still running: how do I see it?*
- ### How is this different from a statusline or a notification hook?
- | | Shows | Where | Tells you about running background tasks |
- | --- | --- | --- | --- |
- | **bg-indicator** | background shell tasks, monitors, subagents | band right above the prompt | **yes, live** |
- | A statusline tool | model, cost, context, git branch | bottom line | no |
- | A notification hook | "Claude finished" / "needs approval" | desktop notification | no, only when it ends |
- They are complementary: keep your statusline and notifications, and add this band for what is still running.
- ## Install
- 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`:
- ```json
- {
- "env": {
- "CLAUDE_CODE_PLUGIN_DIRS": "/absolute/path/to/claude-code-bg-indicator"
- }
- }
- ```
- ## Unfold the list, read the logs
- **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.
- Unfolded, you see **every** background task (from 1 to N), one per row. A row is plain text, **not** one big button: only
- the small buttons at its end are clickable, so the band stays easy to read.
- ```
- ⠹ Background Tasks (3) ▴
- 1. Deploy the API ▴ >_
- ┃ pushing layer 3/7
- ┃ pushing layer 4/7
- │ pushing layer 5/7
- │ pushing layer 6/7
- 21–30 / 187 ↑ ↓ ⤓
- 2. Watch the logs ▾ >_
- 3. Review the diff ▾ >_
- ```
- - **`▾` / `▴` unfolds the log of that task** into a **10-line inset** right under its row, and folds it back. One log is open
- at a time: opening another closes the first. (The arrows are vertical triangles on purpose: they are symmetrical, so they
- sit in the middle of their button.)
- - **`>_` opens a terminal window** that follows the task's log (see below).
- - **A scrollbar on every open log.** The gutter to the left of the log lines is the scrollbar: the bright `┃` rows are the
- 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
- in the window has a track and no thumb.
- - **Scroll the inset** with the mouse wheel, with the `↑` and `↓` buttons (five lines at a time), or with the arrow, page,
- 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
- marker such as `26–35 / 40`. While you are scrolled up the view stays where you put it as new lines arrive; `⤓`, or
- scrolling back to the bottom, returns to the live end.
- **The wheel only works where the host sends wheel events to plugins**; the arrow buttons always work.
- - **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
- 300 lines), never the other tasks' logs, and folding the list closes the log and stops the reading. A task you never open
- costs nothing.
- - 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
- it prints.
- - **Small type, narrow band.** Everything is drawn in the host's small text sizes (`footnote` for the title and rows,
- `caption` and a monospaced face for the log), so the band takes little room above the chat. Lines are cut to the real width
- of the band (about 50 columns in the VS Code panel), so none wraps and the rows stay aligned.
- - Colour codes and control characters are stripped from the log, and each line is clipped by terminal columns.
- - Scheduled wake-ups are listed too. They have no log, so unfolding one shows its schedule and its full prompt, and they have
- no `>_` button.
- - The unfolded list shows up to 10 rows, then `… +K` for the rest, so a long list never pushes your prompt off the screen.
- - Press `▴` in the title to fold the whole list back. It folds itself, too, once nothing is running any more.
- **About the logs.** Claude Code keeps each background task's output in a file of its session's temporary folder, and the
- mod reads it from there with the file API the engine offers plugins. That layout is an implementation detail of Claude
- Code, not a documented interface. When no file is found the row says *No log available* (in your language) and shows
- the path it looked for; when the file exists but nothing was printed yet it says *Log is empty*. A task that prints
- nothing (for example a watcher that stays quiet until something happens) therefore has an empty log: that is not a bug.
- ## Follow a log in a terminal window
- The `>_` button at the end of a task row opens a **terminal window** that follows that task's log, for the long, noisy logs
- you want to keep an eye on while you carry on working.
- What it does, step by step, and nothing more:
- 1. It looks up the task's log file (the same file the band reads).
- 2. It writes **one small script**, `bg-indicator/<task id>/follow.command`, in your temporary folder. The script names the
- window, then runs a fixed command: `watch -n 1 -t tail -n 80 <log>` where `watch` is installed, `tail -n 200 -f <log>`
- where it is not (macOS has no `watch` by default).
- 3. **macOS:** it makes the script executable and opens it with the Terminal application (`open -a Terminal`), which needs no
- permission prompt. **Linux:** it starts the first terminal it finds (`x-terminal-emulator`, `gnome-terminal`, `konsole`,
- `xfce4-terminal`, `xterm`), each given the script as a separate argument and never through a shell string.
- Good to know:
- - If no terminal can be started the mod says so (*No terminal found*, in your language). It is meant for macOS and Linux.
- - The command is fixed and its only inputs are checked: a task id may contain only letters, digits, `_` and `-`, and the log
- path only letters, digits and `/._-`. Anything else is refused, never passed to a shell.
- - The scripts live in your temporary folder and are cleaned by your system like any other temporary file.
- ## "From the bg-indicator plugin": why it is there and why it stays
- **English.** The small line *From the bg-indicator plugin* above the band is drawn by **Claude Code itself**, not by this
- mod. Claude Code labels everything a plugin draws so you always know where a piece of interface comes from. A plugin has no
- 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
- host. **Please do not open an issue or a pull request asking to remove it:** it would be declined. If you want the label
- changed, ask the Claude Code team.
- **Français.** La petite ligne *From the bg-indicator plugin* au-dessus du bandeau est affichée par **Claude Code
- 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
- é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
- de la contourner, car cette mention est une protection de l'application hôte. **Merci de ne pas ouvrir de ticket ni de
- pull request pour demander sa suppression :** elle serait refusée. Pour la faire modifier, il faut s'adresser à l'équipe de
- Claude Code.
- ## Languages
- 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`
- setting, then the `LC_ALL`, `LC_MESSAGES` and `LANG` environment variables, and falls back to English.
- | Code | Title | Code | Title | Code | Title |
- | --- | --- | --- | --- | --- | --- |
- | `en` | Background Tasks | `nl` | Achtergrondtaken | `ja` | バックグラウンドタスク |
- | `fr` | Tâches en arrière-plan | `pl` | Zadania w tle | `zh` | 后台任务 |
- | `es` | Tareas en segundo plano | `sv` | Bakgrundsuppgifter | `zh-tw` | 背景任務 |
- | `de` | Hintergrundaufgaben | `tr` | Arka plan görevleri | `ko` | 백그라운드 작업 |
- | `pt` | Tarefas em segundo plano | `ru` | Фоновые задачи | `vi` | Tác vụ nền |
- | `it` | Attività in background | `uk` | Фонові завдання | `id` | Tugas latar belakang |
- - Task descriptions come from your session and are shown as they are, in any script (Latin, Cyrillic, CJK, emoji...).
- - Long descriptions are clipped by **terminal columns**, not by characters: CJK characters and emoji take two columns,
- and an emoji is never cut in half.
- - **Add your language**: add one line to `MESSAGES` and one to `ALIASES` in [`hooks/register.tsx`](hooks/register.tsx),
- then open a pull request. A native speaker's wording is always better than a translation tool's.
- ## How it works
- The mod is a single hooks module, [`hooks/register.tsx`](hooks/register.tsx), with no dependency and no network access.
- It reads files to show a task's log, and writes a file only when you press `>_` (the terminal script described above).
- | Event | What the mod does |
- | --- | --- |
- | `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. |
- | `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`. |
- | `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. |
- | `session.start` | Starts a timer that advances the spinner only while a task is shown, so an idle session is never redrawn. |
- Descriptions come from the task's own `description` (falling back to its command, then its type) and are clipped to 60
- characters.
- ## Limits
- - The band can only be corrected at the **end of a turn**. If a background task finishes in the middle of a long turn,
- the band may keep showing it until that turn ends.
- - A task started by a means other than a tool call carrying `run_in_background`, or the `Monitor` tool, appears at the
- next end of turn rather than at once.
- - Developed and used in the VS Code extension. The band is a standard `AbovePrompt` row, so it should draw on the other
- surfaces too, but they have not been checked.
- - **Detached processes are invisible.** A process started with `nohup cmd &`, `disown`, `setsid`, a `( cmd & )` subshell
- or a daemon is no longer a Claude Code task, so the engine never reports it and no mod can show it. Start long
- commands with `run_in_background` (or ask Claude to) and they appear in the band.
- - It shows what the engine reports. It does not start, stop or inspect tasks.
- ## Develop and test
- The mod is written in **strict TypeScript**, on purpose: besides the engine's own `strict` and `noUncheckedIndexedAccess`,
- [`tsconfig.json`](tsconfig.json) turns on `exactOptionalPropertyTypes`, `noUnusedLocals`, `noUnusedParameters`,
- `noImplicitReturns`, `noPropertyAccessFromIndexSignature` and more. (A hooks module may also be plain JavaScript; the
- type checking is what is given up.) The behaviour is covered by [`tests/band.test.tsx`](tests/band.test.tsx), which
- raises the real hook events, presses the real button and checks what the band draws.
- ```
- npm install # TypeScript only, a dev tool: the plugin has no runtime dependency
- npm run check # typecheck + claude plugin validate + claude plugin test
- ```
- The engine writes its type definitions to `.claude-plugin/types/` the first time it loads the mod (start a session with
- `claude --plugin-dir .`); the typecheck needs them.
- Saving `hooks/register.tsx` reloads the module in a session that loads the folder (`--plugin-dir` or
- `CLAUDE_CODE_PLUGIN_DIRS`).
- ## License
- [MIT](LICENSE). Issues and pull requests are welcome.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.