Basilisk

Ever opened a massive Rust codebase and felt completely lost? Yeah, me too.

Basilisk is a lightweight TUI that helps you navigate and understand large Rust projects without wanting to throw your laptop out the window. Think of it as your x-ray vision into the code.

What's this for?

You know that moment when you're staring at a 50k line legacy codebase at 2am trying to figure out where literally anything happens? That's what this fixes.

• Jump between files instantly with fuzzy search
• See all structs, functions, and modules at a glance with line numbers
• Bookmark important spots so you don't lose your place
• Syntax highlighting that actually works (multi-line strings, Unicode, the works)
• Line numbers with bookmark indicators
• History/back navigation
• Actually works on older laptops (looking at you, Electron apps)

Features

Three-Pane Navigation

• Files - Browse and search all .rs, .toml, and .md files
• Symbols - Jump to functions, structs, enums, impls with line numbers
• Bookmarks - Mark important lines and jump back instantly

Smart Code Preview

• Syntax highlighting powered by tree-sitter
• Line numbers with dynamic width
• Bookmark indicators (red ► markers)
• Handles Unicode, multi-line strings, nested comments
• Graceful error handling for non-Rust files

Fuzzy Search

• Lightning-fast filtering across files and symbols
• Live result counts
• No lag even on huge codebases

Keybindings

Navigation:

• ↑/↓ - Move through lists
• Tab - Switch between Files/Symbols/Bookmarks
• j/k - Scroll code preview (vim style)
• b - Go back in history

Search & Bookmarks:

• / - Start fuzzy search (updates as you type)
• Esc/Enter - Exit search
• m - Toggle bookmark on current line

Quit:

• q - Exit

Install

git clone https://github.com/asterwuu/basilisk.git
cd basilisk
cargo run --release -- /path/to/your/rust/project

Or if you're feeling fancy:

cargo install --git https://github.com/asterwuu/basilisk.git

Usage

# Navigate your current project
basilisk .

# Or specify a path
basilisk /path/to/some/rust/project

The interface shows:

• Left pane: File/symbol/bookmark browser with search
• Right pane: Syntax-highlighted code with line numbers
• Bottom: Keybinding hints
• Top left: ASCII logo that changes color based on mode

Requirements

• Rust 2024 edition
• A terminal with UTF-8 support
• That's it

Why "Basilisk"?

Because when you stare at complex code long enough, you need something that can stare back and make sense of it. Also the name sounded cool.

Built with

• ratatui - For the TUI that doesn't suck
• tree-sitter - Parsing Rust code properly
• crossterm - Terminal handling
• fuzzy-matcher - Because exact matches are for cowards

Performance

• Starts instantly even on huge projects
• Low memory footprint (~20MB typical)
• Works smoothly on 8GB RAM machines
• Tested on files up to 10k+ lines

Limitations

• Currently Rust-only (support for other languages could happen if people want it)
• Bookmarks don't persist between sessions (yet)
• No configuration file (uses sensible defaults)

Contributing

Found a bug? Feature idea? PRs welcome. Just try to keep the code somewhat readable.

Troubleshooting

Logo shows garbled characters:

• Make sure your terminal supports UTF-8
• Try a different terminal emulator

Syntax highlighting looks wrong:

• This is expected for non-Rust files
• For Rust files with syntax errors, you'll see a warning

Program crashes on large files:

• Please open an issue with the file size and specs

License

MIT - do whatever you want with it

---

Made with ☕ and mild frustration at existing code navigation tools