Zettelkasten Refactor Tool

zrt is a command-line tool for analyzing and managing refactoring tasks in a Zettelkasten note system. It helps you identify files that need attention and track progress through tags.

Features

• File Analysis: Count files and words with tag-based filtering
• Tag-based Search: Find files with exact tag matches or missing tags
• Tag Frequency: List tags sorted by how many notes use them
• Connection Analysis: Find the most connected notes for a given tag
• Similarity Detection: Find similar notes for consolidation
• Word/Line Metrics: Identify files exceeding thresholds
• Flexible Configuration: Customize thresholds and sorting

Installation

From Source

git clone https://github.com/yourusername/zettelkasten-refactor-tool
cd zettelkasten-refactor-tool
cargo install --path zrt

Quick Start

1. Initialize zrt in your notes directory:

   zrt init

2. List files by word count:

   zrt wc -n 20

3. Find similar notes:

   zrt similar --threshold 0.6

Commands

zrt init (alias: i)

Initialize zrt configuration in the current directory.

zrt init

Creates .zrt/config.toml with default refactor thresholds (300 words, 60 lines).

zrt count (alias: c)

Count files, words, or calculate percentages by tags.

zrt count [OPTIONS] [TAGS...]

Flags (exactly one required):

• --files - Count files matching tags
• --words - Count words in files matching tags
• --percentage - Calculate percentage of words in tagged files

Options:

• -d, --dir <DIRECTORY> - Directories to scan (space-separated, default: current)
• -e, --exclude <DIRS> - Directories to exclude (space-separated)
• [TAGS...] - Tags to filter by (omit to count all)

Examples:

# Count all files
zrt count --files

# Count files with "refactored" tag
zrt count --files refactored

# Count words in files with "draft" or "wip" tags
zrt count --words draft wip

# Calculate percentage of words in refactored files
zrt count --percentage refactored

# Scan multiple directories
zrt count --files -d ~/notes ~/work refactored

Output: Single number (pipeable)

zrt wordcount (alias: wc)

Show files ordered by word or line count.

zrt wordcount [OPTIONS]

Options:

• -d, --dir <DIRECTORY> - Directories to scan (space-separated, default: current)
• -f, --filter <TAGS> - Filter out files with these tags (space-separated)
• -n, --num <TOP> - Number of files to show (default: 10)
• -e, --exclude <DIRS> - Directories to exclude (space-separated, default: .git)
• --exceeds - Only show files exceeding configured thresholds
• --sort-by <SORT> - Sort by words or lines (overrides config)

Examples:

# Top 10 files by word count
zrt wc

# Files without "refactored" tag, top 20
zrt wc -f refactored -n 20

# Only files exceeding thresholds
zrt wc --exceeds

# Sort by line count
zrt wc --sort-by lines

Output: File paths, one per line (pipeable)

zrt search (alias: s)

Search for files with exact tag matches.

zrt search [OPTIONS] (--tags <TAGS...> | --no-tags)

Options:

• -d, --dir <DIRECTORY> - Directories to scan (space-separated, default: current)
• -e, --exclude <DIRS> - Directories to exclude (space-separated)
• --tags <TAGS> - Find files with exactly these tags (no more, no less)
• --no-tags - Find files that have no tags at all

Examples:

# Files with only "refactored" tag
zrt search --tags refactored

# Files with exactly "draft" and "review" tags
zrt search --tags draft review

# Search in specific directory
zrt search -d ~/notes --tags refactored

# Files missing tags entirely
zrt search --no-tags -d thoughts/ blog/

Output: File paths, one per line (pipeable)

zrt tags (alias: t)

List tags sorted by how many notes use them.

zrt tags [OPTIONS]

Options:

• -d, --dir <DIRECTORY> - Directories to scan (space-separated, default: current)
• -e, --exclude <DIRS> - Directories to exclude (space-separated)
• --exclude-tag <TAGS> - Tag names to omit from results (space-separated)
• --limit <N> - Show only the top N tags

Examples:

# List all tags by frequency
zrt tags

# Top 5 tags, excluding meta-tags
zrt tags --limit 5 --exclude-tag refactored draft

# Scan specific directories
zrt tags -d thoughts/ blog/ --limit 10

Output: Tag names, one per line, sorted by frequency descending (pipeable)

zrt connected (alias: con)

Find the most connected notes for a given tag. Only wikilinks between notes that both share the tag are counted.

zrt connected [TAG] [OPTIONS]

Arguments:

• [TAG] - Tag to filter by (reads from stdin if not provided)

Options:

• -d, --dir <DIRECTORY> - Directories to scan (space-separated, default: current)
• -e, --exclude <DIRS> - Directories to exclude (space-separated)
• --limit <N> - Number of results to show (default: 20)

Examples:

# Most connected notes tagged "writing"
zrt connected writing

# Top 3 results
zrt connected writing --limit 3

Output: <tag> <file_path> per line, sorted by connection score descending (pipeable)

zrt similar (alias: sim)

Find similar notes for refactoring and consolidation.

zrt similar [OPTIONS]

Options:

• -d, --dir <DIRECTORY> - Directories to scan (space-separated, default: current)
• -e, --exclude <DIRS> - Directories to exclude (space-separated)
• --threshold <THRESHOLD> - Similarity threshold 0.0-1.0 (default: 0.5)

Examples:

# Find similar notes with default threshold
zrt similar

# Higher threshold for stricter matching
zrt similar --threshold 0.7

# Scan multiple directories
zrt similar -d ~/notes ~/work --threshold 0.6

Output: Pairs of file paths (space-separated), one pair per line, sorted by similarity (pipeable)

Frontmatter Exclusions:

Exclude specific pairs from results using exclude_similarity field:

---
tags: [research]
exclude_similarity:
  - [[duplicate-note]]
  - [[old-version]]
---

Configuration

zrt uses .zrt/config.toml to customize behavior.

Default Configuration

[refactor]
word_threshold = 300      # Files with 300+ words are large
line_threshold = 60       # Files with 60+ lines are large
sort_by = "words"        # Sort by "words" or "lines"

Configuration Options

• word_threshold: Minimum word count for --exceeds filtering
• line_threshold: Minimum line count for --exceeds filtering
• sort_by: Default sorting method ("words" or "lines")

Ignore Patterns

Create a .zrtignore file to exclude directories (gitignore-style):

.git/
node_modules/
archive/

File Format

zrt works with markdown files containing YAML frontmatter:

---
tags:
  - research
  - methodology
  - draft
exclude_similarity:
  - [[old-version]]
---

# Content here

Your note content...

Both inline tags: [tag1, tag2] and list format are supported.