ClaudeMiner 사용 가이드

What ClaudeMiner is

ClaudeMiner is a small visual monitor that shows each Claude Code process running on your computer as a little miner character. If you keep several terminals open and hand tasks to Claude Code in each, it is hard to tell at a glance which window is still working, which one has finished, and whether a process is lingering after you closed its terminal. ClaudeMiner exists to answer those questions quickly. It is open source under the MIT license, built with Rust and Tauri on the system WebView rather than a bundled Chromium, and the project documentation puts its memory use at roughly 20MB.

Who it is for

• People who run two or more Claude Code sessions at the same time
• People who start a long task, switch to other work, and keep checking the terminal to see whether it is done
• Anyone who has suspected that a process kept using CPU after the terminal was closed

If you run a single session and watch it continuously, the benefit is small. When you work with several sessions in parallel, being able to see who is busy at a glance is the main value.

Screens at a glance

Below is the main window. Each character in the middle area is one detected Claude Code process, and the number on its tag is the PID (process ID). The legend at the bottom shows a pickaxe for working, a sleepy face for resting and a zombie figure for zombie, with the note that clicking an icon shows the PID and zombies can be terminated.

Reading the three miner states

For every Claude Code process it detects, ClaudeMiner shows one character in one of three states. The README defines them as follows.

• Working: the process is using more than 10% CPU. This usually overlaps with Claude Code generating a response or running tools.
• Resting: CPU use is below 10%. The session is idle or waiting for your input.
• Zombie: the process has no controlling terminal (no TTY). This is the case where the terminal window is gone but the process remains.

How it detects sessions

According to the project documentation, ClaudeMiner scans the running process list at a configurable interval (2 seconds by default), finds Claude Code processes and reads their CPU and memory usage. On macOS it also checks TTY information through the ps command to identify zombies. The data it reads is limited to process IDs and CPU and memory figures; the documentation states that it does not read your conversations or code, has no analytics, and keeps everything local.

Installation and requirements

1. Open the Releases section of the GitHub repository linked above and find the latest release. At the time of writing the README points to a macOS build for Apple Silicon (.dmg).
2. Open the .dmg, move the app into your Applications folder and launch it.
3. To receive notifications, allow the macOS notification permission prompt on first launch. You can change it later in System Settings under Notifications.
4. Start Claude Code in a terminal as usual. Within a few seconds the session should appear as a miner.

The README lists macOS 10.15 or later, or Windows 10 or later, plus an installed Claude Code. The internal docs add that on Windows process detection works but TTY detection is disabled, so zombie detection is most accurate on macOS. To build from source, the README describes running npm install and then npm run tauri build inside development/app.

Notifications and settings

On macOS you can be notified when a miner finishes working, when a new Claude Code session starts and when a zombie process is found. The settings panel lets you toggle notifications and pick a refresh interval of 1, 2, 5 or 10 seconds. Clicking a miner badge copies its PID, and the docs say a zombie process can be terminated from the app in one click.

A workflow for running parallel sessions

For someone running several sessions at once, the number of times you ask "which one is still working?" is itself a cost. Keep ClaudeMiner small on one side of your screen and use this flow to cut down on flipping between terminals.

1. Hand off the tasks and go do something else. Confirm one miner appears per session. If the count differs from what you expect, you can see right away which terminal is missing.
2. Wait for the notification. With macOS notifications on, you are told when a session finishes its work. Notifications are judged from state changes, so check the result in that terminal.
3. Check sessions that sit in resting. Resting cannot tell "finished" from "waiting for input", so when a notification arrives, open the terminal and confirm it really finished.
4. Clean up zombies. For a process left as a zombie after you closed its terminal, confirm the PID and then terminate it. Match the PID so you do not kill an unrelated job.

How to split work for parallel runs and how to manage sessions and work trees is covered in managing multiple Claude Code sessions at once.

Practical tips

• Start a long task, work in another window, and come back when the completion notification arrives. It cuts down on cycling through terminals.
• A longer refresh interval (5 to 10 seconds) lowers battery and CPU overhead further. Use 1 to 2 seconds if you want quicker feedback.
• The PID copy feature helps when you want to inspect or stop a specific session from another terminal.

Things to watch out for

• Before terminating a zombie, make sure the process is truly unused. A terminated process cannot be brought back.
• The 10% CPU threshold is a simple heuristic, so brief misreadings are possible.
• ClaudeMiner observes; it does not control Claude Code, and it is an independent project not affiliated with the makers of Claude Code.

Limits and known issues

• State is an indirect signal: CPU usage. The rule is simple: above 10% CPU is working, below 10% is resting, so a moment of waiting on the network or a gap between tool runs can look like "resting". Conversely it cannot tell waiting for your input from having just finished.
• Zombie detection is most accurate on macOS. A process with no attached terminal (TTY) counts as a zombie, and the development notes say that on Windows process detection works but TTY detection is turned off. Notifications are described for macOS too.
• The officially documented build is macOS for Apple Silicon. The README download is an aarch64 .dmg, and building from source is described for other environments.
• Refresh is a periodic check. The default is 2 seconds, selectable in settings from 1, 2, 5 and 10 seconds. A brief stop-and-start between checks can be missed.
• It is observe-only and does not control anything. It cannot start or stop Claude Code for you, and the only write action is terminating a zombie process when you press the button. A terminated process cannot be brought back.
• It is an independent project, unrelated to Claude Code's developer. If Claude Code's process names or behavior change, detection may drift, so please report issues on GitHub.

How it compares

The two approaches complement each other rather than compete. If you need an accurate completion signal, use the official hooks; to skim the state of several sessions and clean up leftover processes, a visual monitor like ClaudeMiner fits.

Sources and further reading

1. GitHub: JUKI-J/claudeminer (README and releases)
2. Claude Code docs: Hooks reference
3. Claude Code docs: Hooks guide
4. Tauri: the app framework

FAQ