loadtoagent 1.0.0

package/README.ko.md

@@ -0,0 +1,175 @@
+<div align="center">
+
+# LoadToAgent
+
+### 일하는 모든 AI를 한곳에서 보는 로컬 작업 지휘실
+
+Claude, Codex, Gemini, Grok 세션을 모니터링하고, 메인 AI와 도움 AI의 관계를 따라가며, 토큰 사용량을 확인하고, 연결된 터미널로 바로 일을 전달하세요. 대화 기록은 외부로 업로드하지 않습니다.
+
+[![Desktop CI](https://github.com/minjund/LodeToAgent/actions/workflows/desktop-ci.yml/badge.svg)](https://github.com/minjund/LodeToAgent/actions/workflows/desktop-ci.yml)
+[![npm version](https://img.shields.io/npm/v/loadtoagent?logo=npm&color=CB3837)](https://www.npmjs.com/package/loadtoagent)
+[![GitHub Release](https://img.shields.io/github/v/release/minjund/LodeToAgent?display_name=tag&sort=semver)](https://github.com/minjund/LodeToAgent/releases/latest)
+![macOS](https://img.shields.io/badge/macOS-지원-111827?logo=apple)
+![Windows](https://img.shields.io/badge/Windows-지원-111827?logo=windows11)
+![Local first](https://img.shields.io/badge/데이터-로컬--퍼스트-35d69f)
+
+[English](README.md) | [简体中文](README.zh-CN.md) | **한국어**
+
+[**Windows·macOS 프로그램 다운로드**](https://github.com/minjund/LodeToAgent/releases/latest) · [**npm으로 설치**](https://www.npmjs.com/package/loadtoagent)
+
+</div>
+
+<div align="center">
+  <img src="docs/assets/loadtoagent-demo.gif" alt="AI 작업과 도움 AI, 대화, 토큰 사용량을 차례로 보여주는 LoadToAgent 데모" width="960" />
+</div>
+
+> AI 대화 기록은 내 컴퓨터에 그대로 남습니다. LoadToAgent는 이미 사용 중인 AI 도구가 만든 로컬 세션 파일을 직접 읽습니다.
+
+## 설치와 실행
+
+npm을 사용하거나, 바로 실행할 수 있는 프로그램 파일을 내려받을 수 있습니다. 어느 방식이든 Git으로 저장소를 받을 필요는 없습니다.
+
+### 방법 1: npm
+
+LoadToAgent는 npm에 [`loadtoagent`](https://www.npmjs.com/package/loadtoagent)로 공개되어 있습니다. 전역 설치한 뒤 `loadtoagent` 명령으로 데스크톱 앱을 여세요.
+
+```bash
+npm install -g loadtoagent
+loadtoagent
+```
+
+npm 방식은 바탕 화면이나 응용 프로그램 바로가기를 만들지 않습니다. 앱을 열 때마다 터미널에서 `loadtoagent`를 실행하세요. 설치 직후 명령을 찾지 못하면 터미널을 한 번 닫았다가 다시 여세요.
+
+```bash
+# 업데이트
+npm install -g loadtoagent@latest
+
+# 삭제
+npm uninstall -g loadtoagent
+```
+
+### 방법 2: 프로그램 파일 직접 다운로드
+
+[최신 GitHub Release](https://github.com/minjund/LodeToAgent/releases/latest)에서 내 컴퓨터에 맞는 파일을 내려받으세요. 이 방식은 Node.js가 필요하지 않습니다.
+
+| 운영체제 | 받을 파일 | 실행 방법 |
+|---|---|---|
+| Windows 10/11 (x64) | `LoadToAgent-Setup-<version>.exe` | 권장 설치본입니다. 처음 설치하거나 앱 안에서 업데이트할 때 사용하세요. |
+| Windows 10/11 (x64) | `LoadToAgent-<version>-portable.exe` | 받은 파일을 더블클릭하세요. 설치 과정이 없는 포터블 실행 파일입니다. |
+| Apple Silicon Mac | `LoadToAgent-<version>-arm64.dmg` | DMG를 열고 LoadToAgent를 응용 프로그램 폴더로 옮긴 뒤 응용 프로그램에서 실행하세요. |
+| Intel Mac | `LoadToAgent-<version>-x64.dmg` | DMG를 열고 LoadToAgent를 응용 프로그램 폴더로 옮긴 뒤 응용 프로그램에서 실행하세요. |
+
+현재 배포 파일에는 코드 서명이 없어 Windows SmartScreen 또는 macOS Gatekeeper가 알 수 없는 개발자 경고를 표시할 수 있습니다. 이 저장소의 공식 Releases 페이지에서 받은 파일일 때만 계속하세요. macOS에서는 LoadToAgent를 Control-클릭하고 **열기**를 선택합니다. Windows에서는 **추가 정보 → 실행**을 선택합니다.
+
+### 앱에서 업데이트
+
+LoadToAgent는 시작할 때 현재 패키지 버전과 GitHub의 최신 정식 Release 태그를 비교합니다. 더 높은 버전이 있으면 화면 위쪽과 **설정 → 프로그램 업데이트**에 안내가 나타납니다. 업데이트 파일 받기를 누르면 운영체제와 CPU에 맞는 파일을 다운로드하고, GitHub가 제공한 파일 크기와 SHA-256을 검증한 뒤 설치 파일을 열 수 있습니다. Windows는 Setup EXE, macOS는 DMG가 우선 선택됩니다. npm 설치본은 위의 `npm install -g loadtoagent@latest` 명령으로 갱신할 수도 있습니다.
+
+### 필요한 환경
+
+- macOS 또는 Windows
+- npm으로 설치할 때만 Node.js 18 이상
+- Claude Code, Codex CLI, Gemini CLI, Grok CLI 중 하나 이상 설치 및 로그인
+- tmux 작업 지도를 사용할 때만 tmux 필요
+
+## 처음 10분 사용법
+
+1. **홈**에서 `새 AI 작업`을 누르고 할 일과 작업 폴더를 고릅니다. 설치된 AI가 없으면 화면의 공식 설치 안내를 먼저 따르세요.
+2. **진행 중**에서 초록 상태의 AI를 확인합니다. 도움 AI를 함께 쓰는 작업은 접힌 `상세 흐름 보기`에서 펼칠 수 있습니다.
+3. **내 확인 필요**에 숫자가 생기면 답변이나 선택이 필요한 작업부터 처리합니다.
+4. 작업 카드를 열어 **대화·진행 과정·사용량**을 확인하고, 연결된 작업은 **세션 터미널**에서 이어서 입력합니다.
+
+홈의 `10분 시작 가이드`도 같은 네 단계를 직접 눌러 연습하게 해 줍니다. 완료 상태는 이 컴퓨터에 저장되며 언제든 다시 펼칠 수 있습니다.
+
+## 한눈에 볼 수 있는 것
+
+| 화면 | 확인할 수 있는 내용 |
+|---|---|
+| AI 작업 지도 | Claude, Codex, Gemini, Grok별 실시간 작업 |
+| 연결 관계 | 사용자 요청, 선택한 메인 AI, 직접 나눠 맡긴 도움 AI |
+| 작업 상세 | 대화, 도구 호출, 진행 과정, 모델, 작업 폴더, 상태 |
+| 토큰 | 입력·출력·캐시·추론·전체 사용량과 보고된 컨텍스트 점유율 |
+| 세션 터미널 | 선택한 AI의 이전 대화와 기존 PTY·tmux 화면을 나란히 보며 같은 세션에 이어서 입력 |
+| tmux 작업 | macOS 또는 Windows WSL의 세션 → 창 → 패널 → AI 프로세스 관계 |
+
+LoadToAgent는 `직접 입력 가능`, `브리지 연결 후 입력 가능`, `원래 앱에서 계속해야 하는 보기 전용`, `종료된 세션`을 구분합니다. 임의의 외부 창에 키 입력을 보내지 않습니다.
+
+## 연결된 터미널 사용
+
+LoadToAgent 앱을 열어 둔 뒤 인증된 로컬 브리지로 AI CLI를 시작합니다.
+
+```bash
+loadtoagent run claude
+loadtoagent run codex
+loadtoagent run gemini
+loadtoagent run grok
+```
+
+`--` 뒤의 값은 각 AI CLI 옵션으로 그대로 전달됩니다.
+
+```bash
+loadtoagent run claude -- --model claude-sonnet-4-6
+```
+
+이제 외부 터미널과 LoadToAgent 대시보드가 같은 LoadToAgent 전용 PTY를 조작합니다. AI 카드에서 `터미널에서 열기`를 누르면 새 셸을 만들지 않고 정확히 연결된 기존 터미널을 열며, 왼쪽에는 해당 세션의 이전 대화가 계속 표시됩니다. 터미널 탭을 바꿔도 PTY 출력은 지워지지 않고, 최신 대화 기록도 자동으로 갱신됩니다. 다른 곳에서 임의로 시작한 세션은 계속 볼 수 있지만, 원래 앱이 지원하는 연결 방식이 없으면 보기 전용으로 유지됩니다.
+
+## 로컬 퍼스트와 보안
+
+- 세션 파일은 사용자 프로필에서 직접 읽습니다.
+- API 키 파일은 읽거나 표시하지 않으며 인증은 각 AI CLI가 처리합니다.
+- 터미널 브리지는 사용자별 토큰과 로컬 named pipe 또는 Unix domain socket을 사용합니다.
+- 터미널·tmux 동작 전에 격리된 화면에서 온 요청인지 확인하고 대상과 입력 형식을 검증합니다.
+- 작업 폴더 수정 권한을 켜면 선택한 AI가 해당 폴더를 변경할 수 있으므로 신뢰하는 저장소에서만 사용하세요.
+
+화면 공유 전에는 표시되는 대화 내용을 확인하세요. AI 대화와 도구 입력에 민감한 프로젝트 정보가 포함될 수 있습니다.
+
+## 로컬 개발
+
+```bash
+npm install
+npm start
+npm test
+```
+
+추가 검사와 배포 파일 빌드:
+
+```bash
+npm run test:terminal
+npm run test:bridge
+npm run test:tmux -- macOS
+npm run test:visual
+npm run dist:mac
+npm run dist:win
+```
+
+`dist:mac`은 Apple Silicon·Intel용 DMG/ZIP을 만들고, `dist:win`은 Windows Setup과 포터블 실행 파일을 만듭니다. 실제 macOS 배포에는 관리자의 Apple 서명·notarization 인증 정보가 필요합니다.
+
+## 지원하는 세션 소스
+
+| AI | 기존 세션 | 새 작업 스트림 | 도움 AI 연결 |
+|---|---|---|---|
+| Claude | Claude Code 로컬 JSONL 대화 기록 | 구조화 headless 출력 | transcript의 subagent 기록 |
+| Codex | Codex 로컬 rollout JSONL | `codex exec --json` | `thread_spawn` 부모 정보 |
+| Gemini | Gemini 로컬 chat JSON/JSONL | 구조화 스트리밍 출력 | 제공되는 경우 부모 ID |
+| Grok | Grok 로컬 session JSON/JSONL | 구조화 스트리밍 출력 | 제공되는 경우 부모 ID |
+
+AI별 이벤트 매핑과 컨텍스트 계산 원칙은 [Provider Contracts](docs/PROVIDER-CONTRACTS.md)에 정리되어 있습니다.
+
+## 릴리스
+
+`v*` 형식의 Git 태그를 원격 저장소에 푸시하면 전체 테스트를 실행하고, 출처 증명이 포함된 npm 패키지를 발행하며, macOS·Windows 배포 파일이 첨부된 GitHub Release를 자동 생성합니다. `package.json` 버전과 태그는 반드시 같아야 합니다.
+
+```bash
+npm version patch --no-git-tag-version
+git add package.json package-lock.json
+VERSION=$(node -p 'require("./package.json").version')
+git commit -m "release: v$VERSION"
+git tag "v$VERSION"
+git push origin HEAD --follow-tags
+```
+
+---
+
+<div align="center">
+  여러 AI를 동시에 쓰면서도 각각 무엇을 하는지 정확히 알고 싶은 사람을 위해 만들었습니다.
+</div>

package/README.md

@@ -0,0 +1,175 @@
+<div align="center">
+
+# LoadToAgent
+
+### One local command center for every AI agent at work.
+
+Monitor Claude, Codex, Gemini, and Grok sessions, follow parent–subagent relationships, inspect token usage, and send work back to a connected terminal—without uploading your transcripts.
+
+[![Desktop CI](https://github.com/minjund/LodeToAgent/actions/workflows/desktop-ci.yml/badge.svg)](https://github.com/minjund/LodeToAgent/actions/workflows/desktop-ci.yml)
+[![npm version](https://img.shields.io/npm/v/loadtoagent?logo=npm&color=CB3837)](https://www.npmjs.com/package/loadtoagent)
+[![GitHub Release](https://img.shields.io/github/v/release/minjund/LodeToAgent?display_name=tag&sort=semver)](https://github.com/minjund/LodeToAgent/releases/latest)
+![macOS](https://img.shields.io/badge/macOS-supported-111827?logo=apple)
+![Windows](https://img.shields.io/badge/Windows-supported-111827?logo=windows11)
+![Local first](https://img.shields.io/badge/data-local--first-35d69f)
+
+**English** | [简体中文](README.zh-CN.md) | [한국어](README.ko.md)
+
+[**Download for Windows / macOS**](https://github.com/minjund/LodeToAgent/releases/latest) · [**Install with npm**](https://www.npmjs.com/package/loadtoagent)
+
+</div>
+
+<div align="center">
+  <img src="docs/assets/loadtoagent-demo.gif" alt="LoadToAgent dashboard demo showing an AI task, its subagents, conversation, and token usage" width="960" />
+</div>
+
+> Your agent transcripts stay on your computer. LoadToAgent reads the local session files created by the AI tools you already use.
+
+## Install and run
+
+Choose npm if you already use Node.js, or download a ready-to-run desktop file. Neither option requires a Git checkout.
+
+### Option 1: npm
+
+LoadToAgent is published on npm as [`loadtoagent`](https://www.npmjs.com/package/loadtoagent). Install it globally, then run the command to open the desktop dashboard:
+
+```bash
+npm install -g loadtoagent
+loadtoagent
+```
+
+The npm method does not create a desktop shortcut. Run `loadtoagent` whenever you want to open the app. If your terminal cannot find the command immediately after installation, close and reopen the terminal once.
+
+```bash
+# Update
+npm install -g loadtoagent@latest
+
+# Remove
+npm uninstall -g loadtoagent
+```
+
+### Option 2: desktop download
+
+Open the [latest GitHub Release](https://github.com/minjund/LodeToAgent/releases/latest) and download the file for your computer. Node.js is not required for these files.
+
+| System | Download | Start the app |
+|---|---|---|
+| Windows 10/11 (x64) | `LoadToAgent-Setup-<version>.exe` | Recommended installer for first-time setup and in-app updates. |
+| Windows 10/11 (x64) | `LoadToAgent-<version>-portable.exe` | Double-click the downloaded file. It is portable and does not run an installer. |
+| Apple silicon Mac | `LoadToAgent-<version>-arm64.dmg` | Open the DMG, drag LoadToAgent into Applications, then open it from Applications. |
+| Intel Mac | `LoadToAgent-<version>-x64.dmg` | Open the DMG, drag LoadToAgent into Applications, then open it from Applications. |
+
+The current desktop files are not code-signed. Windows SmartScreen or macOS Gatekeeper may show an unknown-developer warning. Continue only when the file came from this repository's official Releases page. On macOS, Control-click LoadToAgent and choose **Open**. On Windows, choose **More info → Run anyway**.
+
+### Update from the app
+
+On startup, LoadToAgent compares its package version with the newest stable GitHub Release tag. When a newer version exists, a notice appears at the top of the app and under **Settings → Program update**. The app downloads the matching Windows Setup EXE or macOS DMG, verifies its GitHub file size and SHA-256 digest when available, and then lets you open the installer. npm installations can also use `npm install -g loadtoagent@latest`.
+
+### Requirements
+
+- macOS or Windows
+- Node.js 18 or newer only when installing through npm
+- At least one installed and authenticated CLI: Claude Code, Codex CLI, Gemini CLI, or Grok CLI
+- tmux only if you want the optional tmux workspace map
+
+## Your first 10 minutes
+
+1. From **Home**, choose `New AI task`, describe the outcome, and select a workspace. If no supported AI is installed, follow the official setup link shown in the app first.
+2. Open **In progress** to see every AI with a green status. Expand `View detailed flow` only when you need the subagent breakdown.
+3. When **Needs your input** shows a count, handle those replies or decisions first.
+4. Open any task to inspect its **conversation, progress, and usage**, then continue a connected task from **Session terminal**.
+
+The `10-minute start guide` on Home lets you practice the same four steps. Progress is saved on this computer and the guide can be reopened at any time.
+
+## What LoadToAgent shows
+
+| View | What you get |
+|---|---|
+| Agent map | Live work grouped by Claude, Codex, Gemini, and Grok |
+| Relationship view | The request origin, selected agent, and every directly delegated subagent |
+| Session detail | Conversation, tool activity, lifecycle events, model, workspace, and status |
+| Token view | Input, output, cached, reasoning, total, and reported context-window usage |
+| Session terminal | The selected AI's prior conversation beside its existing PTY or tmux pane, with input continuing in that exact session |
+| tmux workspace | Session → window → pane → AI process topology on macOS or Windows through WSL |
+
+LoadToAgent distinguishes between a terminal it can control, a session that needs a bridge connection, a read-only session that must continue in its original app, and an ended session. It never types into an arbitrary external window.
+
+## Use a connected terminal
+
+Keep the LoadToAgent app open, then start an AI CLI through its authenticated local bridge:
+
+```bash
+loadtoagent run claude
+loadtoagent run codex
+loadtoagent run gemini
+loadtoagent run grok
+```
+
+Arguments after `--` are passed to the provider CLI:
+
+```bash
+loadtoagent run claude -- --model claude-sonnet-4-6
+```
+
+The external terminal and LoadToAgent dashboard control the same LoadToAgent-owned PTY. Opening a terminal from an AI card reuses the exact connected terminal instead of creating a new shell, keeps its PTY output intact across UI navigation, and shows that session's prior conversation in a live side rail. Sessions started arbitrarily elsewhere remain visible but read-only unless the original app exposes a supported handoff.
+
+## Local-first by design
+
+- Session files are read directly from your user profile.
+- API key files are not read or displayed; authentication stays with each provider CLI.
+- The terminal bridge uses a per-user token and a local named pipe or Unix domain socket.
+- Renderer requests are isolated and validated before terminal or tmux actions run.
+- Enabling workspace writes gives the selected AI permission to modify that folder, so use it only with repositories you trust.
+
+Review the visible transcript before sharing your screen: agent conversations and tool inputs can contain sensitive project information.
+
+## Develop locally
+
+```bash
+npm install
+npm start
+npm test
+```
+
+Additional checks and distributable builds:
+
+```bash
+npm run test:terminal
+npm run test:bridge
+npm run test:tmux -- macOS
+npm run test:visual
+npm run dist:mac
+npm run dist:win
+```
+
+`dist:mac` produces Apple Silicon and Intel DMG/ZIP files. `dist:win` produces Windows Setup and portable executables. Production macOS releases still require the maintainer's Apple signing and notarization credentials.
+
+## Supported session sources
+
+| Provider | Existing sessions | New work stream | Subagents |
+|---|---|---|---|
+| Claude | Claude Code local JSONL transcripts | Structured headless output | Transcript subagent records |
+| Codex | Codex local rollout JSONL files | `codex exec --json` | `thread_spawn` parent metadata |
+| Gemini | Gemini local chat JSON/JSONL files | Structured streaming output | Parent IDs when reported |
+| Grok | Grok local session JSON/JSONL files | Structured streaming output | Parent IDs when reported |
+
+Provider event mappings and context-window rules are documented in [Provider Contracts](docs/PROVIDER-CONTRACTS.md).
+
+## Release
+
+Pushing a `v*` Git tag runs the full test suite, publishes the npm package with provenance, builds the macOS and Windows artifacts, and creates the GitHub Release with those files attached. The `package.json` version and tag must match.
+
+```bash
+npm version patch --no-git-tag-version
+git add package.json package-lock.json
+VERSION=$(node -p 'require("./package.json").version')
+git commit -m "release: v$VERSION"
+git tag "v$VERSION"
+git push origin HEAD --follow-tags
+```
+
+---
+
+<div align="center">
+  Built for people who run more than one AI agent—and still want to know exactly what each one is doing.
+</div>

package/README.zh-CN.md

@@ -0,0 +1,175 @@
+<div align="center">
+
+# LoadToAgent
+
+### 在一个本地控制台中查看所有正在工作的 AI
+
+监控 Claude、Codex、Gemini 和 Grok 会话，追踪主代理与子代理的关系，检查 Token 用量，并把任务直接发送到已连接的终端。对话记录不会上传到外部服务。
+
+[![Desktop CI](https://github.com/minjund/LodeToAgent/actions/workflows/desktop-ci.yml/badge.svg)](https://github.com/minjund/LodeToAgent/actions/workflows/desktop-ci.yml)
+[![npm version](https://img.shields.io/npm/v/loadtoagent?logo=npm&color=CB3837)](https://www.npmjs.com/package/loadtoagent)
+[![GitHub Release](https://img.shields.io/github/v/release/minjund/LodeToAgent?display_name=tag&sort=semver)](https://github.com/minjund/LodeToAgent/releases/latest)
+![macOS](https://img.shields.io/badge/macOS-支持-111827?logo=apple)
+![Windows](https://img.shields.io/badge/Windows-支持-111827?logo=windows11)
+![Local first](https://img.shields.io/badge/数据-本地优先-35d69f)
+
+[English](README.md) | **简体中文** | [한국어](README.ko.md)
+
+[**下载 Windows / macOS 程序**](https://github.com/minjund/LodeToAgent/releases/latest) · [**通过 npm 安装**](https://www.npmjs.com/package/loadtoagent)
+
+</div>
+
+<div align="center">
+  <img src="docs/assets/loadtoagent-demo.gif" alt="LoadToAgent 演示：查看 AI 任务、子代理、对话和 Token 用量" width="960" />
+</div>
+
+> AI 会话记录始终保留在你的电脑上。LoadToAgent 只读取你已经在使用的 AI 工具生成的本地会话文件。
+
+## 安装与运行
+
+你可以使用 npm，也可以直接下载可运行的桌面文件。两种方式都不需要通过 Git 下载仓库。
+
+### 方式一：npm
+
+LoadToAgent 已在 npm 以 [`loadtoagent`](https://www.npmjs.com/package/loadtoagent) 发布。全局安装后，运行 `loadtoagent` 命令即可打开桌面应用：
+
+```bash
+npm install -g loadtoagent
+loadtoagent
+```
+
+npm 安装方式不会创建桌面或应用程序快捷方式。每次需要打开应用时，请在终端运行 `loadtoagent`。如果安装后终端暂时找不到该命令，请关闭并重新打开终端。
+
+```bash
+# 更新
+npm install -g loadtoagent@latest
+
+# 卸载
+npm uninstall -g loadtoagent
+```
+
+### 方式二：直接下载桌面文件
+
+打开[最新 GitHub Release](https://github.com/minjund/LodeToAgent/releases/latest)，下载与你的电脑匹配的文件。此方式不需要 Node.js。
+
+| 系统 | 下载文件 | 启动方式 |
+|---|---|---|
+| Windows 10/11 (x64) | `LoadToAgent-Setup-<version>.exe` | 推荐用于首次安装和应用内更新。 |
+| Windows 10/11 (x64) | `LoadToAgent-<version>-portable.exe` | 双击下载的文件。它是无需安装的便携版程序。 |
+| Apple 芯片 Mac | `LoadToAgent-<version>-arm64.dmg` | 打开 DMG，将 LoadToAgent 拖入“应用程序”，然后从“应用程序”中打开。 |
+| Intel Mac | `LoadToAgent-<version>-x64.dmg` | 打开 DMG，将 LoadToAgent 拖入“应用程序”，然后从“应用程序”中打开。 |
+
+当前桌面文件尚未进行代码签名，因此 Windows SmartScreen 或 macOS Gatekeeper 可能显示未知开发者警告。只有在文件来自本仓库官方 Releases 页面时才继续。macOS 用户可按住 Control 键点按 LoadToAgent，然后选择**打开**；Windows 用户可选择**更多信息 → 仍要运行**。
+
+### 在应用内更新
+
+LoadToAgent 启动时会比较当前包版本与最新的稳定 GitHub Release 标签。如果存在更高版本，应用顶部以及**设置 → 程序更新**中会显示提示。应用会下载对应的 Windows Setup EXE 或 macOS DMG，并校验 GitHub 提供的文件大小和 SHA-256（如有），随后可直接打开安装文件。npm 安装仍可使用 `npm install -g loadtoagent@latest` 更新。
+
+### 环境要求
+
+- macOS 或 Windows
+- 仅通过 npm 安装时需要 Node.js 18 或更高版本
+- 至少安装并登录一个 CLI：Claude Code、Codex CLI、Gemini CLI 或 Grok CLI
+- 只有使用 tmux 工作区地图时才需要安装 tmux
+
+## 前 10 分钟上手
+
+1. 在**首页**点击`新建 AI 任务`，填写目标并选择工作目录。如果尚未安装受支持的 AI，请先按照应用中显示的官方安装链接完成设置。
+2. 打开**进行中**，查看所有绿色状态的 AI。只有需要检查子代理分工时，再展开`查看详细流程`。
+3. 当**需要你确认**出现数字时，优先处理需要回复或选择的任务。
+4. 打开任务卡片，查看**对话、进度和用量**；对于已连接的任务，可在**会话终端**中继续输入。
+
+首页的`10 分钟入门指南`可以带你实际完成同样的四个步骤。进度只保存在本机，并且可随时重新打开。
+
+## LoadToAgent 可以展示什么
+
+| 视图 | 内容 |
+|---|---|
+| 代理地图 | 按 Claude、Codex、Gemini 和 Grok 分组的实时任务 |
+| 关系视图 | 用户请求、当前代理以及它直接委派的所有子代理 |
+| 会话详情 | 对话、工具活动、执行过程、模型、工作目录和状态 |
+| Token 视图 | 输入、输出、缓存、推理、总量和已报告的上下文占用率 |
+| 终端控制 | 本地 Shell，以及向 LoadToAgent 自有终端安全发送命令 |
+| tmux 工作区 | macOS 或 Windows WSL 中的会话 → 窗口 → 面板 → AI 进程拓扑 |
+
+LoadToAgent 会区分可直接控制的终端、需要桥接的会话、必须回到原应用继续的只读会话以及已结束会话。它不会向任意外部窗口注入键盘输入。
+
+## 使用已连接的终端
+
+保持 LoadToAgent 桌面应用运行，然后通过经过认证的本地桥接启动 AI CLI：
+
+```bash
+loadtoagent run claude
+loadtoagent run codex
+loadtoagent run gemini
+loadtoagent run grok
+```
+
+`--` 后面的参数会原样传给对应的 AI CLI：
+
+```bash
+loadtoagent run claude -- --model claude-sonnet-4-6
+```
+
+外部终端与 LoadToAgent 仪表盘会共同控制同一个 LoadToAgent 专用 PTY。在其他地方启动的现有会话仍然可见，但除非原应用提供受支持的交接方式，否则会保持只读。
+
+## 本地优先与安全
+
+- 会话文件直接从用户目录读取。
+- 不读取或显示 API Key 文件；认证由各个 AI CLI 自行处理。
+- 终端桥接使用每位用户独立的令牌，以及本地 named pipe 或 Unix domain socket。
+- 执行终端或 tmux 操作前，会验证请求来源、目标和输入格式。
+- 开启工作目录写入权限后，所选 AI 可以修改该目录，因此请只在可信仓库中启用。
+
+共享屏幕前请检查当前显示的会话内容，因为 AI 对话和工具输入可能包含敏感的项目信息。
+
+## 本地开发
+
+```bash
+npm install
+npm start
+npm test
+```
+
+其他检查与发行构建：
+
+```bash
+npm run test:terminal
+npm run test:bridge
+npm run test:tmux -- macOS
+npm run test:visual
+npm run dist:mac
+npm run dist:win
+```
+
+`dist:mac` 会生成 Apple Silicon 和 Intel 的 DMG/ZIP 文件；`dist:win` 会生成 Windows Setup 和便携版可执行文件。正式的 macOS 发行仍需要维护者提供 Apple 签名与 notarization 凭据。
+
+## 支持的会话来源
+
+| AI | 现有会话 | 新任务流 | 子代理 |
+|---|---|---|---|
+| Claude | Claude Code 本地 JSONL 记录 | 结构化 headless 输出 | transcript 中的 subagent 记录 |
+| Codex | Codex 本地 rollout JSONL | `codex exec --json` | `thread_spawn` 父级元数据 |
+| Gemini | Gemini 本地 chat JSON/JSONL | 结构化流式输出 | 工具提供时使用父级 ID |
+| Grok | Grok 本地 session JSON/JSONL | 结构化流式输出 | 工具提供时使用父级 ID |
+
+各提供商的事件映射与上下文计算规则记录在 [Provider Contracts](docs/PROVIDER-CONTRACTS.md) 中。
+
+## 发布
+
+将 `v*` Git 标签推送到远程仓库后，工作流会运行完整测试、发布带来源证明的 npm 包、构建 macOS 与 Windows 文件，并自动创建附带这些文件的 GitHub Release。`package.json` 版本必须与标签一致。
+
+```bash
+npm version patch --no-git-tag-version
+git add package.json package-lock.json
+VERSION=$(node -p 'require("./package.json").version')
+git commit -m "release: v$VERSION"
+git tag "v$VERSION"
+git push origin HEAD --follow-tags
+```
+
+---
+
+<div align="center">
+  为同时运行多个 AI、又想准确了解每一个 AI 在做什么的人而设计。
+</div>