Metadata-Version: 2.4
Name: tui-file-explorer
Version: 0.1.0
Summary: Terminal file explorer with hierarchical directory browsing — designed for CMUX and AI agent workflows
Author: John1Q84
License-Expression: MIT
Project-URL: Homepage, https://github.com/John1Q84/tui-explorer
Project-URL: Repository, https://github.com/John1Q84/tui-explorer
Project-URL: Issues, https://github.com/John1Q84/tui-explorer/issues
Keywords: tui,file-explorer,terminal,textual,cmux,ai-agent
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: Utilities
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual>=8.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# TUI File Explorer

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

<img src="docs/assets/screenshot-main.svg" alt="TUI File Explorer — main view">

## Why?

[CMUX](https://cmux.com), [Claude Code](https://claude.ai/claude-code) 같은 터미널 기반 AI 코딩 에이전트 환경에서 작업할 때, Agent가 생성하거나 수정한 파일들을 **터미널을 벗어나지 않고** 즉시 확인할 수 있어야 합니다.

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

**TUI File Explorer**는 [CMUX](https://cmux.com)의 별도 탭이나 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 패널 숨김 상태

<img src="docs/assets/screenshot-no-detail.svg" alt="TUI File Explorer — detail hidden">

### 숨김 파일 표시

<img src="docs/assets/screenshot-hidden.svg" alt="TUI File Explorer — hidden files shown">

## Installation

### pip (PyPI에서 설치)

```bash
pip install tui-file-explorer
```

### 소스에서 설치

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

### 개발 모드

```bash
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

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

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

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

### CMUX와 함께 사용하기

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

```bash
# CMUX Tab 1: AI Agent 실행
claude

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

### tmux와 함께 사용하기

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

```bash
# 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](https://textual.textualize.io/) 8.x (TUI Framework)
- [ruff](https://docs.astral.sh/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

```bash
# 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
