@kairyou/agent-tools 0.1.0

package/skills/workflow/at-review/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: at-review
+description: "Review code changes for bugs, regressions, convention violations, and high-value cleanup opportunities. Use for diffs, commit ranges, PRs, paths, staged changes, or working-tree changes."
+---
+
+# Code Review
+
+`high effort → 3+5 angles × 6 candidates → 1-vote verify (recall-biased) → ≤10 findings`
+
+You are reviewing for **recall** at high effort: catch every real bug a careful reviewer would catch in one sitting. At this level, catching real bugs matters more than avoiding false positives. Err on the side of surfacing.
+
+## Phase 0 — Gather the diff
+
+Run `git diff "@{upstream}...HEAD"` (or `git diff main...HEAD` / `git diff HEAD~1` if there's no upstream) to get the unified diff under review. If there are uncommitted changes, or the range diff is empty, also run `git diff HEAD` and include the working-tree changes in scope — the review often runs before the commit. If a PR number, branch name, or file path was passed as an argument, review that target instead. Treat this diff as the review scope.
+
+## Phase 1 — Find candidates (3 correctness angles + 3 cleanup angles + 1 altitude angle + 1 conventions angle, up to 6 each)
+
+Run **8 independent finder angles** using multi-agent capabilities. Each surfaces **up to 6 candidate findings** with `file`, `line`, a one-line `summary`, and a concrete `failure_scenario`.
+
+### Angle A — line-by-line diff scan
+
+Read every hunk in the diff, line by line. Then Read the enclosing function for each hunk — bugs in unchanged lines of a touched function are in scope (the PR re-exposes or fails to fix them). For every line ask: what input, state, timing, or platform makes this line wrong? Look for inverted/wrong conditions, off-by-one, null/undefined deref, missing `await`, falsy-zero checks, wrong-variable copy-paste, error swallowed in catch, unescaped regex metachars.
+
+### Angle B — removed-behavior auditor
+
+For every line the diff DELETES or replaces, name the invariant or behavior it enforced, then search the new code for where that invariant is re-established. If you can't find it, that's a candidate: a removed guard, a dropped error path, a narrowed validation, a deleted test that was covering a real case.
+
+### Angle C — cross-file tracer
+
+For each function the diff changes, find its callers (Grep for the symbol) and check whether the change breaks any call site: a new precondition, a changed return shape, a new exception, a timing/ordering dependency. Also check callees: does a parallel change in the same PR make a call unsafe?
+
+### Reuse
+
+The angles above hunt for bugs; this one and the next two hunt for cleanup in the changed code. Flag new code that re-implements something the codebase already has — Grep shared/utility modules and files adjacent to the change, and name the existing helper to call instead.
+
+### Simplification
+
+Flag unnecessary complexity the diff adds: redundant or derivable state, copy-paste with slight variation, deep nesting, dead code left behind. Name the simpler form that does the same job.
+
+### Efficiency
+
+Flag wasted work the diff introduces: redundant computation or repeated I/O, independent operations run sequentially, blocking work added to startup or hot paths. Also flag long-lived objects built from closures or captured environments — they keep the entire enclosing scope alive for the object's lifetime (a memory leak when that scope holds large values); prefer a class/struct that copies only the fields it needs. Name the cheaper alternative.
+
+### Altitude
+
+Check that each change is implemented at the right depth, not as a fragile bandaid. Special cases layered on shared infrastructure are a sign the fix isn't deep enough — prefer generalizing the underlying mechanism over adding special cases.
+
+### Conventions (project instructions)
+
+Find the instruction files that govern the changed code: user-level instructions for the current agent, the repo-root AGENTS.md or CLAUDE.md, plus any AGENTS.md, CLAUDE.md, or CLAUDE.local.md in a directory that is an ancestor of a changed file (a directory's instruction file only applies to files at or below it). Read each one that exists, then check the diff for clear violations of the rules they state.
+
+Only flag a violation when you can quote the exact rule and the exact line that breaks it — no style preferences, no vague "spirit of the doc" inferences. In the finding, name the instruction file path and quote the rule so the report can cite it. If no instruction file applies, return nothing for this angle.
+
+Cleanup, altitude, and conventions candidates use the same `file`/`line`/`summary` shape; in `failure_scenario`, state the concrete cost (what is duplicated, wasted, harder to maintain, or which project instruction is broken) instead of a crash. Correctness bugs always outrank cleanup, altitude, and conventions findings when the output cap forces a cut.
+
+Pass every candidate with a nameable failure scenario through — finders that silently drop half-believed candidates bypass the verify step and are the dominant cause of misses.
+
+## Phase 2 — Verify (1-vote, recall-biased)
+
+Dedup near-duplicates (same defect, same location, same reason → keep one). For each remaining candidate, run **one verifier** using multi-agent capabilities: give it the diff, the relevant file(s), and the candidate; it returns exactly one of **CONFIRMED / PLAUSIBLE / REFUTED**.
+
+**PLAUSIBLE by default** — do not refute a candidate for being "speculative" or "depends on runtime state" when the state is realistic: concurrency races, nil/undefined on a rare-but-reachable path (error handler, cold cache, missing optional field), falsy-zero treated as missing, off-by-one on a boundary the code does not exclude, retry storms / partial failures, regex/allowlist that lost an anchor. These are PLAUSIBLE.
+
+**REFUTED** only when constructible from the code: factually wrong (quote the actual line); provably impossible (type/constant/invariant — show it); already handled in this diff (cite the guard); or pure style with no observable effect.
+
+Keep **CONFIRMED and PLAUSIBLE**. Drop REFUTED.
+
+## Output
+
+Return findings as a JSON array of at most 10 objects:
+
+```json
+[
+  {
+    "file": "path/to/file.ext",
+    "line": 123,
+    "summary": "one-sentence statement of the bug",
+    "failure_scenario": "concrete inputs/state → wrong output/crash"
+  }
+]
+```
+
+Ranked most-severe first. If more than 10 survive, keep the 10 most severe. If nothing survives verification, return `[]`.
+
+## Applying fixes
+
+If the user asked to fix, apply the findings to the working tree instead of stopping at the report: fix each one directly — correctness bugs and reuse/simplification/efficiency cleanups alike. Skip any finding whose fix would change intended behavior, require changes well outside the reviewed diff, or that you judge to be a false positive — note the skip rather than arguing with it. Finish with a brief summary of what was fixed and what was skipped.
+
+If the user did NOT ask to fix, stop at the report.

package/skills/workflow/at-simplify/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: at-simplify
+description: "Refactor changed code to reduce duplication, complexity, and wasted work. Use for diffs, commit ranges, PRs, paths, staged changes, or working-tree changes."
+---
+
+# Simplify
+
+`at-simplify → 4 cleanup agents in parallel → apply the fixes`
+
+You are improving the quality of the changed code, not hunting for bugs. Review
+it for reuse, simplification, efficiency, and altitude issues, then fix what you
+find. Do not look for correctness bugs — that is what `at-review` is for.
+
+## Phase 0 — Gather the diff
+
+Run `git diff "@{upstream}...HEAD"` (or `git diff main...HEAD` / `git diff HEAD~1`
+if there's no upstream) to get the unified diff under review. If there are
+uncommitted changes, or the range diff is empty, also run `git diff HEAD` and
+include the working-tree changes in scope — the review often runs before the
+commit. If a PR number, branch name, or file path was passed as an argument,
+review that target instead. Treat this diff as the review scope.
+
+## Phase 1 — Review (4 cleanup agents in parallel)
+
+Launch **4 independent review agents** using multi-agent capabilities, all in a
+single message so they run concurrently. Pass each agent the diff and one of
+the four angles below. Each returns its findings with `file`, `line`, a
+one-line `summary`, and the concrete cost (what is duplicated, wasted, or
+harder to maintain).
+
+### Reuse
+
+Flag new code that re-implements something the codebase
+already has — Grep shared/utility modules and files adjacent to the change,
+and name the existing helper to call instead.
+
+### Simplification
+
+Flag unnecessary complexity the diff adds: redundant or derivable state,
+copy-paste with slight variation, deep nesting, dead code left behind. Name
+the simpler form that does the same job.
+
+### Efficiency
+
+Flag wasted work the diff introduces: redundant computation or repeated I/O,
+independent operations run sequentially, blocking work added to startup or
+hot paths. Also flag long-lived objects built from closures or captured
+environments — they keep the entire enclosing scope alive for the object's
+lifetime (a memory leak when that scope holds large values); prefer a
+class/struct that copies only the fields it needs. Name the cheaper
+alternative.
+
+### Altitude
+
+Check that each change is implemented at the right depth, not as a fragile
+bandaid. Special cases layered on shared infrastructure are a sign the fix
+isn't deep enough — prefer generalizing the underlying mechanism over adding
+special cases.
+
+## Phase 2 — Apply the fixes
+
+Wait for all four agents to complete, dedup findings that point at the same
+line or mechanism, and fix each remaining one directly. Skip any finding whose
+fix would change intended behavior, require changes well outside the reviewed
+diff, or that you judge to be a false positive — note the skip rather than
+arguing with it. Finish with a brief summary of what was fixed and what was
+skipped (or confirm the code was already clean).

package/statusline/.gitkeep

@@ -0,0 +1 @@
+

package/statusline/claude/statusline.mjs

@@ -0,0 +1,399 @@
+#!/usr/bin/env node
+// Claude Code statusLine script (agent-tools).
+// Reads session JSON from stdin and prints one compact status line.
+//
+// Default:
+//   ⎇ main | Opus 4.8 | 5h 7% ⟳2h54m | w 41% ⟳3d1h
+//
+// Customize with either:
+//   node statusline.mjs --fields branch,model,fiveHour,week
+//   AGENT_TOOLS_STATUSLINE_FIELDS=branch,model,context
+//   ~/.agent-tools/config.jsonc
+
+import { execFileSync, spawn } from "node:child_process";
+import fs from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const AGENT_TOOLS_HOME = process.env.AGENT_TOOLS_HOME || join(SCRIPT_DIR, "..", "..");
+const DEFAULT_CONFIG_FILE = join(AGENT_TOOLS_HOME, "config.jsonc");
+const SNAPSHOT_FILE = join(AGENT_TOOLS_HOME, "cache", "usage-snapshot.json");
+const REFRESH_STATE_FILE = join(AGENT_TOOLS_HOME, "cache", "usage-refresh-state.json");
+const USAGE_RUNTIME = join(AGENT_TOOLS_HOME, "lib", "usage.mjs");
+const DEFAULT_SNAPSHOT_TTL_MS = 60_000;
+const DEFAULT_REFRESH_COOLDOWN_MS = 30_000;
+const DEFAULT_FAILURE_BACKOFF_MS = 120_000;
+
+const DEFAULT_CONFIG = {
+  fields: ["branch", "model", "fiveHour", "week"],
+  separator: " | ",
+  symbols: {
+    branch: "⎇",
+    reset: "⟳",
+    empty: "–",
+    fiveHour: "5h",
+    week: "w",
+    context: "ctx",
+  },
+};
+
+const FIELD_ALIASES = {
+  cwd: "directory",
+  dir: "directory",
+  five: "fiveHour",
+  five_hour: "fiveHour",
+  "5h": "fiveHour",
+  sevenDay: "week",
+  seven_day: "week",
+  "7d": "week",
+  weekly: "week",
+  ctx: "context",
+};
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function readJsonFile(file) {
+  try {
+    if (!fs.existsSync(file)) return {};
+    const raw = stripJsonComments(fs.readFileSync(file, "utf8").replace(/^\uFEFF/, ""));
+    return raw.trim() ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+function stripJsonComments(input) {
+  let out = "";
+  let inString = false;
+  let escaped = false;
+  for (let i = 0; i < input.length; i++) {
+    const ch = input[i];
+    const next = input[i + 1];
+    if (inString) {
+      out += ch;
+      escaped = ch === "\\" ? !escaped : false;
+      if (ch === "\"" && !escaped) inString = false;
+      continue;
+    }
+    if (ch === "\"") {
+      inString = true;
+      out += ch;
+      continue;
+    }
+    if (ch === "/" && next === "/") {
+      while (i < input.length && input[i] !== "\n") i++;
+      out += "\n";
+      continue;
+    }
+    if (ch === "/" && next === "*") {
+      i += 2;
+      while (i < input.length && !(input[i] === "*" && input[i + 1] === "/")) i++;
+      i++;
+      continue;
+    }
+    out += ch;
+  }
+  return out;
+}
+
+function parseArgs(argv) {
+  const opts = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--fields" && argv[i + 1]) {
+      opts.fields = argv[++i];
+    } else if (arg.startsWith("--fields=")) {
+      opts.fields = arg.slice("--fields=".length);
+    } else if (arg === "--separator" && argv[i + 1]) {
+      opts.separator = argv[++i];
+    } else if (arg.startsWith("--separator=")) {
+      opts.separator = arg.slice("--separator=".length);
+    }
+  }
+  return opts;
+}
+
+function splitFields(value) {
+  if (Array.isArray(value)) return value;
+  if (typeof value !== "string") return null;
+  return value
+    .split(/[,\s]+/)
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+function normalizeField(field) {
+  return FIELD_ALIASES[field] || field;
+}
+
+function mergeConfig(cli) {
+  const rootConfig = readJsonFile(process.env.AGENT_TOOLS_CONFIG || DEFAULT_CONFIG_FILE);
+  const fileConfig = rootConfig.statusline || {};
+  const envFields = process.env.AGENT_TOOLS_STATUSLINE_FIELDS;
+  const envSeparator = process.env.AGENT_TOOLS_STATUSLINE_SEPARATOR;
+
+  const config = {
+    ...DEFAULT_CONFIG,
+    ...fileConfig,
+    symbols: { ...DEFAULT_CONFIG.symbols, ...(fileConfig.symbols || {}) },
+  };
+
+  const fields =
+    splitFields(cli.fields) ||
+    splitFields(envFields) ||
+    splitFields(fileConfig.fields) ||
+    DEFAULT_CONFIG.fields;
+
+  config.fields = fields.map(normalizeField);
+  if (typeof envSeparator === "string") config.separator = envSeparator;
+  if (typeof cli.separator === "string") config.separator = cli.separator;
+  return config;
+}
+
+function gitBranch(cwd) {
+  try {
+    const out = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+      cwd,
+      stdio: ["ignore", "pipe", "ignore"],
+      encoding: "utf8",
+    }).trim();
+    return out && out !== "HEAD" ? out : "";
+  } catch {
+    return "";
+  }
+}
+
+function secondsUntil(unixSeconds) {
+  if (!unixSeconds) return null;
+  const seconds = Number(unixSeconds) - Math.floor(Date.now() / 1000);
+  return Number.isFinite(seconds) ? Math.max(0, seconds) : null;
+}
+
+function compactDuration(totalSeconds) {
+  if (totalSeconds == null) return "";
+  if (totalSeconds <= 0) return "0m";
+  let seconds = totalSeconds;
+  const days = Math.floor(seconds / 86400);
+  seconds %= 86400;
+  const hours = Math.floor(seconds / 3600);
+  seconds %= 3600;
+  const minutes = Math.floor(seconds / 60);
+  if (days) return `${days}d${hours}h`;
+  if (hours) return `${hours}h${minutes}m`;
+  return `${minutes}m`;
+}
+
+function usageWindow(window, config) {
+  if (!window || typeof window.used_percentage !== "number") {
+    return "";
+  }
+  const pct = `${Math.round(window.used_percentage)}%`;
+  const left = compactDuration(secondsUntil(window.resets_at));
+  return left ? `${pct} ${config.symbols.reset}${left}` : pct;
+}
+
+function showMissingUsageWindow() {
+  const baseUrl = activeRelayBaseUrl();
+  return !baseUrl || isOfficialBaseUrl(baseUrl);
+}
+
+function shortModelName(name) {
+  if (!name) return "";
+  return String(name)
+    .replace(/^Claude\s+/i, "")
+    .replace(/\s*\[1m\]\s*$/i, "")
+    .trim();
+}
+
+function renderField(field, data, config) {
+  const dir = data?.workspace?.current_dir || data?.cwd || process.cwd() || "";
+  const projectDir = data?.workspace?.project_dir || dir;
+  switch (field) {
+    case "branch": {
+      const branch = gitBranch(projectDir);
+      return branch ? `${config.symbols.branch} ${branch}` : "";
+    }
+    case "model":
+      return shortModelName(data?.model?.display_name || data?.model?.id || "");
+    case "fiveHour": {
+      const value = usageWindow(data?.rate_limits?.five_hour, config);
+      return value || showMissingUsageWindow()
+        ? `${config.symbols.fiveHour} ${value || config.symbols.empty}`
+        : "";
+    }
+    case "week": {
+      const value = usageWindow(data?.rate_limits?.seven_day, config);
+      return value || showMissingUsageWindow()
+        ? `${config.symbols.week} ${value || config.symbols.empty}`
+        : "";
+    }
+    case "context": {
+      const pct = data?.context_window?.used_percentage;
+      return typeof pct === "number" ? `${config.symbols.context} ${Math.round(pct)}%` : "";
+    }
+    case "directory":
+      return dir ? basename(dir) : "";
+    default:
+      return "";
+  }
+}
+
+function numberFromEnv(name, fallback) {
+  const value = Number(process.env[name]);
+  return Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+
+function cleanBaseUrl(baseUrl) {
+  return String(baseUrl || "").replace(/\/+$/, "");
+}
+
+function isOfficialBaseUrl(baseUrl) {
+  if (!baseUrl) return true;
+  const clean = cleanBaseUrl(baseUrl);
+  return [
+    "https://api.anthropic.com",
+    "https://api.anthropic.com/v1",
+    "https://api.openai.com",
+    "https://api.openai.com/v1",
+  ].includes(clean);
+}
+
+function usageRouteCacheKey(baseUrl) {
+  try {
+    const url = new URL(cleanBaseUrl(baseUrl));
+    url.hash = "";
+    url.search = "";
+    url.pathname = url.pathname
+      .replace(/\/+$/, "")
+      .replace(/\/api\/v1$/i, "")
+      .replace(/\/v1$/i, "");
+    return url.toString().replace(/\/$/, "");
+  } catch {
+    return cleanBaseUrl(baseUrl).endsWith("/v1") ? cleanBaseUrl(baseUrl).slice(0, -3) : cleanBaseUrl(baseUrl);
+  }
+}
+
+function readJsonFileRaw(file) {
+  try {
+    if (!fs.existsSync(file)) return {};
+    const raw = fs.readFileSync(file, "utf8").replace(/^\uFEFF/, "");
+    return raw.trim() ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+function activeRelayBaseUrl() {
+  return process.env.PROVIDER_USAGE_BASE_URL || process.env.ANTHROPIC_BASE_URL || "";
+}
+
+function hasClaudeUsageToken() {
+  return Boolean(
+    process.env.PROVIDER_USAGE_API_KEY ||
+      process.env.ANTHROPIC_AUTH_TOKEN ||
+      process.env.ANTHROPIC_API_KEY
+  );
+}
+
+function snapshotForBaseUrl(baseUrl) {
+  const snapshot = readJsonFileRaw(SNAPSHOT_FILE);
+  const key = usageRouteCacheKey(baseUrl);
+  const item = snapshot?.items?.[key];
+  return item?.text ? item : null;
+}
+
+function refreshStateForBaseUrl(baseUrl) {
+  const state = readJsonFileRaw(REFRESH_STATE_FILE);
+  return state?.items?.[usageRouteCacheKey(baseUrl)] || {};
+}
+
+function ageMs(isoDate) {
+  const time = Date.parse(isoDate || "");
+  return Number.isFinite(time) ? Date.now() - time : Number.POSITIVE_INFINITY;
+}
+
+function writeRefreshAttempt(baseUrl) {
+  try {
+    const state = readJsonFileRaw(REFRESH_STATE_FILE);
+    const key = usageRouteCacheKey(baseUrl);
+    state.version = 1;
+    state.items = state.items && typeof state.items === "object" ? state.items : {};
+    state.items[key] = {
+      ...(state.items[key] || {}),
+      baseUrl,
+      lastAttemptAt: new Date().toISOString(),
+    };
+    fs.mkdirSync(dirname(REFRESH_STATE_FILE), { recursive: true });
+    fs.writeFileSync(REFRESH_STATE_FILE, `${JSON.stringify(state, null, 2)}\n`);
+  } catch {
+    // Statusline must stay non-blocking and fail-open.
+  }
+}
+
+function shouldRefreshUsage(baseUrl, snapshot) {
+  if (process.env.AGENT_TOOLS_USAGE_REFRESH === "0") return false;
+  if (!baseUrl || isOfficialBaseUrl(baseUrl)) return false;
+  if (!hasClaudeUsageToken()) return false;
+  if (!fs.existsSync(USAGE_RUNTIME)) return false;
+
+  const ttlMs = numberFromEnv("AGENT_TOOLS_USAGE_SNAPSHOT_TTL_MS", DEFAULT_SNAPSHOT_TTL_MS);
+  const cooldownMs = numberFromEnv("AGENT_TOOLS_USAGE_REFRESH_COOLDOWN_MS", DEFAULT_REFRESH_COOLDOWN_MS);
+  const failureBackoffMs = numberFromEnv("AGENT_TOOLS_USAGE_FAILURE_BACKOFF_MS", DEFAULT_FAILURE_BACKOFF_MS);
+  const state = refreshStateForBaseUrl(baseUrl);
+
+  if (ageMs(state.lastAttemptAt) < cooldownMs) return false;
+  if (state.lastError && ageMs(state.lastFailureAt) < failureBackoffMs) return false;
+  return !snapshot || ageMs(snapshot.updatedAt) >= ttlMs;
+}
+
+function refreshUsageInBackground(baseUrl) {
+  if (!shouldRefreshUsage(baseUrl, snapshotForBaseUrl(baseUrl))) return;
+  writeRefreshAttempt(baseUrl);
+  try {
+    const child = spawn(process.execPath, [USAGE_RUNTIME, "refresh", "--agent", "claude"], {
+      detached: true,
+      stdio: "ignore",
+      env: process.env,
+      windowsHide: true,
+    });
+    child.unref();
+  } catch {
+    // Statusline must never surface provider usage refresh errors.
+  }
+}
+
+function providerUsageStatus() {
+  const baseUrl = activeRelayBaseUrl();
+  if (!baseUrl || isOfficialBaseUrl(baseUrl)) return "";
+  const snapshot = snapshotForBaseUrl(baseUrl);
+  if (shouldRefreshUsage(baseUrl, snapshot)) refreshUsageInBackground(baseUrl);
+  return snapshot?.text || "";
+}
+
+function render(data, config) {
+  const fields = config.fields
+    .map((field) => renderField(field, data, config))
+    .filter(Boolean);
+  const providerUsage = providerUsageStatus();
+  if (providerUsage) fields.push(providerUsage);
+  return fields.join(config.separator);
+}
+
+async function main() {
+  const config = mergeConfig(parseArgs(process.argv.slice(2)));
+  let data = {};
+  try {
+    const raw = await readStdin();
+    data = raw.trim() ? JSON.parse(raw) : {};
+  } catch {
+    data = {};
+  }
+  process.stdout.write(render(data, config));
+}
+
+main();

package/statusline/codex/.gitkeep

@@ -0,0 +1 @@
+