Ganger

🚀 Ganger - GitHub Ranger

Ganger是一款受ranger启发的基于终端的GitHub starred仓库文件管理器。借助类似Vim的快捷键和多面板界面，你可以轻松地对GitHub starred仓库进行导航、组织和管理。

🚀 快速开始

认证

Ganger支持两种认证方式：

1. OAuth设备流程（推荐）：

   ganger auth
   # 按照提示通过浏览器进行认证
   

2. 个人访问令牌：

   export GITHUB_TOKEN=your_token_here
   ganger tui
   

MCP服务器

MCP服务器允许大语言模型（LLM）代理编排GitHub starred仓库管理：

# 启动MCP服务器
ganger mcp

# 服务器提供的工具如下：
# - list_starred_repos
# - create_virtual_folder
# - move_repo_to_folder
# - star_repository
# - get_repo_details

✨ 主要特性

• 双界面：TUI（文本用户界面）和MCP（模型上下文协议）服务器
• 米勒列视图：三列的ranger风格视图（文件夹 | 仓库 | 预览）
• 虚拟文件夹：使用基于标签的虚拟文件夹来组织starred仓库
• 自动分类：根据语言、主题和活跃度自动对仓库进行分类
• Vim快捷键：支持hjkl导航、可视模式、剪切/复制/粘贴操作
• 智能缓存：使用SQLite缓存，支持离线浏览并减少API调用
• 双重认证：支持OAuth设备流程或个人访问令牌认证

📦 安装指南

前提条件

• Python 3.10 或更高版本
• Poetry（用于依赖管理）
• GitHub账户

使用Poetry安装

# 克隆仓库
git clone https://github.com/synapticsage/ganger.git
cd ganger

# 安装依赖
poetry install

# 激活虚拟环境
poetry shell

# 运行认证设置
ganger auth

# 启动TUI
ganger tui

# 或者启动MCP服务器
ganger mcp

📚 详细文档

配置

配置文件：~/.config/ganger/config.yaml

有关默认设置和可用选项，请参阅config/config.yaml。

项目状态

阶段1（进行中）：核心基础

• [x] 项目结构和依赖
• [ ] 核心数据模型
• [ ] GitHub认证（OAuth + PAT）
• [ ] GitHub API客户端（REST + GraphQL）
• [ ] SQLite缓存
• [ ] 支持自动分类的文件夹管理器
• [ ] MCP服务器
• [ ] 配置系统
• [ ] 单元测试

阶段2（计划中）：TUI界面 阶段3（计划中）：高级功能

架构

Ganger采用了清晰的服务层架构，TUI和MCP界面均可使用该架构：

ganger/
├── core/          # 业务逻辑（共享）
│   ├── models.py
│   ├── github_client.py
│   ├── cache.py
│   ├── auth.py
│   └── folder_manager.py
├── mcp/           # MCP服务器界面
│   ├── server.py
│   └── tools.py
└── tui/           # TUI界面（阶段2）
    └── app.py

开发

运行测试

poetry run pytest

代码质量

# 格式化代码
poetry run black src/ tests/

# 代码检查
poetry run ruff check src/ tests/

# 类型检查
poetry run mypy src/

📄 许可证

本项目采用MIT许可证。

致谢

• 灵感来源于 ranger 文件管理器
• 架构模式借鉴自 yanger
• 基于 Textual 和 MCP 构建