# DroidTUI 🤖
[](https://crates.io/crates/droidtui)
[](LICENSE)
[](https://github.com/sorinirimies/droidtui/actions/workflows/release.yml)
[](https://github.com/sorinirimies/droidtui/actions/workflows/ci.yml)
A beautiful Terminal User Interface (TUI) for Android development — ADB commands, live logcat viewer, device dashboard, and more. Built with Rust, Ratatui, and the pure-Rust `adb_client` crate (no Android SDK required).
## Features ✨
### 📺 Live Logcat Viewer
Full-screen, real-time logcat streaming with professional-grade tooling:
- **Live streaming** via `adb_client`'s native API — no `adb` binary needed
- **Regex search** (`r` toggle) — powerful pattern matching (`Error|Exception`, `OkHttp.*failed`)
- **Find filter** (`f`) — case-insensitive substring search with match highlighting
- **Exclude filter** (`e`) — negative matching to hide noisy tags/messages
- **Tag & PID filters** (`t`, `p`) — dedicated filter fields
- **Log level filter** (`l`) — cycle minimum level V → D → I → W → E → F
- **Per-tag color hashing** — each tag gets a stable, visually distinct color
- **Stack trace folding** (`F`) — detect and fold/unfold Java/Kotlin stack traces
- **Line detail popup** (`Enter`) — inspect any line with full message, JSON formatting
- **Bookmarks** (`m`, `[`, `]`) — mark lines and jump between them
- **Copy to clipboard** (`y`) — copy selected line via `pbcopy`/`xclip`
- **Soft wrap** (`w`) — wrap long messages across multiple rows with aligned indentation
- **Compact mode** (`x`) — hide timestamp/PID columns for more message space
- **Horizontal scroll** (`←`/`→`) — scroll long messages when wrap is off
- **Auto-scroll** — sticks to bottom; manual scroll disables; `G`/`End` re-enables
- **Pause / Resume** (`Space`) — freeze the view without losing the stream
- **Live stats** — lines/sec rate and per-level counters in the status bar
- **Save logs** (`s`) — save to file with path input dialog
- **Save As…** (`S`) — browse with integrated file explorer, `Shift+S` to save in current folder
- **JSON export** — Tab in save dialog cycles TXT/JSON format (JSONL for Nushell/jq)
- **Bounded channel** — `sync_channel(10k)` with backpressure prevents OOM during bursts
- **JSON detection** — auto-detects and pretty-prints JSON in log messages with syntax coloring
### 📱 ADB Command Dashboard
- **Device panel** — live device selector with model, Android version, battery, RAM, CPU stats
- **40+ typed commands** — packages, system, network, root toolkit, bootloader & flash
- **Fastboot support** — OEM unlock/lock, wipe data, device info
- **Type-safe execution** — compile-time guarantees via `adb_client` crate
### 🎨 Theme System
- **12 named presets** — Default, Dracula, Nord, Gruvbox Dark, Catppuccin Mocha, Tokyo Night, Solarized Dark, Moonfly, Oxocarbon, Forest, Neon, Mono
- **Global selector** (`Shift+T`) — works from any screen
- **11 colour fields** — brand, accent, success, dim, fg, sel_bg, warn, error, surface, border, key_hint
### 🖥️ CLI Query Mode
Stream logcat as JSON lines to stdout — designed for piping into Nushell, jq, or grep:
```bash
droidtui --query # Stream live logcat as JSONL
droidtui --query --last 500 # Dump last 500 lines
droidtui --query --level E # Only errors
droidtui --query --tag MyApp # Filter by tag
droidtui --query --grep "timeout" # Filter by message
### 📂 Nushell Recipe Scripts
Pre-built analysis scripts in `scripts/logcat/`:
| `top_tags.nu` | Rank tags by frequency (top 20) |
| `error_summary.nu` | Group Error/Fatal by tag with sample messages |
| `timeline.nu` | Log volume + error count per second |
| `find_crashes.nu` | Detect Fatal entries, ANRs, exceptions |
| `filter_json.nu` | Extract and pretty-print JSON payloads from messages |
```bash
droidtui --query --last 5000 > logcat.jsonl
nu scripts/logcat/top_tags.nu logcat.jsonl
```
## Installation 🔧
### From crates.io
```bash
cargo install droidtui
```
### From source
```bash
git clone https://github.com/sorinirimies/droidtui.git
cd droidtui
cargo install --path .
```
### Prerequisites
- **ADB server** running (`adb start-server`) — the `adb` binary is only needed to start the server; all commands use the pure-Rust `adb_client` crate
- A connected Android device with USB debugging enabled
## Usage 🎮
```bash
droidtui # Launch the TUI
droidtui --query # CLI mode — stream logcat as JSON
droidtui --help # Show all options
```
### Key Bindings — Main Menu
| `↑`/`↓` or `j`/`k` | Navigate menu |
| `Tab` / `Shift+Tab` | Jump between sections |
| `Enter` | Execute selected command |
| `L` | Open Live Logcat |
| `T` | Open Theme Selector |
| `d` | Cycle connected device |
| `r` | Refresh device info |
| `q` / `Esc` | Quit |
### Key Bindings — Logcat Viewer
#### Navigation
| `↑`/`↓` or `j`/`k` | Scroll up/down |
| `PgUp` / `PgDn` | Scroll 20 lines |
| `g` / `G` or `Home`/`End` | Jump to top / bottom |
| `←` / `→` | Horizontal scroll (when wrap off) |
| `0` | Reset horizontal scroll |
#### Filters
| `f` | Find (search filter) |
| `e` | Exclude filter (negative match) |
| `t` | Tag filter |
| `p` | PID filter |
| `l` | Cycle log level (V→D→I→W→E→F) |
| `r` | Toggle regex mode |
#### Actions
| `Enter` | Line detail popup (with JSON formatting) |
| `y` | Copy line to clipboard |
| `m` | Toggle bookmark |
| `[` / `]` | Jump to prev/next bookmark |
| `F` | Fold/unfold stack trace |
| `w` | Toggle soft wrap |
| `x` | Toggle compact mode |
| `Space` | Pause / resume |
| `c` | Clear all entries |
| `s` | Save logs |
| `S` | Save As… (file browser) |
| `q` / `Esc` | Close logcat |
#### Save Dialog
| `Enter` | Save to typed path |
| `S` | Save As… (open file browser) |
| `Tab` | Cycle format: TXT all → TXT filtered → JSON all → JSON filtered |
| `Esc` | Cancel |
#### File Browser (Save As…)
| `↑`/`↓` | Navigate |
| `Enter` / `l` | Open directory / select file |
| `h` / `←` / `Backspace` | Go to parent |
| `Shift+S` | Save Here (into current directory) |
| `/` | Incremental search |
| `n` | Create new folder |
| `.` | Toggle hidden files |
| `s` | Cycle sort mode |
| `Esc` | Back to path input |
## Architecture 🏗️
DroidTUI follows an **Elm-like architecture** with clear separation of concerns:
```
┌── Model ──────────────────────┐
│ app state, menu, logcat, │
│ device status, theme │
├── Message ────────────────────┤
│ all possible state changes │
├── Update ─────────────────────┤
│ message → state transitions │
├── View ───────────────────────┤
│ model → terminal rendering │
├── Event ──────────────────────┤
│ keyboard, tick → messages │
└───────────────────────────────┘
```
### Project Structure
```
droidtui/
├── src/
│ ├── main.rs # Entry point + CLI query mode
│ ├── app.rs # Event loop, key → message mapping
│ ├── model.rs # All application state
│ ├── view.rs # UI rendering (ratatui)
│ ├── update.rs # State transitions
│ ├── message.rs # Message enum
│ ├── event.rs # Async event handling
│ ├── menu.rs # Command menu widget
│ ├── adb.rs # ADB client abstraction
│ ├── fastboot.rs # Fastboot command support
│ ├── logcat.rs # Logcat viewer (streaming, parsing, filters, stats)
│ ├── theme.rs # Theme system (12 presets, selector)
│ ├── effects.rs # Visual effects (TachyonFX)
│ └── lib.rs # Library exports
├── scripts/
│ ├── logcat/ # Nushell recipe scripts
│ ├── bump_version.nu
│ └── release_prepare.nu
├── tests/
│ └── adb_integration_tests.rs
├── examples/
└── Cargo.toml
```
## Dependencies 📦
| `ratatui` | Terminal UI framework |
| `crossterm` | Cross-platform terminal I/O |
| `adb_client` | Pure-Rust ADB protocol client |
| `tokio` | Async runtime |
| `tachyonfx` | Visual effects & animations |
| `regex` | Regex search in logcat |
| `serde` + `serde_json` | JSON serialization for logcat export |
| `tui-file-explorer` | File browser widget (save dialog) |
| `color-eyre` | Error handling |
## Development 🛠️
```bash
cargo test # Run all 209 tests
cargo clippy --all-targets --all-features -- -D warnings # Lint
cargo fmt --check # Format check
just release patch # Bump, test, tag, push
```
### Adding New ADB Commands
1. Add a variant to `AdbCommand` in `src/adb.rs`
2. Implement the handler in `AdbManager::execute`
3. Add a menu entry in `src/menu.rs` via `build_entries()`
4. Tests in `tests/adb_integration_tests.rs`
## Contributing 🤝
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing`)
3. Run `cargo fmt && cargo clippy --all-targets --all-features -- -D warnings && cargo test`
4. Commit and push
5. Open a Pull Request
## License 📄
MIT — Copyright (c) Sorin Albu-Irimies
## Acknowledgments 🙏
- [Ratatui](https://ratatui.rs) — TUI framework
- [adb_client](https://github.com/nicoulaj/adb_client) — Pure-Rust ADB client
- [TachyonFX](https://github.com/junkdog/tachyonfx) — Visual effects
- [tui-file-explorer](https://github.com/sorinirimies/tui-file-explorer) — File browser widget
---
**Made with ❤️ and ☕ for Android developers** · *Powered by Rust 🦀*