aether-code 0.37.0 → 0.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aether-code",
-  "version": "0.37.0",
+  "version": "0.39.0",
   "description": "Uncensored AI coding agent for your terminal — Claude Code alternative with MCP support. Reads code, writes files, runs commands. Drives IDA Pro, Roblox Studio, Wireshark, Blender, and any MCP server. No refusal layer.",
   "homepage": "https://trynoguard.com",
   "repository": {

package/src/agent.js

@@ -4,11 +4,12 @@
 
 import os from "node:os";
 import path from "node:path";
+import { spawn } from "node:child_process";
 import { agentTurnStream, AetherError } from "./api.js";
 import { TOOL_DEFINITIONS, executeTool } from "./tools.js";
 import { unnamespaceToolName } from "./mcp.js";
 import { loadAllSkills, selectSkills, renderSkillsBlock } from "./skills.js";
-import { scanProject } from "./project-context.js";
+import { scanProject, detectVerifyCommand } from "./project-context.js";
 import { c, divider, turn, toolLabel, toolSummary, makeTokenStripper, errorLine, startSpinner } from "./render.js";
 
 const DEFAULT_MAX_TURNS = 25;
@@ -109,6 +110,7 @@ export async function runAgent({
   // finishes having read files it never edited, we nudge it once to finish.
   const looksLikeModification = MOD_RE.test(initialPrompt);
   let appliedNothingNudges = 0;
+  let verifyRounds = 0;
 
   for (let i = 0; i < maxTurns; i++) {
     // No turn header and no leading blank here — each step (assistant text and
@@ -218,6 +220,30 @@ export async function runAgent({
         messages.push({ role: "user", content: msg });
         continue; // give the model another turn to finish
       }
+      // Auto-verify: if we touched files, run the project's typecheck/lint
+      // and feed errors back so the model can self-correct without the user
+      // having to say "fix that." At most 2 verify rounds to avoid infinite loops.
+      if (filesTouched.size > 0 && verifyRounds < 2) {
+        const verifyResult = await runVerify(cwd);
+        if (verifyResult && !verifyResult.ok) {
+          verifyRounds++;
+          console.log("\n" + c.yellow("●") + " " + c.bold("auto-verify") + c.gray(` (${verifyResult.label})`));
+          console.log(c.red("  └─") + " " + c.gray("errors found — feeding back to fix"));
+          const errPreview = verifyResult.output.length > 4000
+            ? verifyResult.output.slice(0, 4000) + "\n…(truncated)"
+            : verifyResult.output;
+          messages.push({
+            role: "user",
+            content:
+              `AUTO-VERIFY FAILED (${verifyResult.label}):\n\`\`\`\n${errPreview}\n\`\`\`\n` +
+              `Fix these errors NOW using edit_file. Do not explain — just fix and move on.`,
+          });
+          continue;
+        }
+        if (verifyResult && verifyResult.ok) {
+          console.log("\n" + c.green("●") + " " + c.bold("auto-verify") + c.gray(` (${verifyResult.label}) — passed`));
+        }
+      }
       if (filesTouched.size) {
         console.log("\n" + c.bold("Files") + c.gray(` in ${cwd}`));
         for (const [p, action] of filesTouched) {
@@ -298,6 +324,32 @@ export async function runAgent({
   return { ok: false, error: new Error("Max turns reached"), totalCredits, totalIn, totalOut, balance: lastBalance, messages };
 }
 
+// Auto-verify: run the project's typecheck/lint command silently and return
+// { ok, output, label }. Returns null if no verify command is detected.
+let cachedVerify = undefined;
+async function runVerify(cwd) {
+  if (cachedVerify === undefined) cachedVerify = detectVerifyCommand(cwd);
+  if (!cachedVerify) return null;
+  const { cmd, label } = cachedVerify;
+  return new Promise((resolve) => {
+    const child = spawn(cmd, [], { cwd, shell: true, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => { child.kill("SIGTERM"); }, 60_000);
+    child.stdout.on("data", (d) => { stdout += d.toString(); });
+    child.stderr.on("data", (d) => { stderr += d.toString(); });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      const output = (stdout + "\n" + stderr).trim();
+      resolve({ ok: code === 0, output, label });
+    });
+    child.on("error", () => {
+      clearTimeout(timer);
+      resolve(null);
+    });
+  });
+}
+
 /**
  * Per-turn skill injection. Selects skills against the latest user message
  * + paths the model has touched, then prepends matching bodies onto the

package/src/project-context.js

@@ -263,6 +263,278 @@ export function scanProject(cwd) {
   return lines.join("\n") + "\n";
 }
 
+// ─────────── /init — deep project indexing ───────────
+
+const KEY_FILES = [
+  "README.md", "CLAUDE.md", ".env.example", "Dockerfile",
+  "docker-compose.yml", "docker-compose.yaml",
+];
+
+const ENTRY_PATTERNS = [
+  /^(src\/)?index\.[jt]sx?$/,
+  /^(src\/)?main\.[jt]sx?$/,
+  /^(src\/)?app\.[jt]sx?$/,
+  /^(src\/)?server\.[jt]sx?$/,
+  /^(bin|cli|cmd)\/[^/]+\.[jt]sx?$/,
+  /^(pages|app)\/_app\.[jt]sx?$/,
+  /^(pages|app)\/layout\.[jt]sx?$/,
+];
+
+const CONFIG_FILES = [
+  "next.config.js", "next.config.mjs", "next.config.ts",
+  "vite.config.ts", "vite.config.js", "webpack.config.js",
+  "tsconfig.json", "tailwind.config.js", "tailwind.config.ts",
+  "eslint.config.js", ".eslintrc.js", ".eslintrc.json",
+  "jest.config.js", "jest.config.ts", "vitest.config.ts",
+  "prisma/schema.prisma", "drizzle.config.ts",
+];
+
+function collectSourceFiles(dir, base, maxFiles = 500) {
+  const results = [];
+  function walk(current, rel) {
+    if (results.length >= maxFiles) return;
+    let entries;
+    try { entries = fs.readdirSync(current, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (results.length >= maxFiles) return;
+      if (e.name.startsWith(".") && e.name !== ".env.example") continue;
+      if (SKIP_DIRS.has(e.name)) continue;
+      const fullPath = path.join(current, e.name);
+      const relPath = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        walk(fullPath, relPath);
+      } else if (e.isFile()) {
+        let size = 0;
+        try { size = fs.statSync(fullPath).size; } catch { /* skip */ }
+        results.push({ path: relPath, size });
+      }
+    }
+  }
+  walk(dir, "");
+  return results;
+}
+
+function identifyKeyFiles(allFiles, cwd) {
+  const key = [];
+  for (const f of allFiles) {
+    const name = f.path.split("/").pop();
+    if (KEY_FILES.includes(name)) { key.push(f.path); continue; }
+    if (CONFIG_FILES.includes(f.path)) { key.push(f.path); continue; }
+    for (const pat of ENTRY_PATTERNS) {
+      if (pat.test(f.path)) { key.push(f.path); break; }
+    }
+  }
+  return key;
+}
+
+function summarizeFile(filePath, maxLines = 30) {
+  try {
+    const stat = fs.statSync(filePath);
+    if (!stat.isFile() || stat.size > 200_000) return null;
+    const content = fs.readFileSync(filePath, "utf8");
+    const lines = content.split("\n");
+    const exports = [];
+    const imports = [];
+    for (const line of lines.slice(0, 100)) {
+      if (/^export\s+(default\s+)?(function|class|const|let|async)\s+(\w+)/m.test(line)) {
+        const match = line.match(/^export\s+(?:default\s+)?(?:function|class|const|let|async\s+function)\s+(\w+)/);
+        if (match) exports.push(match[1]);
+      }
+      if (/^import\s/.test(line)) {
+        const match = line.match(/from\s+["']([^"']+)["']/);
+        if (match && !match[1].startsWith(".")) imports.push(match[1]);
+      }
+    }
+    const summary = { lines: lines.length };
+    if (exports.length > 0) summary.exports = exports.slice(0, 15);
+    if (imports.length > 0) summary.externalImports = [...new Set(imports)].slice(0, 10);
+    const firstComment = content.match(/^\/\/\s*(.+)/m);
+    if (firstComment) summary.description = firstComment[1].trim().slice(0, 120);
+    return summary;
+  } catch {
+    return null;
+  }
+}
+
+function detectConventions(allFiles, cwd) {
+  const conventions = [];
+  const extensions = new Set();
+  for (const f of allFiles) {
+    const ext = path.extname(f.path);
+    if (ext) extensions.add(ext);
+  }
+  if (extensions.has(".ts") || extensions.has(".tsx")) conventions.push("TypeScript");
+  if (extensions.has(".jsx") || extensions.has(".tsx")) conventions.push("JSX/TSX (React-style)");
+  const hasTest = allFiles.some((f) =>
+    /\.(test|spec)\.[jt]sx?$/.test(f.path) || f.path.startsWith("test/") || f.path.startsWith("__tests__/"),
+  );
+  if (hasTest) {
+    const testDirs = [];
+    if (allFiles.some((f) => f.path.startsWith("test/"))) testDirs.push("test/");
+    if (allFiles.some((f) => f.path.startsWith("__tests__/"))) testDirs.push("__tests__/");
+    const colocated = allFiles.some((f) => /src\/.*\.(test|spec)\.[jt]sx?$/.test(f.path));
+    if (colocated) testDirs.push("colocated in src/");
+    conventions.push(`Tests: ${testDirs.join(", ") || "detected"}`);
+  }
+  if (fs.existsSync(path.join(cwd, ".prettierrc")) || fs.existsSync(path.join(cwd, ".prettierrc.json"))) {
+    conventions.push("Prettier formatting");
+  }
+  if (fs.existsSync(path.join(cwd, ".eslintrc.js")) || fs.existsSync(path.join(cwd, "eslint.config.js"))) {
+    conventions.push("ESLint");
+  }
+  return conventions;
+}
+
+function buildDirectoryTree(allFiles, maxDepth = 3) {
+  const tree = {};
+  for (const f of allFiles) {
+    const parts = f.path.split("/");
+    let node = tree;
+    for (let i = 0; i < Math.min(parts.length - 1, maxDepth); i++) {
+      if (!node[parts[i]]) node[parts[i]] = {};
+      node = node[parts[i]];
+    }
+  }
+  function render(node, indent = "") {
+    const lines = [];
+    const entries = Object.keys(node).sort();
+    for (const key of entries) {
+      const children = Object.keys(node[key]);
+      lines.push(`${indent}${key}/`);
+      if (children.length > 0 && indent.length < maxDepth * 2) {
+        lines.push(...render(node[key], indent + "  "));
+      }
+    }
+    return lines;
+  }
+  return render(tree);
+}
+
+export function generateProjectIndex(cwd) {
+  const lines = [];
+  lines.push("# Project Context");
+  lines.push(`# Auto-generated by \`aether /init\` — edit freely, this file is yours.`);
+  lines.push(`# Loaded on every agent turn to give the model deep project understanding.`);
+  lines.push("");
+
+  const { dirs, files: topFiles } = listTopLevel(cwd);
+  const frameworks = detectFrameworks(cwd, topFiles);
+  const pkg = extractPackageInfo(cwd);
+  const cargo = extractCargoInfo(cwd);
+  const goInfo = extractGoInfo(cwd);
+  const pyInfo = extractPythonInfo(cwd);
+
+  lines.push("## Overview");
+  if (pkg?.name) lines.push(`- **Package:** ${pkg.name}${pkg.version ? ` v${pkg.version}` : ""}`);
+  if (cargo?.name) lines.push(`- **Crate:** ${cargo.name}${cargo.version ? ` v${cargo.version}` : ""}`);
+  if (goInfo?.module) lines.push(`- **Module:** ${goInfo.module}${goInfo.goVersion ? ` (go ${goInfo.goVersion})` : ""}`);
+  if (pyInfo?.name) lines.push(`- **Python:** ${pyInfo.name || pyInfo.type}`);
+  if (frameworks.length > 0) lines.push(`- **Stack:** ${frameworks.join(", ")}`);
+  if (pkg?.frameworks?.length) lines.push(`- **Libraries:** ${pkg.frameworks.join(", ")}`);
+  if (pkg?.depCounts) lines.push(`- **Dependencies:** ${pkg.depCounts}`);
+  lines.push("");
+
+  const allFiles = collectSourceFiles(cwd);
+  const conventions = detectConventions(allFiles, cwd);
+  if (conventions.length > 0) {
+    lines.push("## Conventions");
+    for (const c of conventions) lines.push(`- ${c}`);
+    lines.push("");
+  }
+
+  if (pkg?.scripts?.length) {
+    lines.push("## Scripts");
+    const pkgFull = readJsonSafe(path.join(cwd, "package.json"));
+    if (pkgFull?.scripts) {
+      for (const [name, cmd] of Object.entries(pkgFull.scripts)) {
+        lines.push(`- \`npm run ${name}\` → \`${cmd}\``);
+      }
+    }
+    lines.push("");
+  }
+
+  lines.push("## Structure");
+  const tree = buildDirectoryTree(allFiles);
+  for (const t of tree.slice(0, 60)) lines.push(t);
+  if (tree.length > 60) lines.push(`... (${tree.length - 60} more directories)`);
+  lines.push("");
+
+  const keyFiles = identifyKeyFiles(allFiles, cwd);
+  if (keyFiles.length > 0) {
+    lines.push("## Key Files");
+    for (const kf of keyFiles.slice(0, 25)) {
+      const abs = path.join(cwd, kf.replace(/\//g, path.sep));
+      const summary = summarizeFile(abs);
+      if (summary) {
+        const desc = summary.description ? ` — ${summary.description}` : "";
+        const exports = summary.exports?.length ? ` (exports: ${summary.exports.join(", ")})` : "";
+        lines.push(`- \`${kf}\` [${summary.lines} lines]${desc}${exports}`);
+      } else {
+        lines.push(`- \`${kf}\``);
+      }
+    }
+    lines.push("");
+  }
+
+  const sourceByDir = {};
+  for (const f of allFiles) {
+    const dir = f.path.includes("/") ? f.path.split("/").slice(0, -1).join("/") : ".";
+    if (!sourceByDir[dir]) sourceByDir[dir] = [];
+    sourceByDir[dir].push(f);
+  }
+  const topDirs = Object.entries(sourceByDir)
+    .sort((a, b) => b[1].length - a[1].length)
+    .slice(0, 10);
+  if (topDirs.length > 0) {
+    lines.push("## Module Map");
+    for (const [dir, dirFiles] of topDirs) {
+      const exts = {};
+      for (const f of dirFiles) {
+        const ext = path.extname(f.path) || "(no ext)";
+        exts[ext] = (exts[ext] || 0) + 1;
+      }
+      const extStr = Object.entries(exts).map(([e, c]) => `${c}${e}`).join(", ");
+      lines.push(`- \`${dir}/\` — ${dirFiles.length} files (${extStr})`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## Notes");
+  lines.push("<!-- Add project-specific instructions, patterns, or gotchas below. -->");
+  lines.push("<!-- The agent reads this file on every turn. -->");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+// ─────────── Auto-verify: detect project check commands ───────────
+
+export function detectVerifyCommand(cwd) {
+  const pkg = readJsonSafe(path.join(cwd, "package.json"));
+  if (pkg?.scripts) {
+    if (pkg.scripts.typecheck) return { cmd: "npm run typecheck", label: "typecheck" };
+    if (pkg.scripts["type-check"]) return { cmd: "npm run type-check", label: "typecheck" };
+  }
+  if (fs.existsSync(path.join(cwd, "tsconfig.json"))) {
+    const hasTsc = pkg?.devDependencies?.typescript || pkg?.dependencies?.typescript;
+    if (hasTsc) return { cmd: "npx tsc --noEmit", label: "typecheck" };
+  }
+  if (pkg?.scripts) {
+    if (pkg.scripts.lint) return { cmd: "npm run lint", label: "lint" };
+    if (pkg.scripts.check) return { cmd: "npm run check", label: "check" };
+  }
+  const cargo = readTextSafe(path.join(cwd, "Cargo.toml"), 500);
+  if (cargo) return { cmd: "cargo check", label: "cargo check" };
+  const goMod = readTextSafe(path.join(cwd, "go.mod"), 500);
+  if (goMod) return { cmd: "go vet ./...", label: "go vet" };
+  if (fs.existsSync(path.join(cwd, "pyproject.toml"))) {
+    if (pkg?.scripts?.mypy || fs.existsSync(path.join(cwd, "mypy.ini"))) {
+      return { cmd: "mypy .", label: "mypy" };
+    }
+  }
+  return null;
+}
+
 export function scanProjectQuick(cwd) {
   const { dirs, files } = listTopLevel(cwd);
   const total = dirs.length + files.length;

package/src/render.js

@@ -88,6 +88,13 @@ export function toolLabel(name, args) {
     case "web_fetch":    return `${verb("fetch")}  ${arg(a.url)}`;
     case "todo_write":   return ""; // its Plan box is the label
     case "ask_user":     return ""; // the interactive menu is its display
+    case "git_status":   return `${verb("git")}    ${arg("status")}`;
+    case "git_diff":     return `${verb("git")}    ${arg("diff" + (a.staged ? " --staged" : "") + (a.base ? ` ${a.base}...${a.head || "HEAD"}` : ""))}`;
+    case "git_log":      return `${verb("git")}    ${arg("log" + (a.file ? ` -- ${a.file}` : "") + (a.branch ? ` ${a.branch}` : ""))}`;
+    case "git_commit":   return `${verb("git")}    ${arg(`commit "${ellip(a.message || "", 50)}"`)}`
+    case "git_branch":   return `${verb("git")}    ${arg(`branch ${a.name}`)}`;
+    case "git_push":     return `${verb("git")}    ${arg("push" + (a.force ? " --force" : ""))}`;
+    case "git_create_pr": return `${verb("git")}    ${arg(`pr "${ellip(a.title || "", 50)}"`)}`
     default:             return `${verb(name)} ${arg(JSON.stringify(a))}`;
   }
 }
@@ -142,6 +149,32 @@ export function toolSummary(name, result) {
   }
   if (name === "todo_write") return ""; // the Plan is its own feedback
   if (name === "ask_user") return ""; // the menu already showed the answer
+  if (name === "git_commit" || name === "git_push" || name === "git_create_pr") {
+    return `  ${branch} ${c.gray(ellip(firstLine, 100))}`;
+  }
+  if (name === "git_status") {
+    try {
+      const s = JSON.parse(out);
+      if (s.clean) return `  ${branch} ${c.gray("clean")}`;
+      const parts = [];
+      if (s.staged?.length) parts.push(`${s.staged.length} staged`);
+      if (s.unstaged?.length) parts.push(`${s.unstaged.length} modified`);
+      if (s.untracked?.length) parts.push(`${s.untracked.length} untracked`);
+      return `  ${branch} ${c.gray(parts.join(", "))}`;
+    } catch { /* fall through */ }
+  }
+  if (name === "git_diff") {
+    if (out === "(no changes)") return `  ${branch} ${c.gray("no changes")}`;
+    const diffLines = out.split("\n").length;
+    return `  ${branch} ${c.gray(`${diffLines} lines of diff`)}`;
+  }
+  if (name === "git_log") {
+    const logLines = out.trim().split("\n").filter((l) => l.trim()).length;
+    return `  ${branch} ${c.gray(`${logLines} lines`)}`;
+  }
+  if (name === "git_branch") {
+    return `  ${branch} ${c.gray(ellip(firstLine, 100))}`;
+  }
   if (name === "write_file" || name === "edit_file") {
     // Handler already printed the diff; echo its short status line.
     return `  ${branch} ${c.gray(ellip(firstLine, 100))}`;

package/src/repl.js

@@ -8,6 +8,7 @@
 //   - Bottom status line is rendered after each turn
 //   - Ctrl+C: first press cancels in-progress turn, second press exits
 
+import fs from "node:fs";
 import path from "node:path";
 import { runAgent } from "./agent.js";
 import { fetchBalance, AetherError } from "./api.js";
@@ -20,7 +21,7 @@ import {
   generateSessionId, saveSession, loadSession, listSessions,
   findRecentSession, deleteSession, extractSummary, formatAge,
 } from "./sessions.js";
-import { scanProjectQuick } from "./project-context.js";
+import { scanProjectQuick, generateProjectIndex } from "./project-context.js";
 
 const VERSION = getVersion();
 const MODEL_NAME = "Aether Core";
@@ -44,6 +45,7 @@ const SHORTCUTS = `
   ${c.cyan("/yes")}       Toggle auto-approve mode (skip y/N prompts)
   ${c.cyan("/turns")} ${c.gray("<n>")}     Set max turns per prompt (default 25)
   ${c.cyan("/model")} ${c.gray("[core|ultra]")}  Show or switch model (ultra=Opus — premium)
+  ${c.cyan("/init")}      Deep-scan project → generate .aether/context.md
   ${c.cyan("/sessions")}  List saved sessions for this directory
   ${c.cyan("/resume")} ${c.gray("[id]")}   Resume a saved session (default: most recent)
   ${c.cyan("/new")}       Start a fresh session (save current first)
@@ -286,6 +288,31 @@ async function handleSlash(line, state) {
       }
       break;
     }
+    case "init": {
+      console.log(c.gray("Scanning project..."));
+      try {
+        const content = generateProjectIndex(state.cwd);
+        const dir = path.join(state.cwd, ".aether");
+        fs.mkdirSync(dir, { recursive: true });
+        const filePath = path.join(dir, "context.md");
+        fs.writeFileSync(filePath, content, "utf8");
+        const lineCount = content.split("\n").length;
+        console.log(c.green("●") + " " + c.bold(`.aether/context.md`) + c.gray(` generated (${lineCount} lines)`));
+        console.log(c.gray("  The agent now reads this on every turn. Edit it freely to add project-specific notes."));
+        // Add to .gitignore if not already there
+        const gitignorePath = path.join(state.cwd, ".gitignore");
+        try {
+          const existing = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, "utf8") : "";
+          if (!existing.includes(".aether/")) {
+            fs.appendFileSync(gitignorePath, `\n# Aether agent context\n.aether/\n`, "utf8");
+            console.log(c.gray("  Added .aether/ to .gitignore"));
+          }
+        } catch { /* non-fatal */ }
+      } catch (err) {
+        console.log(errorLine(`/init failed: ${err.message}`));
+      }
+      break;
+    }
     case "sessions": {
       const sessions = listSessions(state.cwd);
       if (sessions.length === 0) {

package/src/tools.js

@@ -223,6 +223,125 @@ export const TOOL_DEFINITIONS = [
       },
     },
   },
+  /* ─────────────────────── Git tools ─────────────────────── */
+  {
+    type: "function",
+    function: {
+      name: "git_status",
+      description:
+        "Show the working tree status — staged, unstaged, and untracked files. Auto-executes (read-only). Use this before committing to see what's changed.",
+      parameters: {
+        type: "object",
+        properties: {},
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "git_diff",
+      description:
+        "Show a unified diff of changes. By default shows unstaged changes. Set staged=true for staged changes, or pass base/head for branch comparisons (e.g. base='main' head='HEAD'). Optionally limit to specific file(s).",
+      parameters: {
+        type: "object",
+        properties: {
+          staged: { type: "boolean", description: "Show staged (--cached) diff instead of unstaged. Default: false." },
+          base: { type: "string", description: "Base ref for comparison (e.g. 'main', 'HEAD~3'). When set, shows diff between base and head." },
+          head: { type: "string", description: "Head ref for comparison. Default: 'HEAD' when base is set." },
+          files: {
+            type: "array",
+            description: "Limit diff to these file paths.",
+            items: { type: "string" },
+          },
+        },
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "git_log",
+      description:
+        "Show recent commit history with hash, author, date, and message. Defaults to 15 commits. Use this to understand what's been done recently, find commit hashes, or check the commit style before committing.",
+      parameters: {
+        type: "object",
+        properties: {
+          count: { type: "number", description: "Number of commits to show (1-50). Default: 15." },
+          oneline: { type: "boolean", description: "Compact one-line format. Default: false." },
+          file: { type: "string", description: "Show only commits that touched this file." },
+          branch: { type: "string", description: "Show commits on this branch instead of HEAD." },
+        },
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "git_commit",
+      description:
+        "Stage files and create a commit. If no files are specified, stages all modified/new files (git add -A). The user will see what's being committed and confirm. Use git_status first to see what's changed, and git_log to match the commit message style.",
+      parameters: {
+        type: "object",
+        properties: {
+          message: { type: "string", description: "Commit message. Be concise — focus on WHY, not WHAT." },
+          files: {
+            type: "array",
+            description: "Specific files to stage. If omitted, stages everything (git add -A).",
+            items: { type: "string" },
+          },
+        },
+        required: ["message"],
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "git_branch",
+      description:
+        "Create and/or switch to a branch. If the branch exists, switches to it. If it doesn't, creates it from the current HEAD (or from 'base' if specified) and switches to it.",
+      parameters: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "Branch name to create or switch to." },
+          base: { type: "string", description: "Create the branch from this ref instead of HEAD." },
+        },
+        required: ["name"],
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "git_push",
+      description:
+        "Push the current branch to the remote. Sets upstream tracking (-u origin) on first push. The user will confirm before pushing.",
+      parameters: {
+        type: "object",
+        properties: {
+          force: { type: "boolean", description: "Force push (--force-with-lease). Use only when explicitly asked. Default: false." },
+        },
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "git_create_pr",
+      description:
+        "Create a GitHub pull request using the `gh` CLI. Requires `gh` to be installed and authenticated. Pushes the branch first if needed. The user will confirm before creating.",
+      parameters: {
+        type: "object",
+        properties: {
+          title: { type: "string", description: "PR title. Keep under 72 chars." },
+          body: { type: "string", description: "PR body/description. Markdown supported." },
+          base: { type: "string", description: "Target branch to merge into. Default: repo default (usually main)." },
+          draft: { type: "boolean", description: "Create as a draft PR. Default: false." },
+        },
+        required: ["title", "body"],
+      },
+    },
+  },
 ];
 
 /* ─────────────────────── Argument validation ─────────────────────── */
@@ -410,6 +529,13 @@ export async function executeTool(call, opts) {
     web_fetch: () => webFetch(args, opts),
     todo_write: () => todoWrite(args, opts),
     ask_user: () => askUser(args, opts),
+    git_status: () => gitStatus(args, opts),
+    git_diff: () => gitDiff(args, opts),
+    git_log: () => gitLog(args, opts),
+    git_commit: () => gitCommit(args, opts),
+    git_branch: () => gitBranch(args, opts),
+    git_push: () => gitPush(args, opts),
+    git_create_pr: () => gitCreatePr(args, opts),
   };
   const fn = handlers[name];
   if (!fn) {
@@ -859,6 +985,226 @@ async function runShell(args, opts) {
   });
 }
 
+/* ─────────────────────── Git tools ─────────────────────── */
+
+function runGit(gitArgs, cwd, timeoutMs = 30_000) {
+  return new Promise((resolve) => {
+    const child = spawn("git", gitArgs, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let killed = false;
+    const timer = setTimeout(() => { killed = true; child.kill("SIGTERM"); }, timeoutMs);
+    child.stdout.on("data", (d) => { stdout += d.toString(); });
+    child.stderr.on("data", (d) => { stderr += d.toString(); });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      const truncate = (t) => (t.length > 30_000 ? t.slice(0, 30_000) + "\n…(truncated)" : t);
+      resolve({ code, killed, stdout: truncate(stdout), stderr: truncate(stderr) });
+    });
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      resolve({ code: 1, killed: false, stdout: "", stderr: `git spawn error: ${err.message}` });
+    });
+  });
+}
+
+async function gitStatus(_args, opts) {
+  const r = await runGit(["status", "--short", "--branch", "-u"], opts.cwd);
+  if (r.code !== 0) return { ok: false, output: r.stderr || "git status failed" };
+  const lines = r.stdout.trim().split("\n");
+  const branchLine = lines[0] || "";
+  const files = lines.slice(1).filter((l) => l.trim());
+  const staged = [];
+  const unstaged = [];
+  const untracked = [];
+  for (const line of files) {
+    const x = line[0];
+    const y = line[1];
+    const name = line.slice(3);
+    if (x === "?") { untracked.push(name); continue; }
+    if (x !== " " && x !== "?") staged.push({ status: x, file: name });
+    if (y !== " " && y !== "?") unstaged.push({ status: y, file: name });
+  }
+  const result = {
+    branch: branchLine.replace(/^## /, ""),
+    staged,
+    unstaged,
+    untracked,
+    clean: staged.length === 0 && unstaged.length === 0 && untracked.length === 0,
+  };
+  return { ok: true, output: JSON.stringify(result, null, 2) };
+}
+
+async function gitDiff(args, opts) {
+  const gitArgs = ["diff", "--stat", "--patch"];
+  if (args.staged) gitArgs.push("--cached");
+  if (args.base) {
+    const head = args.head || "HEAD";
+    gitArgs.length = 0;
+    gitArgs.push("diff", args.base + "..." + head, "--stat", "--patch");
+  }
+  if (Array.isArray(args.files) && args.files.length > 0) {
+    gitArgs.push("--");
+    for (const f of args.files) gitArgs.push(f);
+  }
+  const r = await runGit(gitArgs, opts.cwd, 60_000);
+  if (r.code !== 0) return { ok: false, output: r.stderr || "git diff failed" };
+  if (!r.stdout.trim()) return { ok: true, output: "(no changes)" };
+  return { ok: true, output: r.stdout };
+}
+
+async function gitLog(args, opts) {
+  const count = Math.min(50, Math.max(1, args.count ?? 15));
+  const gitArgs = ["log", `-${count}`];
+  if (args.oneline) {
+    gitArgs.push("--oneline");
+  } else {
+    gitArgs.push("--format=%h %an (%ar)%n  %s%n");
+  }
+  if (args.branch) gitArgs.push(args.branch);
+  if (args.file) { gitArgs.push("--"); gitArgs.push(args.file); }
+  const r = await runGit(gitArgs, opts.cwd);
+  if (r.code !== 0) return { ok: false, output: r.stderr || "git log failed" };
+  if (!r.stdout.trim()) return { ok: true, output: "(no commits)" };
+  return { ok: true, output: r.stdout };
+}
+
+async function gitCommit(args, opts) {
+  if (typeof args.message !== "string" || !args.message.trim()) {
+    return { ok: false, output: "commit message is required" };
+  }
+  // Stage files
+  const filesToStage = Array.isArray(args.files) && args.files.length > 0 ? args.files : null;
+  if (filesToStage) {
+    const addR = await runGit(["add", "--", ...filesToStage], opts.cwd);
+    if (addR.code !== 0) return { ok: false, output: `git add failed: ${addR.stderr}` };
+  } else {
+    const addR = await runGit(["add", "-A"], opts.cwd);
+    if (addR.code !== 0) return { ok: false, output: `git add -A failed: ${addR.stderr}` };
+  }
+  // Show what's staged
+  const staged = await runGit(["diff", "--cached", "--stat"], opts.cwd);
+  if (!staged.stdout.trim()) {
+    return { ok: false, output: "Nothing to commit — no staged changes after git add." };
+  }
+  console.log(c.dim(staged.stdout));
+  console.log(c.cyan("commit message: ") + c.bold(args.message));
+  const approved = await confirm(c.yellow("Create this commit?"), opts.autoYes);
+  if (!approved) {
+    await runGit(["reset", "HEAD"], opts.cwd);
+    return { ok: false, output: "User declined the commit. Staged changes have been unstaged." };
+  }
+  const commitR = await runGit(["commit", "-m", args.message], opts.cwd);
+  if (commitR.code !== 0) return { ok: false, output: `git commit failed: ${commitR.stderr}` };
+  // Get the commit hash for confirmation
+  const hashR = await runGit(["rev-parse", "--short", "HEAD"], opts.cwd);
+  const hash = hashR.stdout.trim();
+  return { ok: true, output: `Committed ${hash}: ${args.message}\n${commitR.stdout}` };
+}
+
+async function gitBranch(args, opts) {
+  if (typeof args.name !== "string" || !args.name.trim()) {
+    return { ok: false, output: "branch name is required" };
+  }
+  // Check if branch exists
+  const checkR = await runGit(["rev-parse", "--verify", args.name], opts.cwd);
+  if (checkR.code === 0) {
+    // Branch exists, switch to it
+    const switchR = await runGit(["checkout", args.name], opts.cwd);
+    if (switchR.code !== 0) return { ok: false, output: `git checkout failed: ${switchR.stderr}` };
+    return { ok: true, output: `Switched to existing branch '${args.name}'` };
+  }
+  // Create new branch
+  const createArgs = ["checkout", "-b", args.name];
+  if (args.base) createArgs.push(args.base);
+  const createR = await runGit(createArgs, opts.cwd);
+  if (createR.code !== 0) return { ok: false, output: `git checkout -b failed: ${createR.stderr}` };
+  return { ok: true, output: `Created and switched to new branch '${args.name}'${args.base ? ` from ${args.base}` : ""}` };
+}
+
+async function gitPush(args, opts) {
+  // Get current branch name
+  const branchR = await runGit(["rev-parse", "--abbrev-ref", "HEAD"], opts.cwd);
+  if (branchR.code !== 0) return { ok: false, output: `Cannot determine current branch: ${branchR.stderr}` };
+  const branch = branchR.stdout.trim();
+  if (!branch || branch === "HEAD") {
+    return { ok: false, output: "Cannot push — HEAD is detached. Checkout a branch first." };
+  }
+  const pushArgs = ["push", "-u", "origin", branch];
+  if (args.force) pushArgs.splice(1, 0, "--force-with-lease");
+  console.log(c.yellow("$ ") + c.bold(`git ${pushArgs.join(" ")}`));
+  const approved = await confirm(c.yellow(`Push '${branch}' to origin?`), opts.autoYes);
+  if (!approved) return { ok: false, output: "User declined the push." };
+  const r = await runGit(pushArgs, opts.cwd, 60_000);
+  if (r.code !== 0) return { ok: false, output: `git push failed: ${r.stderr}` };
+  return { ok: true, output: `Pushed '${branch}' to origin.\n${r.stderr}${r.stdout}`.trim() };
+}
+
+async function gitCreatePr(args, opts) {
+  if (typeof args.title !== "string" || !args.title.trim()) {
+    return { ok: false, output: "PR title is required" };
+  }
+  if (typeof args.body !== "string") {
+    return { ok: false, output: "PR body is required" };
+  }
+  // Check if gh CLI is available
+  const ghCheck = await runGit(["--version"], opts.cwd);
+  void ghCheck;
+  const ghVerify = new Promise((resolve) => {
+    const child = spawn("gh", ["--version"], { cwd: opts.cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let out = "";
+    child.stdout.on("data", (d) => { out += d.toString(); });
+    child.on("close", (code) => resolve({ code, stdout: out }));
+    child.on("error", () => resolve({ code: 1, stdout: "" }));
+  });
+  const ghResult = await ghVerify;
+  if (ghResult.code !== 0) {
+    return { ok: false, output: "GitHub CLI (gh) is not installed or not in PATH. Install it: https://cli.github.com" };
+  }
+  // Push branch first if needed
+  const branchR = await runGit(["rev-parse", "--abbrev-ref", "HEAD"], opts.cwd);
+  const branch = branchR.stdout.trim();
+  const trackR = await runGit(["config", "--get", `branch.${branch}.remote`], opts.cwd);
+  if (trackR.code !== 0 || !trackR.stdout.trim()) {
+    console.log(c.gray(`Branch '${branch}' has no remote — pushing first...`));
+    const pushR = await runGit(["push", "-u", "origin", branch], opts.cwd, 60_000);
+    if (pushR.code !== 0) return { ok: false, output: `Failed to push branch: ${pushR.stderr}` };
+    console.log(c.gray("Pushed."));
+  }
+  // Build gh pr create command
+  console.log(c.cyan("PR title: ") + c.bold(args.title));
+  const bodyPreview = args.body.length > 200 ? args.body.slice(0, 197) + "..." : args.body;
+  console.log(c.gray(bodyPreview));
+  if (args.base) console.log(c.gray(`base: ${args.base}`));
+  if (args.draft) console.log(c.gray("(draft PR)"));
+  const approved = await confirm(c.yellow("Create this pull request?"), opts.autoYes);
+  if (!approved) return { ok: false, output: "User declined the PR." };
+  const ghArgs = ["pr", "create", "--title", args.title, "--body", args.body];
+  if (args.base) { ghArgs.push("--base"); ghArgs.push(args.base); }
+  if (args.draft) ghArgs.push("--draft");
+  return new Promise((resolve) => {
+    const child = spawn("gh", ghArgs, { cwd: opts.cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => child.kill("SIGTERM"), 30_000);
+    child.stdout.on("data", (d) => { stdout += d.toString(); });
+    child.stderr.on("data", (d) => { stderr += d.toString(); });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (code !== 0) {
+        resolve({ ok: false, output: `gh pr create failed (exit ${code}): ${stderr || stdout}` });
+      } else {
+        const prUrl = stdout.trim();
+        resolve({ ok: true, output: `Pull request created: ${prUrl}\n${stderr}`.trim() });
+      }
+    });
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      resolve({ ok: false, output: `gh spawn error: ${err.message}` });
+    });
+  });
+}
+
 /* ─────────────────────── todo_write ─────────────────────── */
 
 // Module-level singleton holding the current todo list for this CLI session.