recur

v0.1.15

Recursive, hierarchy-aware search for modern codebases.

Development is mainly using ChatGPT 5.2+ Codex and Claude Sonnet & Opus 4.5+ tied to vscode. I run out of tokens on one I usually switch to the other one. I use Julia for tests as I'm more familiar with that to verify work. I actually don't understand Rust at all, but it seems pretty easy to vibe code as long as I can verify and control that direction with the tests. I also test recur in a private Github Copilot project which will remain nameless so as not to reek havoc.

recur is a command-line tool for working with hierarchically named code: files, modules, and identifiers that encode structure using dot-separated or “C#-style” naming conventions. While tools like grep and ripgrep excel at fast text matching, they treat results as flat lists. recur complements them by understanding hierarchy—so you can search, navigate, and analyze related code as a structured system.

Inspired by Dennis M. Ritchie’s 1968 work on recursive hierarchies and program structure.

# Search within a hierarchical scope
recur find "CreateSection" --scope "LevelController.CreateWizard3"

# Visualize a hierarchy as a tree
recur tree "LevelController"

# Discover related (sibling) files in the hierarchy
recur related "Service.Module.Feature.cs"

Why recur?

Many modern codebases encode structure directly into names:

LevelController.CreateWizard3.Templates.cs
config.database.connection.timeout
user.level.up.services.game

Traditional tools (e.g., grep, awk, find) do not interpret these as recursive hierarchies. recur does—making it easier to:

• search within a subsystem (scope),
• visualize nested structure (tree),
• find related files (siblings/children),
• and locate hierarchical identifiers in code.

Installation

What you get: Two binaries for a complete toolset:

• recur - Core hierarchy tool (pure, no Git dependencies)
• recur-git - Git workflow extension (checkpoint tracking, dogfooding)
  • recur-git depends on existing git binaries to already be installed

From Cargo (crates.io)

cargo install recur

From source (local checkout)

cargo build --profile release-safe --locked
cargo install --path . --profile release-safe --locked --force --offline

Both binaries will be installed to Cargo's bin folder. If recur is not found, add it to PATH:

• Windows: %USERPROFILE%\.cargo\bin
• macOS/Linux: ~/.cargo/bin

Debian/Ubuntu

# Coming soon
sudo apt install recur

Arch Linux

# Coming soon (AUR)
yay -S recur

Quick Start

# Search within a hierarchy scope (recursive)
recur find "async" --scope "Controller.Api"

# Search with context lines (similar to grep -C)
recur find "CreateSection" --scope "LevelController.**" -C 2

# View hierarchy as a tree (recursive structure)
recur tree "ServiceName"

# Find files matching a hierarchical pattern (recursive)
recur files "Controller.*.Tests"

# Find related files (siblings in hierarchy)
recur related "UserService.Handlers.Create.cs"

# Find related files excluding the input file
recur related "UserService.Handlers.Create.cs" --exclude-self

# Search for hierarchical identifiers (recursive)
recur id "config.database.*" -C 1

# Analyze hierarchy statistics by depth (with listing at depth level)
recur stats "ServiceName" -l 1

Features

Core capabilities

• Hierarchy-aware pattern matching with * and ** wildcards
• Multi-separator merge — unify results across naming conventions (. and _)
• Scoped text search within a hierarchy (grep-like, but structure-aware)
• Context lines via -C (show surrounding lines like grep -C)
• Tree visualization using Unicode box-drawing characters
• Related file discovery (siblings within the hierarchy)
• Identifier search (dot-notation identifiers in code)
• Hierarchy statistics with depth analysis and pagination
• Cross-domain gap analysis — verify completeness across representations
• Multiple output formats (human-friendly terminal output, plus JSON for tooling)
• Proper exit codes (0=success, 1=no results, 2=error)

Grep-like options

• -C N - Show N lines of context around matches
• -i - Case-insensitive search
• -E - Use regular expressions
• --json - Output results as JSON
• --color - Colorized output (auto-detected)

Multi-separator merge (Cross-domain entity tracking)

Problem: Documentation uses dots (api.user.service.md), source code uses underscores (api_user_service.rs). Traditional tools can't unify them.

Solution: Use multiple --sep flags to merge results across naming conventions:

# Merge documentation (dots) + source code (underscores)
recur tree main --sep "." --sep "_"

# Show which domain each file comes from (gap analysis)
recur tree main --sep "." --sep "_" --show-sep

# Normalize output to consistent separator
recur files "main.command.**" --sep "." --sep "_" --sep-replace-default "."

Use cases:

• Living documentation — verify code has matching docs/tests
• Polyglot projects — navigate TypeScript (.) + Python (_) + Go (/) as one
• Configuration management — track configs across file (.) and env-var (_) conventions
• Build pipelines — verify artifact completeness across naming conventions
• Gap analysis — --show-sep marks each file's origin: [.] or [_]

See docs/main.trait.separator-merge.readme.md for details.

Commands

recur files — find files by hierarchical pattern

recur files "Controller.*"                    # All direct children
recur files "Controller.**"                   # All descendants (recursive)
recur files "*.Tests" --ext .cs              # Test files only
recur files "Module.*" --count               # Show count only
recur files **.AutoSave.** -i -e cs          # No quotes needed with stdin stdout

# Multi-separator merge (cross-domain)
recur files "main.**" --sep "." --sep "_"                        # Merge docs + src
recur files "api.user.**" --sep "." --sep "_" --show-sep         # With markers
recur files "config.**" --sep "." --sep "_" --sep-replace-default "."  # Normalized

recur find — search text within a hierarchy scope

recur find "async" --scope "Controller.Api"          # Search in scope
recur find "TODO" --scope "Service.**" -C 2          # With context
recur find "pattern" --scope "Module" -i             # Case-insensitive
recur find "async.*Task" --scope "**" -E             # Regex search

recur tree — visualize hierarchy as a tree

recur tree "ServiceName"                     # Unicode tree view
recur tree "ServiceName" --count             # With file counts
recur tree "ServiceName" --ascii             # ASCII-only (no Unicode)
recur tree "ServiceName" --json              # JSON output

# Multi-separator merge (cross-domain)
recur tree "main" --sep "." --sep "_"                      # Merge docs + src
recur tree "main" --sep "." --sep "_" --show-sep           # With domain markers
recur tree "api" --sep "." --sep "_" --sep-replace-default "."  # Normalized

recur merge — merge results across separators

# Merge docs (.) and source (_) into one view
recur merge --pattern "main.command" --sep "." --pattern "main_command" --sep "_"

# Show provenance markers in the merged tree
recur merge --pattern "api.user" --sep "." --pattern "api_user" --sep "_" --show-sep

# Normalize output to dots for display
recur merge --pattern "main.command.tree" --sep "." --pattern "main_command_tree" --sep "_" --sep-replace-default "."

# Phase 4 file mode: merge cached JSON outputs
recur tree "main.command" --sep "." --json > main.command.json
recur tree "main_command" --sep "_" --json > main_command.json
recur merge main.command.json --sep "." main_command.json --sep "_" --base "main.command" --show-sep

# File mode with files JSON
recur files "main.command.**" --sep "." --json > main.command.files.json
recur files "main_command_**" --sep "_" --json > main_command.files.json
recur merge main.command.files.json --sep "." main_command.files.json --sep "_" --base "main.command" --show-sep

recur related — find sibling files

recur related "Service.Module.Feature.cs"                 # Include self
recur related "Service.Module.Feature.cs" --exclude-self  # Exclude self

recur children — find child files

recur children "Service.Module"              # All children
recur children "Service.Module" --count      # Show count only

recur id — search for hierarchical identifiers

recur id "config.database.*"                 # Find identifiers
recur id "ulu.role.**" -C 2                  # With context lines
recur id "config.*" --ext .json              # JSON files only

recur stats — analyze hierarchy statistics

recur stats "ServiceName"                    # Summary with depth breakdown
recur stats "ServiceName" -l 0               # List files at depth 0 (base)
recur stats "ServiceName" -l 1               # List files at depth 1 (children)
recur stats "Controller.**" --ext .cs        # Stats for .cs files only
recur stats "**" --json                      # JSON output

Pattern Syntax (Recursive)

Pattern	Matches	Example
Module.Sub	Exact	Module.Sub.cs
Module.*	One level (depth = 1)	Module.Feature.cs
Module.**	Any depth (recursive)	Module.A.B.C.cs
*.Tests	Prefix wildcard	Module.Tests.cs
Module.**.Tests	Deep + suffix	Module.Sub.Feature.Tests.cs

Comparison

Feature	grep (1973)	rg (ripgrep)	recur (2026)
Fast text search	✅	✅	✅
Regex support	✅	✅	✅
Context lines (-C)	✅	✅	✅
Hierarchy-aware	❌	❌	✅
Tree view	❌	❌	✅
Scoped search	❌	❌	✅
Related file discovery	❌	❌	✅
Hierarchical patterns	❌	❌	✅

Note: recur does not replace rg or grep—it complements them. For raw text-search throughput, ripgrep is hard to beat. recur focuses on a different (and increasingly common) problem: working with structure encoded in names.

The Tribute

"Program Structure and Computational Complexity"
— Dennis Ritchie, PhD Thesis, Harvard, 1968

Ritchie’s thesis explored recursive functions and hierarchical program structures—ideas that later shaped Unix and C. recur is a small tribute to that legacy: bringing hierarchy-aware understanding to everyday developer search workflows.

Why the name “recur”?

1. Recursive — searches hierarchies recursively
2. Recur — short and memorable (in the tradition of grep, awk, sed)
3. Ritchie — honors Dennis Ritchie’s early work on hierarchical program structure
4. Unix philosophy — aim for a focused tool that composes well

Documentation

• Full Tribute — the Dennis Ritchie connection
• White Paper — design and philosophy
• Proposal — technical design
• Contributing — how to contribute
• Implementation — code walkthrough

recur-git: Git Workflow Extension

recur-git is a separate binary for Git-aware workflows. It keeps recur pure (focused on hierarchies) while adding checkpoint tracking for dogfooding.

Checkpoint tracking:

# Snapshot current state (git + active todo leaves)
recur-git checkpoint --snapshot

# Append to checkpoint log (requires --file)
recur-git checkpoint --append-parallel --checkpoint-id ck-phase3-01 -f checkpoints.md

See docs/main.recur-git.artifact.md for details.

Contributing

Contributions are welcome. Please see CONTRIBUTING.md.

For dogfooding state transitions and commit checkpoints, use:

• docs/main.git.checkpoint.readme.md
• scripts/dogfooding_checkpoint.ps1
• recur-git checkpoint commands (see above)

Local git hook note

This repo uses a local-only pre-commit hook on the maintainer's machine to bump VERSION, update Cargo.toml, and refresh Cargo.lock when committing on main. Git hooks live in .git/hooks and are not shared with other clones. If you need to update or remove it later, check .git/hooks/pre-commit.

git clone https://github.com/userlevelup/recur
cd recur
cargo test
cargo build --profile release-safe --locked
cargo run --profile release-safe -- tree "main" -d src
cargo install --path . --profile release-safe --locked --force --offline

License

MIT — permissive, simple, and broadly compatible.

Acknowledgments

recur is possible because of the tools and ideas that came before:

• Dennis M. Ritchie (1941–2011) — for foundational work on recursion and program structure
• Ken Thompson — for grep and the standard it set for developer tooling
• Andrew Gallant (BurntSushi) — for ripgrep and modern Rust CLI excellence
• The Unix philosophy — “Do one thing well”
• The Rust community — for the ecosystem that makes tools like this practical

---

recur: Hierarchy-aware search for the 21st century—built for modern naming conventions, inspired by foundational ideas in program structure.