@someonegg/agent-hub 0.0.0-stage → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kngin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+# Agent Hub
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+English | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md)
+
+A local web hub for Codex and Claude Code that pairs readable conversations with live CLI interaction.
+Browse sessions by project, follow responses in near real time, and keep working with
+either runtime from desktop or mobile.
+
+![Agent Hub: create a session, send a prompt, and review an answered User input card](docs/images/ahub-intro.gif)
+
+<details>
+<summary>Mobile screenshots</summary>
+
+<img src="docs/images/ahub-mobile-catalog.png" alt="Mobile project navigation" width="260">
+<img src="docs/images/ahub-mobile-reader.png" alt="Mobile conversation with an answered User input question, options, and selected answer" width="260">
+<img src="docs/images/ahub-mobile-composer.png" alt="Mobile message input with image attachment preview and send controls" width="260">
+
+</details>
+
+## Quick start
+
+Runtime requirements:
+
+- macOS or Linux with Node.js >=22.13 and npm
+- A locally configured Codex or Claude Code CLI
+- tmux for creating, resuming, and interacting with sessions
+
+Hub reads `~/.codex` and `~/.claude` by default. You can use either runtime or both;
+see [Agent configuration](docs/usage.md#multiple-agents) for custom directories.
+
+Try it without a global installation:
+
+```sh
+npx @someonegg/agent-hub@latest
+```
+
+Or install it for regular use:
+
+```sh
+npm install -g @someonegg/agent-hub
+agent-hub
+```
+
+Open <http://127.0.0.1:4173>. Open **Settings → Language** at the bottom of the sidebar to switch between English (the default), 简体中文, and 繁體中文. The choice is saved in this browser. Press `Ctrl-C` to stop the server.
+For agent configuration, ports, and optional page/diff hosting, see [Usage](docs/usage.md).
+
+To upgrade, run `npm install -g @someonegg/agent-hub@latest` again.
+For running from source, see [Development](docs/development.md).
+
+## Features
+
+- Navigate projects, main sessions, and child conversations.
+- Read conversation messages, plans, and user input with Markdown, code, tables, and math.
+- Follow conversation updates while browsing their history.
+- Create sessions with optional worktrees, send input, and preview their terminals.
+- View live sessions, resume exited sessions, stop session execution, and archive or delete history.
+- [Publish static pages and review diffs](docs/usage.md#publish-pages-and-diffs) with optional local hosting.
+- Switch the interface between English, Simplified Chinese, and Traditional Chinese.
+
+## Session interaction
+
+Send prompts and control the live terminal from the session page. Take photos,
+paste images, or drop files, then preview and send.
+See [file uploads](docs/usage.md#file-uploads) for storage, cleanup, and file limits.
+
+<details>
+<summary>Show session interaction screenshot</summary>
+
+<img src="docs/images/ahub-session-interaction.png" alt="Session conversation with answered User input, live terminal preview, controls, message input, and Handoff" width="900">
+
+</details>
+
+Expand **Terminal Preview** to follow the CLI and handle prompts with the on-screen
+controls. See [session interaction](docs/usage.md#send-prompts-and-files) for keyboard
+shortcuts, interruption, and Codex session handoff.
+
+## Command-line management
+
+Use `ahub-cli session` to list, create, resume, inspect, and manage sessions from
+another terminal, or send input to a live session. Add `--json` for structured
+output in scripts and agent workflows.
+See [session CLI usage](docs/usage.md#session-commands) for commands and examples.
+
+For agent-assisted session workflows, use the bundled
+[`ahub-control` skill](skills/ahub-control). Run
+`ahub-cli skill path ahub-control` to locate it. With `npx`, copy the skill
+directory from the temporary cache for lasting use.
+
+## Security
+
+Agent Hub reads local session history and controls connected CLI sessions through
+tmux. The configured CLI handles model access and authentication; Hub does not
+manage API keys or CLI credentials.
+
+The server binds to loopback by default. Interaction and management are enabled
+without application authentication. Before exposing it to a network, add
+authentication, such as the built-in mTLS option, and restrict access. See the
+[security guidance](docs/usage.md#access-from-other-devices).
+
+## Documentation
+
+- [Usage and configuration](docs/usage.md)
+- [Technical reference](docs/technical-reference.md)
+- [Development and screenshots](docs/development.md)
+- [All documentation and architecture decisions](docs/README.md)

package/README.zh-CN.md

@@ -0,0 +1,99 @@
+# Agent Hub
+
+[English](README.md) | 简体中文 | [繁體中文](README.zh-TW.md)
+
+面向 Codex 和 Claude Code 的本地网页中心，将清晰易读的会话记录与实时 CLI 交互结合起来。
+按项目浏览会话、跟进最新回复，并从电脑或手机继续工作。
+
+![创建会话、发送提示并查看已回答的用户输入卡片](docs/images/zh-CN/ahub-intro.gif)
+
+<details>
+<summary>手机截图</summary>
+
+<img src="docs/images/zh-CN/ahub-mobile-catalog.png" alt="手机上的项目导航" width="260">
+<img src="docs/images/zh-CN/ahub-mobile-reader.png" alt="手机上的会话与已回答问题" width="260">
+<img src="docs/images/zh-CN/ahub-mobile-composer.png" alt="手机上的消息输入与图片附件预览" width="260">
+
+</details>
+
+## 快速开始
+
+运行要求：
+
+- macOS 或 Linux，Node.js >=22.13 与 npm
+- 已配置的本地 Codex 或 Claude Code CLI
+- tmux，用于创建、恢复会话和交互
+
+Hub 默认读取 `~/.codex` 和 `~/.claude`，两种运行时可单独或同时使用。
+自定义目录见[多个智能体配置](docs/usage.zh-CN.md#多个智能体)。
+
+无需全局安装即可试用：
+
+```sh
+npx @someonegg/agent-hub@latest
+```
+
+也可以安装后长期使用：
+
+```sh
+npm install -g @someonegg/agent-hub
+agent-hub
+```
+
+打开 <http://127.0.0.1:4173>。按 `Ctrl-C` 停止服务器。
+界面默认英文，在侧边栏底部打开 **Settings → Language → 简体中文 / 繁體中文** 即可切换；选择保存在当前浏览器。
+
+智能体、端口与可选网页／差异托管配置见[使用与配置](docs/usage.zh-CN.md)。
+
+升级时再次执行
+`npm install -g @someonegg/agent-hub@latest`。从源码运行请参阅[开发指南（英文）](docs/development.md)。
+
+## 功能
+
+- 按项目浏览主会话和子会话。
+- 阅读会话消息、计划和用户输入，支持 Markdown、代码、表格和数学公式。
+- 浏览历史记录的同时跟进会话更新。
+- 创建会话，可选 worktree；发送输入并预览终端。
+- 查看运行中的会话、恢复已退出会话、停止会话运行，以及归档或删除历史记录。
+- [发布静态网页和查看代码差异](docs/usage.zh-CN.md#发布网页与差异)，可选启用本地托管。
+- 在英文、简体中文与繁体中文之间切换界面。
+
+## 会话交互
+
+在会话页面发送提示并控制实时终端。可以拍照、粘贴图片或拖放文件，预览后发送。
+上传存储、清理和限制见[文件上传](docs/usage.zh-CN.md#文件上传)。
+
+<details>
+<summary>查看会话交互截图</summary>
+
+<img src="docs/images/zh-CN/ahub-session-interaction.png" alt="会话、已回答问题、终端预览、消息输入与移交绑定" width="900">
+
+</details>
+
+展开**终端预览**跟进 CLI，并通过屏幕按钮处理提示。
+快捷键、中断与 Codex 会话移交详见[与会话交互](docs/usage.zh-CN.md#发送提示与文件)。
+
+## 通过管理 CLI 操作会话
+
+使用 `ahub-cli session` 在另一个终端中列出、创建、恢复、查看和管理会话，或向运行中的会话发送输入。
+添加 `--json` 可输出结构化结果，便于脚本和智能体工作流使用。
+命令与示例见[会话 CLI 使用说明](docs/usage.zh-CN.md#会话命令)。
+
+如需智能体协助管理会话，可使用 npm 包附带的
+[`ahub-control` skill](skills/ahub-control)。运行
+`ahub-cli skill path ahub-control` 查看目录。`npx` 返回缓存路径，长期使用请复制该目录。
+
+## 安全
+
+Agent Hub 读取本地会话记录，通过 tmux 控制已连接的 CLI 会话。
+模型访问与身份认证由所配置的 CLI 负责；Hub 不管理 API 密钥或 CLI 凭据。
+
+服务器默认仅监听回环地址，交互和管理功能没有应用层登录保护。对外开放前，请添加身份认证
+（例如内置 mTLS）并限制访问。参阅[安全说明](docs/usage.zh-CN.md#从其他设备访问)。
+
+## 文档
+
+- [使用与配置](docs/usage.zh-CN.md)
+- [技术参考（英文）](docs/technical-reference.md)
+- [开发与截图（英文）](docs/development.md)
+- [全部文档与架构决策](docs/README.md)

package/README.zh-TW.md

@@ -0,0 +1,99 @@
+# Agent Hub
+
+[English](README.md) | [简体中文](README.zh-CN.md) | 繁體中文
+
+面向 Codex 和 Claude Code 的本地網頁中心，將清晰易讀的工作階段記錄與即時 CLI 互動結合起來。
+按專案瀏覽工作階段、跟進最新回覆，並從電腦或手機繼續工作。
+
+![建立工作階段、傳送提示並檢視已回答的使用者輸入卡片](docs/images/zh-TW/ahub-intro.gif)
+
+<details>
+<summary>手機截圖</summary>
+
+<img src="docs/images/zh-TW/ahub-mobile-catalog.png" alt="手機上的專案導覽" width="260">
+<img src="docs/images/zh-TW/ahub-mobile-reader.png" alt="手機上的工作階段與已回答問題" width="260">
+<img src="docs/images/zh-TW/ahub-mobile-composer.png" alt="手機上的訊息輸入與圖片附件預覽" width="260">
+
+</details>
+
+## 快速開始
+
+執行要求：
+
+- macOS 或 Linux，Node.js >=22.13 與 npm
+- 已設定的本機 Codex 或 Claude Code CLI
+- tmux，用於建立、恢復工作階段和互動
+
+Hub 預設讀取 `~/.codex` 和 `~/.claude`，兩種執行環境可單獨或同時使用。
+自訂目錄見[多個智慧體設定](docs/usage.zh-TW.md#多個智慧體)。
+
+無需全域安裝即可試用：
+
+```sh
+npx @someonegg/agent-hub@latest
+```
+
+也可以安裝後長期使用：
+
+```sh
+npm install -g @someonegg/agent-hub
+agent-hub
+```
+
+開啟 <http://127.0.0.1:4173>。按 `Ctrl-C` 停止伺服器。
+介面預設英文，在側邊欄底部開啟 **Settings → Language → 简体中文 / 繁體中文** 即可切換；選擇儲存在目前瀏覽器。
+
+智慧體、連接埠與可選網頁／差異託管設定見[使用與設定](docs/usage.zh-TW.md)。
+
+升級時再次執行
+`npm install -g @someonegg/agent-hub@latest`。從原始碼執行請參閱[開發指南（英文）](docs/development.md)。
+
+## 功能
+
+- 按專案瀏覽主工作階段和子工作階段。
+- 閱讀工作階段訊息、計畫和使用者輸入，支援 Markdown、程式碼、表格和數學公式。
+- 瀏覽歷史記錄的同時跟進工作階段更新。
+- 建立工作階段，可選 worktree；傳送輸入並預覽終端。
+- 檢視執行中的工作階段、恢復已退出工作階段、停止工作階段執行，以及封存或刪除歷史記錄。
+- [發布靜態網頁和檢視程式碼差異](docs/usage.zh-TW.md#發布網頁與差異)，可選啟用本機託管。
+- 在英文、簡體中文與繁體中文之間切換介面。
+
+## 工作階段互動
+
+在工作階段頁面傳送提示並控制即時終端。可以拍照、貼上圖片或拖放檔案，預覽後傳送。
+上傳儲存、清理和限制見[檔案上傳](docs/usage.zh-TW.md#檔案上傳)。
+
+<details>
+<summary>檢視工作階段互動截圖</summary>
+
+<img src="docs/images/zh-TW/ahub-session-interaction.png" alt="工作階段、已回答問題、終端預覽、訊息輸入與移交繫結" width="900">
+
+</details>
+
+展開**終端預覽**跟進 CLI，並透過螢幕按鈕處理提示。
+快捷鍵、中斷與 Codex 工作階段移交詳見[與工作階段互動](docs/usage.zh-TW.md#傳送提示與檔案)。
+
+## 透過管理 CLI 操作工作階段
+
+使用 `ahub-cli session` 在另一個終端中列出、建立、恢復、檢視和管理工作階段，或向執行中的工作階段傳送輸入。
+新增 `--json` 可輸出結構化結果，方便指令碼和智慧體工作流程使用。
+命令與範例見[工作階段 CLI 使用說明](docs/usage.zh-TW.md#工作階段命令)。
+
+如需智慧體協助管理工作階段，可使用 npm 套件附帶的
+[`ahub-control` skill](skills/ahub-control)。執行
+`ahub-cli skill path ahub-control` 查看目錄。`npx` 回傳快取路徑，長期使用請複製該目錄。
+
+## 安全
+
+Agent Hub 讀取本機工作階段記錄，透過 tmux 控制已連線的 CLI 工作階段。
+模型存取與身分認證由所設定的 CLI 負責；Hub 不管理 API 金鑰或 CLI 認證資料。
+
+伺服器預設僅監聽回送位址，互動和管理功能沒有應用層登入保護。對外開放前，請新增身分認證
+（例如內建 mTLS）並限制存取。參閱[安全說明](docs/usage.zh-TW.md#從其他裝置存取)。
+
+## 文件
+
+- [使用與設定](docs/usage.zh-TW.md)
+- [技術參考（英文）](docs/technical-reference.md)
+- [開發與截圖（英文）](docs/development.md)
+- [全部文件與架構決策](docs/README.md)