tui-file-explorer 0.1.0

Terminal file explorer with hierarchical directory browsing — designed for CMUX and AI agent workflows

TUI File Explorer

Terminal 환경에서 GUI 파일 탐색기와 같은 사용 경험을 제공하는 TUI(Text User Interface) 앱입니다. Python Textual 프레임워크를 활용하여 hierarchical directory 구조를 직관적으로 탐색할 수 있습니다.

Why?

CMUX, Claude Code 같은 터미널 기반 AI 코딩 에이전트 환경에서 작업할 때, Agent가 생성하거나 수정한 파일들을 터미널을 벗어나지 않고 즉시 확인할 수 있어야 합니다.

기존 워크플로우의 문제:

• AI Agent가 파일을 생성/수정하면 ls, tree, cat 등을 반복적으로 입력해야 함
• GUI 파일 탐색기를 열면 터미널 컨텍스트에서 벗어남
• watch tree는 상세 정보가 부족하고 인터랙션이 불가

TUI File Explorer는 CMUX의 별도 탭이나 tmux pane에 띄워두고, Agent 작업 중 생성되는 파일 구조를 실시간으로 탐색할 수 있도록 설계되었습니다. 디렉토리 트리를 계층적으로 보여주고, 파일 선택 시 크기/권한/날짜 등 메타데이터를 바로 확인할 수 있습니다.

┌─────────────────────────────────────────────────────────┐
│ CMUX                                                    │
├──────────────────────────┬──────────────────────────────┤
│ Tab 1: Claude Code       │  Tab 2: TUI File Explorer    │
│                          │  ├── src/                    │
│ > 새 모듈을 생성합니다... │  │   ├── main.py  ← new!    │
│   Writing main.py...     │  │   └── utils.py            │
│   Writing test_main.py.. │  ├── tests/                  │
│                          │  │   └── test_main.py ← new! │
│                          │  └── pyproject.toml           │
└──────────────────────────┴──────────────────────────────┘

Features

• Directory Tree — 계층적 디렉토리 구조를 트리 뷰로 탐색
• File Detail — 파일/디렉토리 선택 시 메타데이터 (경로, 크기, 권한, 소유자, 날짜) 표시
• Hidden Files Toggle — 숨김 파일(.으로 시작) 표시/숨김 전환
• Detail Panel Toggle — 하단 상세 정보 패널 표시/숨김 전환
• Keyboard Navigation — 마우스 없이 키보드만으로 완전한 탐색 가능
• CMUX / tmux Friendly — 별도 탭이나 pane에서 가볍게 실행, AI Agent 작업과 병행

Detail 패널 숨김 상태

숨김 파일 표시

Installation

pip (PyPI에서 설치)

pip install tui-file-explorer

소스에서 설치

git clone https://github.com/your-repo/tui-file-explorer.git
cd tui-file-explorer
pip install .

개발 모드

git clone https://github.com/your-repo/tui-file-explorer.git
cd tui-file-explorer
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Usage

# 현재 디렉토리 탐색
tui-explorer

# 특정 경로 탐색
tui-explorer /path/to/directory

# python -m 으로 실행
python -m tui_explorer.main /path/to/directory

CMUX와 함께 사용하기

CMUX는 여러 AI 코딩 에이전트를 관리하기 위한 Ghostty 기반 네이티브 macOS 터미널입니다. 세로 탭 사이드바로 여러 에이전트 세션을 전환할 수 있어, 한 탭에서 AI Agent를 실행하고 다른 탭에서 TUI File Explorer를 띄워두면 파일 변경 사항을 즉시 확인할 수 있습니다.

# CMUX Tab 1: AI Agent 실행
claude

# CMUX Tab 2: 프로젝트 디렉토리 모니터링
tui-explorer /path/to/project
# Agent가 파일을 생성/수정하면 'r' 키로 새로고침하여 확인

tmux와 함께 사용하기

tmux에서도 동일하게 활용할 수 있습니다:

# tmux 세션에서 수직 분할 후 오른쪽에 띄워둠
tmux split-window -h 'tui-explorer /path/to/project'

Key Bindings

Key	Action
↑ ↓	트리 탐색
Enter	디렉토리 펼치기/접기
d	Detail 패널 표시/숨김
h	숨김 파일 표시/숨김
r	트리 새로고침
Escape	Command Palette 닫기
q	종료

Tech Stack

• Python 3.14+
• Textual 8.x (TUI Framework)
• ruff (Lint/Format)

Project Structure

tui-file-explorer/
├── pyproject.toml
├── code/
│   └── tui_explorer/          # Python package
│       ├── main.py            # App entry point
│       ├── utils.py           # Formatting utilities
│       ├── style.tcss         # TUI stylesheet
│       ├── widgets/
│       │   ├── directory_tree.py
│       │   └── file_detail.py
│       └── tests/
│           ├── test_utils.py
│           ├── test_widgets.py
│           └── test_app.py
└── docs/
    ├── specs/
    └── plans/

Development

# Run tests
python -m pytest code/tui_explorer/tests/ -v

# Lint
ruff check code/tui_explorer/
ruff format --check code/tui_explorer/

# Build distribution
python -m build

License

MIT