📂 lsoph

TUI that lists open files for a given process — a live, colour-coded view of every file a program (and its children) touches, updated as it happens.

Usage:

uvx lsoph -p <pid>          # attach to a running process (and its descendants)
uvx lsoph -c <command ...>  # launch a command and monitor it
uvx lsoph -b <backend> ...  # force a specific backend

Backends

lsoph auto-detects which backends are usable on your machine (the required tool must be installed, or a C compiler present) and picks the best available. There are two kinds:

• Tracers stream real file events — open, read, write, close, stat, rename, unlink — from an external tracing tool. Accurate and complete, but usually need privilege.
• Pollers snapshot each process's open files on an interval. Portable and low-privilege, but they miss short-lived files and can't see actual I/O.

🐧 Linux · 🍏 macOS · 😈 BSD · ☀️ Solaris · 🪟 Windows

* Under the default kernel.yama.ptrace_scope=1, strace can only attach to your own descendants. To attach to an arbitrary PID, run with sudo, lower the scope, or setcap cap_sys_ptrace+ep $(command -v strace). Run mode (-c) works without any of that.

The strace, preload, psutil and lsof backends are exercised on Linux. The BSD/macOS tracers (truss, dtruss, ktrace, fs_usage) are built and tested against their documented output formats but still want a smoke-test on real hardware — reports welcome. etw is built against the documented Kernel-File event layouts and smoke-tested under Wine (where the session APIs work but events don't flow); it wants validation on real Windows.

Future?

• Native Linux backends — fanotify, or eBPF (bpftrace / BCC)
• osquery — one polling backend, three OSes
• gdb / lldb debugger-scripting backends (cross-platform, slow)
• DYLD_INSERT_LIBRARIES shim for macOS (the preload sibling)

Note: inotify is intentionally absent — it watches paths, not processes, and doesn't report which PID caused an event. fanotify is the right Linux API.

• 🎬 demo
• 🏠 home
• 🐱 github
• 🐍 pypi