SkillAgentSearch skills...

duscope

Fast, queryable disk-usage analyzer with JSON output and an MCP server

Install / Use

claude mcp add kawadeomkar -- npx -y github:kawadeomkar/duscope

If the server publishes to npm under a different name, use that package instead — check the repo README.

About this skill
🔌

MCP Server

Model Context Protocol server

Quality Score

80/100

Supported Platforms

Claude Code
Claude Desktop

Our assessment of duscope

duscope scores 80/100 on our quality scale, 525th of 598 Data & Analytics skills we index.

Its MCP Server is 19 KB long, well organised into 14 sections with 18 code examples: a thorough specification that gives an agent plenty to work with.

It has 3 GitHub stars, so there is little community track record yet; judge it on its content.

Substance
30/30
Structure
20/20
Description
12/15
Adoption
3/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated today, so duscope is actively maintained.
  • It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 87/100, with 2 cautions from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands (1 minor note below).

  • noteInstalls by piping a downloaded script into a shellline 50
    curl --proto '=https' --tlsv1.2 -LsSf https://github.com/kawadeomkar/duscope/releases/latest/download/duscope-installer.sh | sh

Automated pattern scan on 2026-11-21. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

duscope compared with similar skills

All 4 of these similar skills score higher than duscope; compare them before choosing.

SkillScoreStarsUpdatedFormat
duscope (this skill)by kawadeomkar803todayMCP Server
claude-memby thedotmack100119.0ktodayCLAUDE.md
Agent-Reachby Panniantong100114.0ktodayCLAUDE.md
hyperframesby heygen-com10088.2ktodayCLAUDE.md
rufloby ruvnet10082.3ktodayCLAUDE.md

Frequently asked questions

How do I install duscope?
Run claude mcp add kawadeomkar -- npx -y github:kawadeomkar/duscope. The install tabs above show the steps for each supported agent.
Which AI agents does duscope work with?
It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
Is duscope safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands (1 minor note below). It is Apache-2.0-licensed and scores 87/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is duscope still maintained?
The repository was last updated today, so duscope is actively maintained.

duscope

[!NOTE] v0.3.0, agents. duscope mcp serves eleven read-only tools to MCP clients over stdio. They scan a directory, list the saved scans and answer summary, top, by-type, stale, caches, explain, diff, schema and read-only SQL from them, each in its verb's JSON envelope, and reach nothing outside the directories given to --roots; --allow-delete adds a twelfth, which moves entries to the Trash. duscope agent --skill writes the skill an agent's client loads: in the project's evaluation, agents used 29.5% fewer tokens with it (bench/README.md). v0.3.0 also carries the interactive viewer (duscope view) and clean, held to their own gate in v0.4, and, on macOS, rescans that read only what changed.

duscope is a disk-usage analyzer for macOS and Linux. It scans a directory tree once, in parallel, and:

  • draws the tree as a coloured treemap in the terminal, as a static map or in an interactive viewer, or renders it as SVG or PNG;
  • answers the questions that free space: the largest directories and files, large files untouched for months, bytes by file type, regenerable caches, and what deleting a path would free;
  • keeps each scan in a SQLite index with precomputed subtree totals, answers from it in milliseconds, compares two scans and takes read-only SQL;
  • prints one versioned JSON envelope, sized to fit the output limits of scripts and AI agents;
  • serves the same read-only operations to agents as a stdio MCP server.

Its sizes are what deleting would free: hard links count once on every filesystem, and it accounts for APFS clones and firmlinks on macOS and for subvolumes and bind mounts on Linux. On Linux a scan counts each btrfs or XFS reflinked copy in full, as du does, and duscope explain --clones measures what they share (limits). Linux and macOS are both first-class, with one binary, one set of commands and one JSON format.

Install

GitHub Releases and crates.io carry each release from v0.1.0 (v0.0.1 was the pre-release placeholder). The other channels open with the release each one names.

GitHub Releases

Prebuilt binaries for macOS (Apple silicon and Intel) and Linux (x86_64 and arm64, statically linked with musl), built by cargo-dist with build attestations. The shell installer picks the archive for the machine and installs duscope into ~/.cargo/bin:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/kawadeomkar/duscope/releases/latest/download/duscope-installer.sh | sh

To check a downloaded archive was built by this repository's release workflow:

gh attestation verify duscope-aarch64-apple-darwin.tar.xz --repo kawadeomkar/duscope

Homebrew

On macOS and Linux from v0.1.0, from the tap kawadeomkar/homebrew-tap, with the man page and the shell completions. Homebrew pours a bottle where the tap has one for the machine (Apple-silicon macOS, x86_64 Linux) and otherwise builds duscope from source, with its own Rust:

brew install kawadeomkar/tap/duscope

Once duscope meets homebrew-core's notability bar, the formula moves to homebrew-core and brew install duscope works without the tap.

Debian and Ubuntu

.deb packages for amd64 and arm64, attached to each GitHub release from v0.1.0. They install one statically linked binary (musl), which needs no particular glibc, with the man page and the bash, zsh and fish completions:

sudo apt install ./duscope_<version>_amd64.deb

The signed apt repository, https://kawadeomkar.github.io/duscope/apt, serves the same packages, so sudo apt install duscope installs duscope on Debian 12 and later and Ubuntu 22.04 and later, and apt upgrade keeps it up to date. docs/apt.md has the commands that add it and its key's fingerprint. It is not live yet: it opens once its signing key exists (phase 5, before 1.0), with the first release after that.

crates.io

cargo install duscope --locked

It needs Rust 1.89 or later and a C compiler, which builds the SQLite duscope bundles. Cargo builds it with its default release settings: duscope's release profile (link-time optimisation, symbols stripped) applies only to builds inside this repository, so the binary is larger than the prebuilt ones. Cargo installs no man page or completions: duscope man and duscope completions print them.

The pixels feature adds --treemap pixels: the map drawn in pixels on a terminal that shows images through Kitty graphics, Sixel or iTerm2's inline images, asked for only when the flag is given. No prebuilt package has it, and it needs Rust 1.90 or later:

cargo install duscope --locked --features pixels

Inside tmux the map stays in cells, with a warning: asking the terminal through tmux would mean running tmux set -p allow-passthrough on, which changes the pane's settings for every program after duscope, and duscope runs no other program.

From source

It needs rustup, which installs the toolchain pinned in rust-toolchain.toml, and a C compiler:

git clone https://github.com/kawadeomkar/duscope
cd duscope
rustup toolchain install
cargo build --release
./target/release/duscope --version

A tour

The first command scans the tree and saves the scan in the index directory ($XDG_CACHE_HOME/duscope, else ~/Library/Caches/duscope on macOS and ~/.cache/duscope elsewhere; --index-dir names another); the summary line names it. The commands after it answer from that saved scan, as every command does when a saved scan holds its path: an answer then takes milliseconds, however large the tree. --no-save scans without saving, --scan names another saved scan, and scan (or duscope alone) scans afresh, unless --reuse AGE lets it print a saved scan younger than that.

The output below is from the fixture tree duscope's tests build (just fixtures), a made-up home directory, on macOS (APFS); a terminal shows it in colour. On Linux some allocated sizes differ, and the thread count at the end of the first summary line is the machine's default. Every scan gets an id of its own, so yours is not 1fd3. Paths in the home directory are shortened to ~ here; duscope prints them in full.

top lists the largest directories. A directory holding 80% of its parent's bytes is cut through to the child that holds them, so the row says where the space is:

$ duscope top ~ --limit 6
    Size      %   Files  Path
79.3 MiB  36.0%  24,859  ~/Library
54.3 MiB  24.6%   8,604  ~/dev
30.0 MiB  13.6%       8  ~/Movies
10.5 MiB   4.8%     250  ~/Music
10.0 MiB   4.5%   2,001  ~/Documents
 7.9 MiB   3.6%   4,000  ~/.cache
220.6 MiB allocated · 43,137 files · 8,129 dirs · 0.1 s, 16 threads, saved as 1fd3

tree shows each entry's share of its parent, here only those of at least 10%:

$ duscope tree ~/Projects --depth 1 --min-pct 10
   Size       %  Path
5.9 MiB  100.0%  ~/Projects
3.5 MiB   59.0%    rust-cli/
1.1 MiB   17.9%    npm-app/
5.9 MiB allocated · 94 files · 137 dirs · saved scan 1fd3 from 2037-01-01 00:00

by-type adds bytes up by class; a directory rule wins over the extensions inside it (node_modules is code, whatever it holds):

$ duscope by-type ~
    Size      %   Files  Class
54.7 MiB  24.8%  18,988  data
50.9 MiB  23.1%   1,704  media
44.0 MiB  20.0%   4,055  binaries
24.5 MiB  11.1%   6,277  code
15.1 MiB   6.8%   4,932  docs
 7.4 MiB   3.3%     197  archives
23.9 MiB  10.9%   6,983  other
220.6 MiB allocated · 43,137 files · 8,129 dirs · saved scan 1fd3 from 2037-01-01 00:00

stale finds large files neither modified nor changed for a while:

$ duscope stale ~ --older-than 1y --min-size 1M
   Size    Modified  Path
7.0 MiB  2035-08-20  ~/Movies/holiday-2035.mov
6.0 MiB  2034-01-02  ~/Movies/wedding.mp4
4.0 MiB  2035-01-02  ~/Movies/lecture-01.mkv
4.0 MiB  2035-01-02  ~/Movies/lecture-02.mkv
3.0 MiB  2035-01-02  ~/Downloads/Xcode_16.1.xip
1.5 MiB  2034-10-24  ~/Downloads/ubuntu-24.04.1-live-server-arm64.iso
220.6 MiB allocated · 43,137 files · 8,129 dirs · saved scan 1fd3 from 2037-01-01 00:00

Scripts take --plain (tab-separated, sizes in bytes) or --json, the envelope every verb shares; agents get JSON without asking. Nothing but the payload reaches stdout, and the summary line goes to stderr (the two blocks below leave it out):

$ duscope top ~ --files --limit 3 --plain
7340032	7340032	1	0	2035-08-20T00:00:00Z	file	~/Movies/holiday-2035.mov
6291456	6291456	1	0	2034-01-02T00:00:00Z	file	~/Movies/wedding.mp4
5242880	5242880	1	0	2036-12-12T00:00:00Z	file	~/Movies/screen-recording.mov

The envelope is one JSON object: "ok": true, the scan and the query, and the rows in entries, here picked out with jq:

$ duscope top ~ --files --limit 2 --json | jq -c '.entries[] | {path, kind, allocated_bytes}'
{"path":"~/Movies/holiday-2035.mov","kind":"file","allocated_bytes":7340032}
{"path":"~/Movies/wedding.mp4","kind":"file","allocated_bytes":6291456}

scans lists the saved scans; here the one the first command saved:

$ duscope scans --json | jq -c '.entries[] | {root, entry_count, source}'
{"root":"~","entry_count":51266,"source":"scan"}

explain says what one path is and what deleting it would free, here a node_modules directory, with the command that builds it again:

$ duscope explain ~/dev/node_modules --json | jq -c '.result | {kind, allocated_bytes, freeable_now_bytes, regenerable_by, confidence}'
{"kind":"dir","allocated_bytes":18247680,"freeable_now_bytes":18247680,"regenerable_by":"npm install","confidence":"high"}

query --sql runs one read-only SELECT over the saved scan's tables (docs/index-format.md; duscope schema lists them), here the extensions holding the most data:

$ duscope query ~ --plain --sql "SELECT human_size(sum(apparent)) AS size, count(*) AS files, ext FROM files WHERE ext != '' GROUP BY ext ORDER BY sum(apparent) DESC, ext LIMIT 4"
size	files	ext
17.1 MiB	147	mov
8.0 MiB	2	mkv
7.1 MiB	129	mp4
3.0 MiB	1	xip

diff compares two saved scans of one tree, by id: what appeared, went, grew and shrank, the largest change first. After a week's work on the home directory, for example:

duscope scan ~ --save          # saved as 7a2c
duscope diff 1fd3 7a2c

duscope alone, or duscope scan ~, draws the treemap: a box per folder, a tile per file, coloured by class, with the legend and the next commands below. duscope render ~ -o home.svg writes it as SVG (--format png for PNG), and duscope export ~ --format ncdu -o home.json writes the scan for ncdu (or GrandPerspective's .gpscan, QDirStat's cache or CSV), and duscope import saves a tree that ncdu, gdu or GrandPerspective wrote. duscope man prints the manual page, and duscope completions bash (or zsh, fish, elvish, powershell) the completion script.

The interactive viewer

duscope view ~ opens the treemap in an interactive viewer, on the newest saved scan that holds the path (or on a new scan, which it saves), and duscope scan ~ -i scans first. It needs a terminal of at least 80×24, and gives the terminal back as it found it when it ends.

The map fills the screen; from 110 columns a column at its right holds the selection's facts, its siblings and the legend of the colours. The selection starts on the file reached by taking the largest entry at every level. The line at the bottom shows six keys for what is in focus, and ? lists them all, as this table does (⏎ is Enter, ⌫ Backspace and ⇥ Tab):

| Keys | What they do | | --- | --- | | ←↓↑→ hjkl | Move to the neighbouring tile, or along a list or the pane in focus | | ⏎ | Go down the path; in the largest files, show the file on the map; in the types and the legend, keep that row's tiles on the map | | ⌫ | Go up the path | | `Esc

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars3
CategoryData
Updated1h ago
Forks1

Languages

Rust

Trust signals

87/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

2 low