Technical Briefing: browsr

The Problem

browsr is a terminal-based file explorer (TUI) that supports local and remote filesystems including GitHub, SSH, AWS S3, GCS, and Azure Blob Storage. It enables keyboard/mouse-driven navigation with syntax highlighting, JSON formatting, image rendering, and data table conversion. The codebase contains 64 files (31 Python, 12 YAML, 4 Markdown) with a Python-centric stack built on Textual.

What This Does

browsr functions as a cross-platform filesystem navigator. Execution starts at browsr/cli.py:69, which mounts the Browsr screen through TextualAppContext (entry point called from 1 place). The core workflow routes through browsr/browsr.py (mount_screen, action_download_file, action_copy_file_path) and browsr/widgets/windows.py (38 functions, 9 classes, handles file I/O). File operations read/write via browsr/utils.py, which also makes one outbound network call (likely GitHub API). The widget graph shows browsr/widgets/code_browser as a high-instability hub (Ca 1, Ce 10, instability 0.91) — many imports, few importers — suggesting ripple effects when that module changes.

How It Is Wired

Execution flows: cli.py → TextualAppContext → Browsr mount → widget composition (code_browser, windows, files). Key hubs:

  • browsr/base.py — 7 callers, defines TextualAppContext, SortedBindingsScreen
  • browsr/utils.py — 4 callers, reads/writes files, makes network call (_open_pdf_as_image, open_image, get_file_info)
  • browsr/widgets/windows.py — 4 callers, file-to-string/image/json conversions
  • browsr/widgets/code_browser.py — 3 callers, datatable_window, static_window, compose, bind_keys

A single repeated 6-line block exists in browsr/browsr.py and browsr/screens/code_browser.py (duplicated logic). browsr/utils.py opens files without a context manager — open(...) not wrapped in with — handle may leak on error.

How To Use It

Setup:

pipx install "browsr[all]"   # includes remote extras (GitHub, S3, etc.)
# or: pipx install browsr       # minimal install

Configuration: No explicit config file in repo. Remote filesystem access (GitHub, S3, etc.) requires the corresponding extra dependency declared in pyproject.toml. No environment variables or keys are documented in the scanned files.

Running it:

browsr [path]
# or via module: python -m browsr [path]

Entry point: browsr/cli.py:69.

Real-World Use

A user launches browsr from a terminal to navigate a remote GitHub repository or local directory tree. Pressing o opens a file; Ctrl+D downloads it. The code_browser widget renders syntax-highlighted source; windows.py manages split panes and file previews. When a PDF is encountered, utils._open_pdf_as_image triggers the network-dependent image conversion.

Code Health & Issues

Static analysis (4 findings, 0 high / 4 medium / 0 low):

  • [MEDIUM/resource_safety] File opened without context manager — browsr/utils.py — open(...) not wrapped in with; fix: use with open(...) as f:.
  • [MEDIUM/cognitive_load] Deep nesting x2 — browsr/cli.py, .releaserc.js — max indentation depth 6; fix: flatten with early returns/guard clauses.
  • [MEDIUM/clarity] Duplicated code blocks — browsr/browsr.py, browsr/screens/code_browser.py — 2 repeated 6-line blocks; fix: extract shared helper.
  • [MEDIUM/clarity] 3 CI findings from the hygiene audit (separate from the code analysis):
  • [HIGH] Pin third-party GitHub Actions to commit SHAs — .github/workflows — @v1 pins can shift; breakage/leak risk.
  • [HIGH] continue-on-error on correctness-gating steps — .github/workflows/lint.yaml:14 — failing tests report green check.
  • [MEDIUM] Declare least-privilege GITHUB_TOKEN permissions — .github/workflows/lint.yaml — no permissions declared; inherited default allows push/release actions.

The Bottom Line

browsr is a functional TUI file explorer with solid remote-filesystem support and a modular widget architecture. The codebase is manageable at 64 files but carries measurable technical debt: duplicated logic, unguarded file handles, and CI vulnerabilities from unpinned Actions and permissive token defaults. Teams needing a terminal file explorer with remote support can adopt it today, but should pin Action dependencies and address the file-handle leak before production use.