Skip to content
Back to search

teardown-ledger

MarketplaceWorks with Claude CodeGitHub

teardown-ledger: what a Claude Code session spawned and has not yet shown to be gone

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/zexion7873--teardown-ledger/badge.svg)](/listings/zexion7873--teardown-ledger)

HTML

<a href="/listings/zexion7873--teardown-ledger"><img src="/api/listings/zexion7873--teardown-ledger/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.

Requirements are below. At the prompt of a terminal session:

/plugin install teardown-ledger --marketplace zexion7873/teardown-ledger

From a shell:

claude plugin install teardown-ledger --marketplace zexion7873/teardown-ledger

In the desktop app, where `/plugin` does not run: click + next to the prompt box, then Plugins, Add marketplace with `zexion7873/teardown-ledger`, then Add plugin.

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 · 12 lines
  1. {
  2. "name": "teardown-ledger",
  3. "owner": { "name": "Kevin Lin" },
  4. "description": "teardown-ledger: what a Claude Code session spawned and has not yet shown to be gone",
  5. "plugins": [
  6. {
  7. "name": "teardown-ledger",
  8. "source": "./plugin",
  9. "description": "Keeps the processes, ports and temp folders a session spawned until their absence is shown: a count above the prompt and a pane"
  10. }
  11. ]
  12. }
README.md · README · 140 lines
  1. <div align="center">
  2. # 🧹 teardown-ledger
  3. [![CI: check](https://github.com/zexion7873/teardown-ledger/actions/workflows/check.yml/badge.svg)](https://github.com/zexion7873/teardown-ledger/actions/workflows/check.yml)
  4. <img src="docs/hero.svg" width="760" title="Drawn by hand from sample entries, not a screenshot." alt="A drawing of the mod, not a screenshot. On the left, a session has run three Bash commands: a dev server put in the background on port 5173, a tmux session named probe, and a temp folder made at /tmp/qa-run. Its reply says The page renders. Done. Under it, above the prompt box, a button reads Teardown 3. On the right, a pane titled Teardown ledger lists the same three things: each shows what it is and where it was made, the check that would settle it (lsof on the port, tmux has-session, ls on the folder), a Copy check button and a Dismiss button; the folder is marked 2d ago, and a Dismiss all button sits under the list.">
  5. **Keeps the processes, ports and temp folders a Claude Code session spawned
  6. until their absence is shown: a count above the prompt and a pane.**
  7. [![License: MIT](https://img.shields.io/github/license/zexion7873/teardown-ledger?style=flat)](LICENSE)
  8. [![Surface: desktop | terminal](https://img.shields.io/badge/surface-desktop%20%7C%20terminal-lightgrey?style=flat)](#what-it-reads-and-writes)
  9. [![Network: none](https://img.shields.io/badge/network-none-brightgreen?style=flat)](#what-it-reads-and-writes)
  10. No model calls. No network requests. No running, blocking or rewriting a
  11. command. One mod reading the Bash calls the session already made.
  12. </div>
  13. ---
  14. An agent that runs a dev server, opens a tmux session or makes a temp folder
  15. during a check is supposed to tear it down afterwards, and to show that it is
  16. gone rather than say that it killed it. teardown-ledger watches the Bash tool
  17. calls of a session and its subagents, records what they leave behind, and
  18. clears an entry only when a later command's own output shows its absence:
  19. - a count above the prompt while something is unsettled
  20. - a pane (`/teardown`) listing each unsettled thing, where it was made and the
  21. check that would settle it, with Dismiss per entry and a two-press Dismiss all
  22. There is one ledger for the machine: every session shows every unsettled
  23. entry, wherever it was made. A session catches up with another session's
  24. changes the next time it redraws.
  25. It never runs, blocks or rewrites a command, and it makes no model calls and no
  26. network requests.
  27. ## What is recorded
  28. | A command that | is kept as |
  29. | --- | --- |
  30. | puts a job in the background with `&`, unless it also `wait`s | a process, named by that job's text |
  31. | runs as a background task | a process, named by its first part that is not `cd`, `export`, `source` or `set` |
  32. | runs `tmux new-session -s NAME` | a tmux session |
  33. | runs `mkdir` on a literal path under `/tmp` or `/private/tmp` | a temp folder |
  34. | runs `mktemp -d` and prints the path it made | a temp folder |
  35. A process also keeps its pid when the command echoes `$!`, and its port when
  36. the text names one (`--port N`, `PORT=N`, `localhost:N`, `http.server N`).
  37. ## What settles an entry
  38. Only the output of a check:
  39. | Entry | Check | Settles when |
  40. | --- | --- | --- |
  41. | process | `pgrep -f PATTERN` | it prints no pid and PATTERN matches the entry's text |
  42. | process with a pid | `ps -p PID` | its header prints without that pid's row |
  43. | process with a port | `lsof -i :PORT` | it prints nothing |
  44. | tmux session | `tmux has-session -t NAME` | it prints `can't find session`, or that no server is running |
  45. | tmux session | `tmux ls` | it lists the sessions, or no server, without NAME |
  46. | temp folder | `ls PATH`, `stat PATH` | it prints `No such file or directory` for the folder or one above it |
  47. `kill`, `pkill`, `tmux kill-session` and `rm` settle nothing. `pgrep` and `lsof`
  48. print nothing either way, so they count only where they must have run and kept
  49. their output: not after `&&` or `||`, not piped, not redirected (`2>/dev/null`
  50. and `2>&1` aside), and not on a call that never reached the shell. An
  51. `|| echo gone` after one is fine; the check ran first.
  52. ## Install
  53. Requirements are below. At the prompt of a terminal session:
  54. ```
  55. /plugin install teardown-ledger --marketplace zexion7873/teardown-ledger
  56. ```
  57. From a shell:
  58. ```bash
  59. claude plugin install teardown-ledger --marketplace zexion7873/teardown-ledger
  60. ```
  61. In the desktop app, where `/plugin` does not run: click + next to the prompt
  62. box, then Plugins, Add marketplace with `zexion7873/teardown-ledger`, then Add
  63. plugin.
  64. ## Options
  65. - `row`: the name of another mod whose row above the prompt the count joins,
  66. so the two take one row. Empty, the default, gives the count a row of its
  67. own. While that mod is not loaded, the count is not drawn. From a shell it
  68. can be set at install: `--config row=<that mod's name>`.
  69. The count is drawn inside that mod's row. It sits beside that mod's own
  70. content when teardown-ledger is the outer of the two hooks, or when that mod
  71. lays out what it is handed in a row; a mod that stacks it shows the count on
  72. the line above its own.
  73. ## What it reads and writes
  74. | Hook | Reads | Changes |
  75. | --- | --- | --- |
  76. | `session.start` | nothing | registers `/teardown` |
  77. | `command.run` (`/teardown`) | whether the mod's pane is open and shown | opens the pane; one open behind another pane's tab is closed and opened again, which brings it forward |
  78. | `tool.call` (`Bash`) | the command and, once it has run, its output; the session's working directory | adds what the command left behind to the ledger and removes what its checks showed gone; the call and its result pass through as they were |
  79. | `ui.render` (`AbovePrompt`, `Pane`) | the ledger, at each draw | draws the count and the pane; the count opens the pane as `/teardown` does; **Dismiss** deletes an entry, **Dismiss all** deletes every entry after a second press, **Copy check** puts an entry's check on the clipboard |
  80. The ledger lives in Claude Code's per-plugin store on your machine, one list
  81. for every session. An entry holds the text it was recognised by, a pid or port
  82. when the command showed one, the working directory and the time. For a
  83. background job that text is its command with leading `VAR=value` assignments
  84. and redirections removed, so a secret passed as an argument is kept there until
  85. the entry settles or is dismissed.
  86. ## Limits
  87. It is a reminder, not a guarantee. Commands are matched by their text, and the
  88. matching leans towards missing a spawn over recording one that never happened,
  89. so an empty ledger does not prove a clean machine.
  90. - Not recorded: a server started inside a tmux pane with `send-keys`, the
  91. app's own preview server, a daemon that forks by itself, a command typed into
  92. a terminal by hand, a `mktemp -d` whose path is never printed.
  93. - A background command that ends by itself stays until a check or a Dismiss
  94. clears it. A background task reported as completed is not a receipt: the
  95. shell of `server & echo $!` completes while the server lives.
  96. - Exercised on macOS only. A `pgrep` that counts the shell wrapping it never
  97. prints nothing; `ps -p` and `lsof` settle the entry there.
  98. ## Requirements
  99. A Claude Code build with function-hook plugins; CI validates and tests against
  100. 2.1.325.
  101. ## License
  102. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

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