@kairyou/agent-tools 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agent-tools Developers and Contributors
+
+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

@@ -0,0 +1,156 @@
+# Agent Tools
+
+Reusable skills and runtime integrations for Codex, Claude Code, and opencode. This repository keeps each capability in predictable locations so projects can opt into only what they need.
+
+[中文](README.zh-CN.md)
+
+## Directory Layout
+
+```text
+agent-tools/
+├── .claude-plugin/    # Claude Code/plugin ecosystem manifest.
+├── .codex-plugin/     # Codex plugin manifest.
+├── hooks/             # Shared and agent-specific hook integrations.
+├── plugins/           # Runtime plugins loaded by supported agents.
+├── scripts/           # Install, sync, validation, and maintenance scripts.
+├── skills/            # Reusable Agent Skills for CLI discovery and plugin manifests.
+│   └── workflow/      # Workflow-oriented skills.
+│       ├── at-commit/   # Conventional Commit message skill.
+│       ├── at-review/   # Review changes for bugs and regressions.
+│       └── at-simplify/ # Reduce complexity and duplication in changes.
+├── statusline/        # Statusline scripts/templates, grouped by agent.
+│   └── claude/        # Claude command-backed statusLine script + example config.
+└── lib/               # Shared implementation used by hooks, statuslines, and installers.
+```
+
+## Current Skills
+
+- `at-commit`: Generate a Conventional Commits message from staged changes and wait for user confirmation before committing.
+- `at-review`: Review changes for correctness bugs, regressions, convention violations, and high-value cleanup findings.
+- `at-simplify`: Refactor changes to reduce duplication, lower complexity, and improve code quality.
+
+## Usage
+
+List available skills:
+
+```bash
+npx -y skills@latest add kairyou/agent-tools --list
+```
+
+Install skills globally:
+
+```bash
+npx -y skills@latest add kairyou/agent-tools --skill at-commit -g -y
+npx -y skills@latest add kairyou/agent-tools --skill at-review -g -y
+npx -y skills@latest add kairyou/agent-tools --skill at-simplify -g -y
+```
+
+Pass multiple skills after `--skill`, for example `--skill at-commit at-review at-simplify`.
+
+## Runtime integrations
+
+### Claude Code
+
+#### Statusline
+
+```bash
+# Install or update
+npx -y github:kairyou/agent-tools statusline -a claude
+
+# Preview or uninstall
+npx -y github:kairyou/agent-tools statusline -a claude --dry-run
+npx -y github:kairyou/agent-tools statusline -a claude --uninstall
+```
+
+The installer writes `statusLine` to `~/.claude/settings.json`. The default
+output is:
+
+```text
+⎇ main | Opus 4.8 | 5h 7% ⟳2h54m | w 41% ⟳3d1h
+```
+
+Here `5h` and `w` are Claude's rolling usage windows; `⟳` is the reset countdown.
+When a compatible API relay is active, the statusline also appends provider usage.
+
+To choose what appears, edit `statusline.fields` in
+`~/.agent-tools/config.jsonc`. The installer may add new default keys on update;
+it preserves top-of-file comments and existing values.
+
+### Codex
+
+#### Provider usage hook
+
+```bash
+# Install or update
+npx -y github:kairyou/agent-tools usage -a codex
+
+# Preview or uninstall
+npx -y github:kairyou/agent-tools usage -a codex --dry-run
+npx -y github:kairyou/agent-tools usage -a codex --uninstall
+```
+
+The installer adds the hook to `UserPromptSubmit` and `Stop` in
+`~/.codex/hooks.json`. After installation, run `/hooks` inside Codex and approve
+the agent-tools usage hooks.
+
+Output examples:
+
+```text
+# Subscription / plan quota.
+warning: API | D $0.0/$100 | W $0.0/$300 | Exp 07-08
+
+# Wallet balance.
+warning: API | balance $362 | today $61.7 | 30d $566
+```
+
+Fields: `D/W/M` are daily/weekly/monthly spend against plan limits; `Exp` is
+the plan expiry; `balance` is wallet credit; `today` and `30d` are API spend.
+
+### OpenCode
+
+#### Provider usage plugin
+
+```bash
+# Install or update
+npx -y github:kairyou/agent-tools usage -a opencode
+
+# Preview or uninstall
+npx -y github:kairyou/agent-tools usage -a opencode --dry-run
+npx -y github:kairyou/agent-tools usage -a opencode --uninstall
+```
+
+The installer adds global server and TUI plugins. After the active session
+becomes idle, the server plugin refreshes usage and shows it as a toast. The TUI
+plugin also registers `/at-usage` for the latest cached value. Restart opencode
+after installing or updating the plugins.
+
+Toast example:
+
+```text
+Provider usage
+balance $244 | today $45.8 | 30d $604
+```
+
+### Supported gateways
+
+Balance, quota, and plan usage queries support compatible Sub2API-like,
+NewAPI/OneAPI/OneHub/DoneHub/Veloera/AnyRouter-like, and OpenRouter gateways.
+
+## FAQ
+
+### Why does a global install report `Failed to install 1`?
+
+`PromptScript does not support global skill installation` means that the
+PromptScript agent does not support global installation. It does not affect
+other agents and can be ignored. See [`skills` issue #1352](https://github.com/vercel-labs/skills/issues/1352).
+
+## Notes
+
+- `skills/` contains reusable `SKILL.md` capabilities.
+- `hooks/` keeps stable ownership directories for shared and agent-specific integrations.
+- `plugins/` contains runtime plugin implementations such as opencode usage.
+- `statusline/claude/` contains the command-backed Claude statusLine script.
+- `lib/` contains shared implementation such as API usage query logic.
+- The installer marks and removes only the config entries it owns.
+
+Run local checks with `npm test`.

package/README.zh-CN.md

@@ -0,0 +1,149 @@
+# Agent Tools
+
+面向 Codex、Claude Code 与 opencode 的可复用 skills 和 runtime integrations. 本仓库把各项能力放在可预期的位置; 不同项目可以只安装自己需要的部分.
+
+## 目录结构
+
+```text
+agent-tools/
+├── .claude-plugin/    # Claude Code/plugin 生态的 manifest。
+├── .codex-plugin/     # Codex plugin manifest。
+├── hooks/             # 通用 hook 逻辑及各 agent 的适配实现。
+├── plugins/           # 由各 agent 加载的 runtime plugins.
+├── scripts/           # 安装、同步、校验和仓库维护脚本。
+├── skills/            # 可复用 Agent Skills，供 CLI 扫描和 plugin manifest 声明。
+│   └── workflow/      # 工作流类 skills。
+│       ├── at-commit/   # 生成 Conventional Commits message.
+│       ├── at-review/   # 审查改动中的 bug 与回归风险.
+│       └── at-simplify/ # 减少改动中的冗余和复杂度.
+├── statusline/        # Statusline 配置片段/模板，按 agent 分组。
+│   └── claude/        # Claude command-backed statusLine 脚本和示例配置。
+└── lib/               # hooks、statusline、installer 复用的共享实现。
+```
+
+## 当前 Skills
+
+- `at-commit`: 根据暂存区改动生成 Conventional Commits message, 并在提交前等待用户确认.
+- `at-review`: 审查改动中的正确性 bug, 回归风险, 约定违规和高价值清理项.
+- `at-simplify`: 重构改动, 减少冗余, 降低复杂度, 提升代码质量.
+
+## 使用方式
+
+查看可用 skills：
+
+```bash
+npx -y skills@latest add kairyou/agent-tools --list
+```
+
+全局安装 skill：
+
+```bash
+npx -y skills@latest add kairyou/agent-tools --skill at-commit -g -y
+npx -y skills@latest add kairyou/agent-tools --skill at-review -g -y
+npx -y skills@latest add kairyou/agent-tools --skill at-simplify -g -y
+```
+
+多个 skill 可以跟在 `--skill` 后面，例如 `--skill at-commit at-review at-simplify`。
+
+## Runtime integrations
+
+### Claude Code
+
+#### Statusline
+
+```bash
+# 安装或更新
+npx -y github:kairyou/agent-tools statusline -a claude
+
+# 预览或卸载
+npx -y github:kairyou/agent-tools statusline -a claude --dry-run
+npx -y github:kairyou/agent-tools statusline -a claude --uninstall
+```
+
+安装器会把 `statusLine` 写入 `~/.claude/settings.json`. 默认显示:
+
+```text
+⎇ main | Opus 4.8 | 5h 7% ⟳2h54m | w 41% ⟳3d1h
+```
+
+其中 `5h` / `w` 是 Claude 的滚动用量窗口, `⟳` 后面是重置倒计时.
+使用兼容的 API 中转时, statusline 还会追加 provider usage.
+
+如需控制显示项, 修改 `~/.agent-tools/config.jsonc` 里的
+`statusline.fields`. 安装器更新时可能补充新的默认键; 文件顶部注释和已有值会保留.
+
+### Codex
+
+#### Provider usage hook
+
+```bash
+# 安装或更新
+npx -y github:kairyou/agent-tools usage -a codex
+
+# 预览或卸载
+npx -y github:kairyou/agent-tools usage -a codex --dry-run
+npx -y github:kairyou/agent-tools usage -a codex --uninstall
+```
+
+安装器会把 hook 添加到 `~/.codex/hooks.json` 的 `UserPromptSubmit` 和
+`Stop`. 安装后, 在 Codex 里运行 `/hooks` 并批准 agent-tools usage hooks.
+
+显示效果示例:
+
+```text
+# 订阅/套餐额度.
+warning: API | D $0.0/$100 | W $0.0/$300 | Exp 07-08
+
+# 钱包余额.
+warning: API | balance $362 | today $61.7 | 30d $566
+```
+
+字段含义: `D/W/M` 是日/周/月套餐消耗与上限, `Exp` 是套餐到期日,
+`balance` 是钱包余额, `today` / `30d` 是今日与近 30 天 API 消耗.
+
+### OpenCode
+
+#### Provider usage plugin
+
+```bash
+# 安装或更新
+npx -y github:kairyou/agent-tools usage -a opencode
+
+# 预览或卸载
+npx -y github:kairyou/agent-tools usage -a opencode --dry-run
+npx -y github:kairyou/agent-tools usage -a opencode --uninstall
+```
+
+安装器会添加全局 server plugin 和 TUI plugin. 当前 session 进入 idle 后, server
+plugin 会刷新 usage 并通过 toast 显示; TUI plugin 还会注册 `/at-usage`, 用于查看最新
+缓存值. 安装或更新 plugin 后需要重启 opencode.
+
+显示效果示例:
+
+```text
+Provider usage
+balance $244 | today $45.8 | 30d $604
+```
+
+### 支持的网关
+
+余额, 额度和套餐用量查询支持兼容 Sub2API-like,
+NewAPI/OneAPI/OneHub/DoneHub/Veloera/AnyRouter-like 与 OpenRouter 的网关.
+
+## FAQ
+
+### 全局安装为什么显示 `Failed to install 1`？
+
+`PromptScript does not support global skill installation` 表示 PromptScript Agent 不支持全局
+安装，不影响其他 Agent，可忽略。参见 [`skills` issue #1352](https://github.com/vercel-labs/skills/issues/1352)。
+
+## 说明
+
+- `skills/` 放可复用的 `SKILL.md` 能力。项目可以只安装自己需要的 skills。
+- `hooks/` 按通用逻辑和各 agent 适配实现划分目录。
+- `plugins/` 放 opencode usage 等 runtime plugin 实现.
+- `statusline/claude/` 放 Claude command-backed statusLine 脚本。
+- `lib/` 放 API usage 查询等共享实现。
+- 安装器只标记并移除自己写入的配置项。
+
+本地检查运行 `npm test`。

package/config.default.jsonc

@@ -0,0 +1,23 @@
+// agent-tools config.
+// statusline.fields controls both visibility and order.
+// Remove a field to hide it; move a field to reorder it.
+// Available statusline fields: branch, model, fiveHour, week, context, directory.
+// providerUsage is used by the shared usage runtime.
+{
+  "statusline": {
+    "fields": ["branch", "model", "fiveHour", "week"],
+    "separator": " | ",
+    "symbols": {
+      "branch": "⎇",
+      "reset": "⟳",
+      "empty": "–",
+      "fiveHour": "5h",
+      "week": "w",
+      "context": "ctx"
+    }
+  },
+  "providerUsage": {
+    "days": 30,
+    "debug": false
+  }
+}

package/hooks/claude/.gitkeep

@@ -0,0 +1 @@
+

package/hooks/codex/.gitkeep

@@ -0,0 +1 @@
+

package/hooks/codex/usage-hook.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+// Codex usage hook wrapper.
+// Keeps hook failures actionable: infrastructure errors are logged and the hook
+// still exits 0 with a short message instead of surfacing only "exit code 1".
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const AGENT_TOOLS_HOME = process.env.AGENT_TOOLS_HOME || path.resolve(SCRIPT_DIR, "..", "..");
+const USAGE_SCRIPT = path.join(AGENT_TOOLS_HOME, "lib", "usage.mjs");
+const LOG_PATH = path.join(AGENT_TOOLS_HOME, "logs", "usage-hook.log");
+const TIMEOUT_MS = Number(process.env.AGENT_TOOLS_USAGE_HOOK_TIMEOUT_MS || 4500);
+const MAX_LOG_BYTES = Number(process.env.AGENT_TOOLS_USAGE_HOOK_LOG_BYTES || 256 * 1024);
+const KEEP_LOG_BYTES = 128 * 1024;
+
+function hookOut(message) {
+  const payload = { continue: true };
+  if (message) payload.systemMessage = message;
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+}
+
+function preview(text) {
+  return String(text || "").replace(/\s+/g, " ").trim().slice(0, 500);
+}
+
+function logFailure(event) {
+  try {
+    fs.mkdirSync(path.dirname(LOG_PATH), { recursive: true });
+    rotateLogIfNeeded();
+    fs.appendFileSync(
+      LOG_PATH,
+      `${JSON.stringify({ at: new Date().toISOString(), ...event })}\n`
+    );
+  } catch {
+    // Nothing else to do; the wrapper must fail open.
+  }
+}
+
+function rotateLogIfNeeded() {
+  const maxBytes = Number.isFinite(MAX_LOG_BYTES) && MAX_LOG_BYTES > 0 ? MAX_LOG_BYTES : 256 * 1024;
+  if (!fs.existsSync(LOG_PATH)) return;
+  const stat = fs.statSync(LOG_PATH);
+  if (stat.size <= maxBytes) return;
+  const keepBytes = Math.min(KEEP_LOG_BYTES, Math.floor(maxBytes / 2));
+  const fd = fs.openSync(LOG_PATH, "r");
+  try {
+    const buffer = Buffer.alloc(keepBytes);
+    fs.readSync(fd, buffer, 0, keepBytes, Math.max(0, stat.size - keepBytes));
+    fs.writeFileSync(
+      LOG_PATH,
+      `${JSON.stringify({ at: new Date().toISOString(), reason: "log rotated", previousBytes: stat.size })}\n` +
+        buffer.toString("utf8").replace(/^[^\n]*\n?/, "")
+    );
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function failureMessage() {
+  return `API usage hook failed; see ${LOG_PATH.replace(/\\/g, "/")}`;
+}
+
+function parseHookJson(stdout) {
+  const text = stdout.trim();
+  if (!text) return { continue: true };
+  return JSON.parse(text);
+}
+
+async function runUsageScript() {
+  if (!fs.existsSync(USAGE_SCRIPT)) {
+    logFailure({ reason: "missing usage script", usageScript: USAGE_SCRIPT });
+    hookOut(failureMessage());
+    return;
+  }
+
+  const result = await new Promise((resolve) => {
+    const child = spawn(process.execPath, [USAGE_SCRIPT, "hook", "--agent", "codex"], {
+      cwd: process.cwd(),
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true,
+    });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const timeout = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill();
+      resolve({ status: null, signal: "timeout", stdout, stderr });
+    }, Number.isFinite(TIMEOUT_MS) && TIMEOUT_MS > 0 ? TIMEOUT_MS : 4500);
+
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      resolve({ status: null, error, stdout, stderr });
+    });
+    child.on("exit", (status, signal) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      resolve({ status, signal, stdout, stderr });
+    });
+  });
+
+  if (result.status !== 0) {
+    logFailure({
+      reason: "usage script exited non-zero",
+      status: result.status,
+      signal: result.signal || "",
+      error: result.error?.message || "",
+      stdout: preview(result.stdout),
+      stderr: preview(result.stderr),
+      usageScript: USAGE_SCRIPT,
+      node: process.version,
+      platform: `${process.platform} ${os.release()}`,
+    });
+    hookOut(failureMessage());
+    return;
+  }
+
+  try {
+    const payload = parseHookJson(result.stdout);
+    process.stdout.write(`${JSON.stringify(payload)}\n`);
+  } catch (error) {
+    logFailure({
+      reason: "usage script returned invalid hook JSON",
+      error: error.message,
+      stdout: preview(result.stdout),
+      stderr: preview(result.stderr),
+      usageScript: USAGE_SCRIPT,
+    });
+    hookOut(failureMessage());
+  }
+}
+
+try {
+  await runUsageScript();
+} catch (error) {
+  logFailure({
+    reason: "wrapper exception",
+    error: error?.stack || error?.message || String(error),
+    usageScript: USAGE_SCRIPT,
+  });
+  hookOut(failureMessage());
+}

package/hooks/common/.gitkeep

@@ -0,0 +1 @@
+

package/hooks/opencode/.gitkeep

@@ -0,0 +1 @@
+