| name | elisp-unused-vars |
| description | Find unused defvar/defvar-local/defcustom variables in Emacs Lisp projects. Use when cleaning up elisp code, reviewing for dead code, or when asked to find unused variables in .el files. |
Emacs Lisp Unused Variable Finder
Find defvar, defvar-local, and defcustom declarations that are defined but never referenced elsewhere.
Usage
Launch an Explore subagent to analyze the codebase:
Task(subagent_type="Explore", prompt="""
Find unused defvar/defvar-local/defcustom variables in the elisp files.
For each variable definition found:
1. Search for references to that variable name across all .el files
2. A variable is "unused" if it only appears in its own definition
Report format:
| File | Variable | Type | Status |
|------|----------|------|--------|
| path | name | defvar/defvar-local/defcustom | unused/used |
Focus on: <target files or directories>
""")
Detection Logic
A variable is unused if:
- Defined with
defvar, defvar-local, or defcustom
- Only occurrence in codebase is the definition itself
- Not referenced in any other expression
A variable is effectively dead if:
- Defined and checked (e.g., in a
when clause)
- But never set/assigned anywhere
- Common pattern: callback variables that were never wired up
Common Patterns
Vestigial callbacks: Variables like foo--save-callback that are checked but never set—indicates abandoned refactor.
Orphaned state: Buffer-local variables from removed features.
Unused customization: defcustom options for features that were removed.
Example Output
Found 3 potentially unused variables:
1. beads-types--original-custom (defvar-local)
- lisp/beads-types.el:52 - definition only
- No other references found
- Recommendation: REMOVE
2. beads-types--save-callback (defvar-local)
- lisp/beads-types.el:55 - definition
- lisp/beads-types.el:207 - checked but never set
- Recommendation: REMOVE (dead code path)
3. beads-types--cancel-callback (defvar-local)
- lisp/beads-types.el:58 - definition only
- No other references found
- Recommendation: REMOVE
