RepoAtlas

One place for GitHub context and local reality.

RepoAtlas packages repository cartography into a desktop app: multi-account inventory, local Git discovery, repository-centered Agents/Memory/Skills/MCP/Workflow/Rules/Hooks tabs, local context evidence, sync comparison, report exports, themes, and safe folder opening.

Multi-account

Scan the current GitHub CLI login or multiple account-router aliases in one merged atlas.

Context tabs

Tags repos as Agents, Memory, Skills, MCP, Workflow, Rules, Hooks, or Other while keeping GitHub repositories at the center.

Local context evidence

Scans marker folders and files, attaches matched evidence to repositories, and leaves unlinked contexts in a secondary panel.

Drift signals

Highlights synced, behind, ahead, diverged, dirty, no-upstream, and missing-local states.

First-run guide

Includes in-app GitHub login, visible progress, account modes, scan roots, and refresh errors.

1

下载安装程序

从 GitHub Release 下载 Windows 版本。

点击页面上方 Download Release
选择 `RepoAtlas-vX.Y.Z-windows-x64.exe`
等待下载完成并确认文件完整
如果系统拦截，选择保留来自 GitHub 的文件

2

准备依赖

先让本机具备 GitHub 扫描能力。

安装 Git 与 GitHub CLI
确认 `git --version` 可以运行
确认 `gh --version` 可以运行
空白窗口时安装 WebView2 Runtime

3

完成登录

首次使用只需要认证一次。

打开 RepoAtlas 后点击侧边栏 Login
在默认浏览器完成 GitHub 授权
等待进度条显示 GitHub login complete
已有便携 `gh.exe` 时填写 custom gh path

4

开始扫描

把 GitHub 和本地项目连接起来。

账号框留空可扫描当前 `gh` 登录
多账号时一行填写一个账号或别名
设置本地 scan roots 以匹配文件夹
点击 Refresh 查看进度和仓库结果

1

下载 macOS 包

从 Release 页面下载 macOS artifact。

选择 `RepoAtlas-vX.Y.Z-macos-ARM64.tar.gz`
解压到一个固定目录
保留包内 README.txt
当前 Release 面向 Apple Silicon runner 构建

2

准备命令行工具

macOS 使用系统 WebKit，实时扫描仍依赖 Git 与 GitHub CLI。

安装 Git 与 GitHub CLI
运行 `gh auth login --web` 或在应用内 Login
确认 `gh auth status` 显示已登录
准备需要扫描的本地项目目录

3

启动 RepoAtlas

从 Terminal 运行包内二进制。

进入解压目录
执行 `./RepoAtlas`
如被 Gatekeeper 拦截，在系统设置中允许打开
首次打开后完成新手教程

4

配置扫描

把账号与本地目录交给扫描台。

多账号一行一个：例如 Harzva、saihao
scan roots 填写本地代码目录
需要最新分支状态时开启 Fetch
点击 Refresh 查看匹配结果

1

克隆源码

适合开发者或暂未覆盖的系统。

`git clone https://github.com/Harzva/RepoAtlas.git`
`cd RepoAtlas`
安装稳定版 Rust 工具链
确认平台具备 Wry/WebView 依赖

2

运行开发版

本地启动桌面应用并嵌入 dashboard。

执行 `cargo run`
等待 Rust 编译完成
应用会打开本地 WebView 窗口
扫描需要本机 Git 和 GitHub CLI

3

执行检查

提交前先做基本回归。

`cargo fmt --all -- --check`
`cargo check --locked`
`cargo test --locked`
`node --check public/app.js`

4

构建发布包

Release 仍推荐交给 GitHub Actions。

本地可执行 `cargo build --release`
Windows/macOS artifact 由 tag workflow 产出
推送 `v*` 标签会创建 GitHub Release
不要提交本地 inventory 或凭证

Future / TODO

RepoAtlas as a future Codex plugin surface.

Today RepoAtlas focuses on local-GitHub coordination from a desktop app. When Codex exposes richer plugin UI extension points similar to VS Code sidebars, RepoAtlas can become a Codex-native navigation layer for repositories, issue context, pull requests, releases, local folders, and conversation-linked project memory.

Bring repository cards, local paths, Issues, Pull Requests, and Releases into a Codex sidebar.
Connect repo context with AI conversation history so project work can be resumed faster.
Keep destructive actions on GitHub or local Git tools until the plugin workflow is mature.
Use RepoAtlas desktop as the proving ground for multi-account and local-online synchronization.

Install

Windows exe and macOS tar.gz from GitHub Actions.

Download the release asset, run it, and sign in with GitHub CLI for live rescans. Enter multiple accounts on separate lines when your work spans personal, product, and agent-tooling accounts.

gh auth login
git --version
RepoAtlas-vX.Y.Z-windows-x64.exe
RepoAtlas-vX.Y.Z-macos-ARM64.tar.gz