duscope
Fast, queryable disk-usage analyzer with JSON output and an MCP server
Install / Use
claude mcp add kawadeomkar -- npx -y github:kawadeomkar/duscopeIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
Data & AnalyticsSupported Platforms
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.
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 foundOur 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.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| duscope (this skill)by kawadeomkar | 80 | 3 | today | MCP Server |
| claude-memby thedotmack | 100 | 119.0k | today | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 114.0k | today | CLAUDE.md |
| hyperframesby heygen-com | 100 | 88.2k | today | CLAUDE.md |
| rufloby ruvnet | 100 | 82.3k | today | CLAUDE.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.
Skill content
View source on GitHubduscope
[!NOTE] v0.3.0, agents.
duscope mcpserves eleven read-only tools to MCP clients over stdio. They scan a directory, list the saved scans and answersummary,top,by-type,stale,caches,explain,diff,schemaand read-only SQL from them, each in its verb's JSON envelope, and reach nothing outside the directories given to--roots;--allow-deleteadds a twelfth, which moves entries to the Trash.duscope agent --skillwrites 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) andclean, 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
claude-mem
119.0kPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
Agent-Reach
114.0kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
hyperframes
88.2kAI video you can actually edit. HyperFrames is a free, open-source AI video editor. Describe any video and get a real project you can change down to the frame.
ruflo
82.3k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
