agent-yes 1.47.0 → 1.49.0

package/agent-yes.config.schema.json

@@ -0,0 +1,163 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/snomiao/agent-yes/blob/main/agent-yes.config.schema.json",
+  "title": "agent-yes configuration",
+  "description": "Configuration schema for agent-yes - automated interaction wrapper for AI coding assistants",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference for IDE support"
+    },
+    "configDir": {
+      "type": "string",
+      "description": "Directory to store agent-yes config files (e.g., session store)"
+    },
+    "logsDir": {
+      "type": "string",
+      "description": "Directory to store agent-yes log files"
+    },
+    "clis": {
+      "type": "object",
+      "description": "CLI-specific configurations",
+      "additionalProperties": {
+        "$ref": "#/definitions/AgentCliConfig"
+      },
+      "properties": {
+        "claude": { "$ref": "#/definitions/AgentCliConfig" },
+        "gemini": { "$ref": "#/definitions/AgentCliConfig" },
+        "codex": { "$ref": "#/definitions/AgentCliConfig" },
+        "copilot": { "$ref": "#/definitions/AgentCliConfig" },
+        "cursor": { "$ref": "#/definitions/AgentCliConfig" },
+        "grok": { "$ref": "#/definitions/AgentCliConfig" },
+        "qwen": { "$ref": "#/definitions/AgentCliConfig" },
+        "auggie": { "$ref": "#/definitions/AgentCliConfig" },
+        "amp": { "$ref": "#/definitions/AgentCliConfig" },
+        "opencode": { "$ref": "#/definitions/AgentCliConfig" }
+      }
+    }
+  },
+  "definitions": {
+    "AgentCliConfig": {
+      "type": "object",
+      "description": "Configuration for a specific CLI tool",
+      "properties": {
+        "install": {
+          "description": "Install command(s) for the CLI tool",
+          "oneOf": [
+            { "type": "string" },
+            {
+              "type": "object",
+              "properties": {
+                "powershell": { "type": "string", "description": "PowerShell install command (Windows)" },
+                "bash": { "type": "string", "description": "Bash install command (Unix/macOS)" },
+                "npm": { "type": "string", "description": "npm install command (fallback)" },
+                "unix": { "type": "string", "description": "Unix-specific install command" },
+                "windows": { "type": "string", "description": "Windows-specific install command" }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "version": {
+          "type": "string",
+          "description": "Command to check if CLI is installed (e.g., 'claude --version')"
+        },
+        "binary": {
+          "type": "string",
+          "description": "Actual binary name if different from CLI name (e.g., 'cursor-agent' for cursor)"
+        },
+        "defaultArgs": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Default arguments to always pass to the CLI"
+        },
+        "ready": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Regex patterns to detect when CLI is ready for input. Set to [] to disable ready check."
+        },
+        "fatal": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Regex patterns to detect fatal errors that should stop execution"
+        },
+        "working": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Regex patterns to detect when CLI is currently processing"
+        },
+        "exitCommands": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Commands to exit the CLI gracefully (e.g., '/exit', '/quit')"
+        },
+        "promptArg": {
+          "type": "string",
+          "description": "How to pass the prompt: 'first-arg', 'last-arg', or a flag like '--prompt'",
+          "examples": ["first-arg", "last-arg", "--prompt", "-p"]
+        },
+        "noEOL": {
+          "type": "boolean",
+          "description": "If true, don't split lines by newline (for CLIs using cursor movement like codex)"
+        },
+        "enter": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Regex patterns that trigger automatic Enter key press"
+        },
+        "enterExclude": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Regex patterns to exclude from auto-enter (even if 'enter' matches)"
+        },
+        "typingRespond": {
+          "type": "object",
+          "description": "Map of responses to type when specific patterns are matched",
+          "additionalProperties": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Regex patterns that trigger this response"
+          },
+          "examples": [
+            { "y\\n": ["Do you want to continue\\?"] },
+            { "1\\n": ["Select an option:"] }
+          ]
+        },
+        "restoreArgs": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Arguments to add when restarting after a crash (e.g., ['--continue'])"
+        },
+        "restartWithoutContinueArg": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Regex patterns for errors that require restart WITHOUT continue args"
+        },
+        "bunx": {
+          "type": "boolean",
+          "description": "Use bunx instead of npx to run the CLI (faster startup)"
+        },
+        "help": {
+          "type": "string",
+          "description": "URL to documentation or help page for this CLI"
+        },
+        "systemPrompt": {
+          "type": "string",
+          "description": "Flag to pass system prompt (e.g., '--append-system-prompt')"
+        },
+        "system": {
+          "type": "string",
+          "description": "System prompt content to inject"
+        },
+        "updateAvailable": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Regex patterns to detect update available messages"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/dist/{SUPPORTED_CLIS-OBl9bioJ.js → SUPPORTED_CLIS-CGHhOLoD.js}

@@ -10118,7 +10118,7 @@ const globalAgentRegistry = new AgentRegistry();
 
 //#endregion
 //#region ts/index.ts
-const config = await import("./agent-yes.config-DgkhZ7eQ.js").then((mod) => mod.default || mod);
+const config = await import("./agent-yes.config-BJbInLnS.js").then((mod) => mod.default || mod);
 const CLIS_CONFIG = config.clis;
 /**
 * Main function to run agent-cli with automatic yes/no responses
@@ -10735,4 +10735,4 @@ const SUPPORTED_CLIS = Object.keys(CLIS_CONFIG);
 
 //#endregion
 export { AgentContext as a, config as i, CLIS_CONFIG as n, PidStore as o, agentYes as r, removeControlCharacters as s, SUPPORTED_CLIS as t };
-//# sourceMappingURL=SUPPORTED_CLIS-OBl9bioJ.js.map
+//# sourceMappingURL=SUPPORTED_CLIS-CGHhOLoD.js.map

package/dist/{agent-yes.config-CUuciqYW.js → agent-yes.config-B0st3al_.js}

@@ -1,5 +1,5 @@
 import { t as logger } from "./logger-DH1Rx9HI.js";
-import { access, mkdir, readFile } from "node:fs/promises";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { parse } from "yaml";
@@ -32,6 +32,8 @@ const CONFIG_EXTENSIONS = [
 	".yml",
 	".yaml"
 ];
+const SCHEMA_URL = "https://raw.githubusercontent.com/snomiao/agent-yes/main/agent-yes.config.schema.json";
+const YAML_SCHEMA_COMMENT = `# yaml-language-server: $schema=${SCHEMA_URL}`;
 /**
 * Check if a file exists
 */
@@ -108,10 +110,86 @@ async function loadCascadingConfig(options = {}) {
 	logger.debug("[config] Merged config from", nonEmptyConfigs.length, "sources");
 	return merged;
 }
+/**
+* Check if a config file has a schema reference
+*/
+function hasSchemaReference(content, ext) {
+	if (ext === ".json") try {
+		return "$schema" in JSON.parse(content);
+	} catch {
+		return false;
+	}
+	return content.includes("yaml-language-server:") && content.includes("$schema");
+}
+/**
+* Add schema reference to a config file content
+*/
+function addSchemaReference(content, ext) {
+	if (ext === ".json") try {
+		const parsed = JSON.parse(content);
+		if ("$schema" in parsed) return content;
+		const withSchema = {
+			$schema: SCHEMA_URL,
+			...parsed
+		};
+		return JSON.stringify(withSchema, null, 2) + "\n";
+	} catch {
+		return content;
+	}
+	if (hasSchemaReference(content, ext)) return content;
+	const lines = content.split("\n");
+	let insertIndex = 0;
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i].trim();
+		if (line && !line.startsWith("#")) {
+			insertIndex = i;
+			break;
+		}
+		insertIndex = i + 1;
+	}
+	lines.splice(insertIndex, 0, YAML_SCHEMA_COMMENT, "");
+	return lines.join("\n");
+}
+/**
+* Ensure schema reference exists in config files
+* Modifies files in-place if they don't have a schema reference
+*/
+async function ensureSchemaInConfigFiles(options = {}) {
+	const projectDir = options.projectDir ?? process.cwd();
+	const homeDir = options.homeDir ?? os.homedir();
+	const modified = [];
+	const skipped = [];
+	for (const dir of [homeDir, projectDir]) {
+		const filepath = await findConfigInDir(dir);
+		if (!filepath) continue;
+		try {
+			const content = await readFile(filepath, "utf-8");
+			const ext = path.extname(filepath).toLowerCase();
+			if (hasSchemaReference(content, ext)) {
+				skipped.push(filepath);
+				logger.debug(`[config] Schema already present in: ${filepath}`);
+				continue;
+			}
+			const newContent = addSchemaReference(content, ext);
+			if (newContent !== content) {
+				await writeFile(filepath, newContent, "utf-8");
+				modified.push(filepath);
+				logger.info(`[config] Added schema reference to: ${filepath}`);
+			}
+		} catch (error) {
+			logger.warn(`[config] Failed to update schema in ${filepath}:`, error);
+		}
+	}
+	return {
+		modified,
+		skipped
+	};
+}
 
 //#endregion
 //#region agent-yes.config.ts
 logger.debug("loading cli-yes.config.ts from " + import.meta.url);
+ensureSchemaInConfigFiles().catch(() => {});
 const configDir = await (async () => {
 	const homeConfigDir = path.resolve(os.homedir(), ".agent-yes");
 	if (await mkdir(homeConfigDir, { recursive: true }).then(() => true).catch(() => false)) {
@@ -252,4 +330,4 @@ function getDefaultConfig() {
 
 //#endregion
 export { agent_yes_config_default as t };
-//# sourceMappingURL=agent-yes.config-CUuciqYW.js.map
+//# sourceMappingURL=agent-yes.config-B0st3al_.js.map

package/dist/{agent-yes.config-DgkhZ7eQ.js → agent-yes.config-BJbInLnS.js}

@@ -1,4 +1,4 @@
 import "./logger-DH1Rx9HI.js";
-import { t as agent_yes_config_default } from "./agent-yes.config-CUuciqYW.js";
+import { t as agent_yes_config_default } from "./agent-yes.config-B0st3al_.js";
 
 export { agent_yes_config_default as default };

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { c as __toESM, i as __commonJSMin, r as require_ms, t as logger } from "./logger-DH1Rx9HI.js";
-import "./agent-yes.config-CUuciqYW.js";
-import { o as PidStore, t as SUPPORTED_CLIS } from "./SUPPORTED_CLIS-OBl9bioJ.js";
+import "./agent-yes.config-B0st3al_.js";
+import { o as PidStore, t as SUPPORTED_CLIS } from "./SUPPORTED_CLIS-CGHhOLoD.js";
 import { createRequire } from "node:module";
 import { argv } from "process";
 import { spawn } from "child_process";
@@ -4505,7 +4505,7 @@ const Yargs = YargsFactory(esm_default);
 //#endregion
 //#region package.json
 var name = "agent-yes";
-var version = "1.47.0";
+var version = "1.49.0";
 
 //#endregion
 //#region ts/parseCliArgs.ts

package/dist/index.js

@@ -1,4 +1,4 @@
 import "./logger-DH1Rx9HI.js";
-import { a as AgentContext, i as config, n as CLIS_CONFIG, r as agentYes, s as removeControlCharacters } from "./SUPPORTED_CLIS-OBl9bioJ.js";
+import { a as AgentContext, i as config, n as CLIS_CONFIG, r as agentYes, s as removeControlCharacters } from "./SUPPORTED_CLIS-CGHhOLoD.js";
 
 export { AgentContext, CLIS_CONFIG, config, agentYes as default, removeControlCharacters };

package/examples/.agent-yes.config.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://raw.githubusercontent.com/snomiao/agent-yes/main/agent-yes.config.schema.json",
+  "configDir": "~/.agent-yes",
+  "logsDir": "~/.agent-yes/logs",
+  "clis": {
+    "claude": {
+      "defaultArgs": ["--verbose"],
+      "ready": ["\\? for shortcuts", "^>[ \\u00A0]"],
+      "enter": ["> 1\\. Yes", "Press Enter to continue"]
+    },
+    "codex": {
+      "defaultArgs": ["--search"],
+      "ready": ["\\? for shortcuts"]
+    }
+  }
+}

package/examples/.agent-yes.config.yaml

@@ -0,0 +1,55 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/snomiao/agent-yes/main/agent-yes.config.schema.json
+
+# agent-yes configuration
+# Place this file in your project root or home directory
+
+configDir: ~/.agent-yes
+logsDir: ~/.agent-yes/logs
+
+clis:
+  # Claude Code configuration
+  claude:
+    defaultArgs:
+      - --verbose
+    # Patterns to detect when Claude is ready for input
+    ready:
+      - "\\? for shortcuts"
+      - "^>[ \\u00A0]"
+    # Patterns that trigger automatic Enter
+    enter:
+      - "> 1\\. Yes"
+      - "Press Enter to continue"
+    # Auto-type responses
+    typingRespond:
+      "1\n":
+        - "Do you want to use this API key\\?"
+
+  # Codex configuration
+  codex:
+    defaultArgs:
+      - --search
+    ready:
+      - "\\? for shortcuts"
+    enter:
+      - "> 1\\. Yes,"
+      - "> 1\\. Approve and run now"
+
+  # Gemini configuration
+  gemini:
+    ready:
+      - "Type your message"
+    enter:
+      - "│ ● 1\\. Yes, allow once"
+    restoreArgs:
+      - --resume
+
+  # Custom CLI example
+  # my-custom-cli:
+  #   binary: my-cli-binary
+  #   install:
+  #     npm: "npm install -g my-cli"
+  #     bash: "curl -fsSL https://example.com/install.sh | bash"
+  #   ready:
+  #     - "Ready>"
+  #   enter:
+  #     - "Confirm\\? \\[y/N\\]"

package/examples/README.md

@@ -0,0 +1,71 @@
+# GCP Cloud Run Demo
+
+## Quick Start
+
+### 1. Set your API key
+
+```bash
+export ANTHROPIC_API_KEY='your-api-key-here'
+```
+
+### 2. Run the deployment script
+
+```bash
+cd demo
+./gcp.sh "hello"
+```
+
+## Usage
+
+The script accepts a command as the first argument:
+
+```bash
+# Run a hello command
+./gcp.sh "hello"
+
+# Run a custom command
+./gcp.sh "list all files in the current directory"
+
+# Default command (if no argument provided)
+./gcp.sh
+```
+
+## Configuration
+
+You can customize the deployment with environment variables:
+
+```bash
+export GCP_PROJECT_ID="my-project"
+export GCP_REGION="asia-northeast1"
+export GCP_JOB_NAME="my-custom-job"
+export GCP_IMAGE="ghcr.io/snomiao/agent-yes:latest"
+
+./gcp.sh "your command here"
+```
+
+## How it works
+
+1. **No TTY needed**: The script configures Cloud Run Jobs to run non-interactively
+2. **API Key authentication**: Uses `ANTHROPIC_API_KEY` environment variable
+3. **Auto-execution**: Creates/updates the job and executes it immediately
+4. **Log streaming**: Automatically streams logs from the execution
+
+## Why Cloud Run Jobs instead of Cloud Run Services?
+
+- **Cloud Run Services**: Require an HTTP server listening on `$PORT` - not suitable for CLI tools
+- **Cloud Run Jobs**: Run to completion and exit - perfect for CLI tools like `agent-yes`
+
+## Alternative: Quick test on Compute Engine
+
+If you need TTY for local testing:
+
+```bash
+# Create a VM
+gcloud compute instances create agent-yes-vm \
+  --machine-type=e2-medium \
+  --zone=us-central1-a
+
+# SSH and run
+gcloud compute ssh agent-yes-vm -- \
+  'docker run -it --rm -e ANTHROPIC_API_KEY=xxx ghcr.io/snomiao/agent-yes:latest claude -- hello'
+```

package/examples/docker.sh

@@ -0,0 +1,2 @@
+# play with docker container
+docker compose run --build -it -v ./:/ws --rm --remove-orphans agent-yes claude-yes -- hello, world

package/examples/gcp.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+
+set -e
+
+# Configuration
+PROJECT_ID="${GCP_PROJECT_ID:-$(gcloud config get-value project)}"
+REGION="${GCP_REGION:-us-central1}"
+JOB_NAME="${GCP_JOB_NAME:-agent-yes-job}"
+IMAGE="${GCP_IMAGE:-ghcr.io/snomiao/agent-yes:latest}"
+COMMAND="${1:-hello}"
+
+# Check for ANTHROPIC_API_KEY
+if [ -z "$ANTHROPIC_API_KEY" ]; then
+  echo "Error: ANTHROPIC_API_KEY environment variable is not set"
+  echo ""
+  echo "IMPORTANT: You need an API key from Anthropic Console (NOT OAuth token)"
+  echo "1. Go to: https://console.anthropic.com/"
+  echo "2. Create an API key (starts with sk-ant-api03-...)"
+  echo "3. Export it: export ANTHROPIC_API_KEY='sk-ant-api03-...'"
+  echo ""
+  echo "Note: The OAuth token from ~/.claude/.credentials.json won't work for Cloud Run"
+  echo ""
+  exit 1
+fi
+
+echo "========================================="
+echo "Google Cloud Run Jobs Deployment"
+echo "========================================="
+echo "Project ID: $PROJECT_ID"
+echo "Region: $REGION"
+echo "Job Name: $JOB_NAME"
+echo "Image: $IMAGE"
+echo "Command: $COMMAND"
+echo "========================================="
+
+# Deploy or update Cloud Run Job
+echo ""
+echo "Deploying to Cloud Run Jobs..."
+if gcloud run jobs describe "$JOB_NAME" --region="$REGION" &>/dev/null; then
+  echo "Job exists, updating..."
+  gcloud run jobs update "$JOB_NAME" \
+    --image="$IMAGE" \
+    --region="$REGION" \
+    --task-timeout=3600 \
+    --max-retries=0 \
+    --set-env-vars="ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY" \
+    --args="claude","--","$COMMAND"
+else
+  echo "Creating new job..."
+  gcloud run jobs create "$JOB_NAME" \
+    --image="$IMAGE" \
+    --region="$REGION" \
+    --task-timeout=3600 \
+    --max-retries=0 \
+    --set-env-vars="ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY" \
+    --args="claude","--","$COMMAND"
+fi
+
+# Execute the job
+echo ""
+echo "Executing the job..."
+EXECUTION_NAME=$(gcloud run jobs execute "$JOB_NAME" --region="$REGION" --format="value(metadata.name)")
+
+echo ""
+echo "Job execution started: $EXECUTION_NAME"
+echo ""
+echo "Streaming logs..."
+echo "========================================="
+gcloud run jobs executions logs tail "$EXECUTION_NAME" --region="$REGION"
+
+echo ""
+echo "========================================="
+echo "View in console:"
+echo "  https://console.cloud.google.com/run/jobs/details/$REGION/$JOB_NAME?project=$PROJECT_ID"
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-yes",
-  "version": "1.47.0",
+  "version": "1.49.0",
   "description": "A wrapper tool that automates interactions with various AI CLI tools by automatically handling common prompts and responses.",
   "keywords": [
     "ai",
@@ -50,7 +50,9 @@
     "ts/*.ts",
     "!dist/**/*.map",
     "dist/**/*.js",
-    "bin"
+    "bin",
+    "agent-yes.config.schema.json",
+    "examples"
   ],
   "type": "module",
   "module": "ts/index.ts",

package/ts/configLoader.spec.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach, afterEach } from "bun:test";
-import { loadCascadingConfig, getConfigPaths } from "./configLoader.ts";
-import { mkdir, writeFile, rm } from "node:fs/promises";
+import { loadCascadingConfig, getConfigPaths, ensureSchemaInConfigFiles } from "./configLoader.ts";
+import { mkdir, writeFile, readFile, rm } from "node:fs/promises";
 import path from "node:path";
 import os from "node:os";
 
@@ -124,4 +124,69 @@ logsDir: /custom/logs
     expect(config.configDir).toBe("/project/config"); // Project takes precedence
     expect(config.logsDir).toBe("/home/logs"); // Home is used when not overridden
   });
+
+  it("should add schema reference to JSON config without one", async () => {
+    const configPath = path.join(testDir, ".agent-yes.config.json");
+    await writeFile(
+      configPath,
+      JSON.stringify({ configDir: "/test" })
+    );
+
+    const result = await ensureSchemaInConfigFiles({ projectDir: testDir, homeDir: testDir });
+    expect(result.modified).toContain(configPath);
+
+    const content = await readFile(configPath, "utf-8");
+    const parsed = JSON.parse(content);
+    expect(parsed.$schema).toContain("agent-yes.config.schema.json");
+    expect(parsed.configDir).toBe("/test"); // Original content preserved
+  });
+
+  it("should add schema comment to YAML config without one", async () => {
+    const configPath = path.join(testDir, ".agent-yes.config.yaml");
+    await writeFile(
+      configPath,
+      `configDir: /test
+clis:
+  claude:
+    defaultArgs:
+      - --verbose
+`
+    );
+
+    const result = await ensureSchemaInConfigFiles({ projectDir: testDir, homeDir: testDir });
+    expect(result.modified).toContain(configPath);
+
+    const content = await readFile(configPath, "utf-8");
+    expect(content).toContain("yaml-language-server:");
+    expect(content).toContain("$schema=");
+    expect(content).toContain("configDir: /test"); // Original content preserved
+  });
+
+  it("should skip JSON config that already has schema", async () => {
+    const configPath = path.join(testDir, ".agent-yes.config.json");
+    const originalContent = JSON.stringify({
+      $schema: "https://example.com/schema.json",
+      configDir: "/test",
+    }, null, 2);
+    await writeFile(configPath, originalContent);
+
+    const result = await ensureSchemaInConfigFiles({ projectDir: testDir, homeDir: testDir });
+    expect(result.skipped).toContain(configPath);
+    expect(result.modified).not.toContain(configPath);
+
+    const content = await readFile(configPath, "utf-8");
+    expect(content).toBe(originalContent); // Unchanged
+  });
+
+  it("should skip YAML config that already has schema comment", async () => {
+    const configPath = path.join(testDir, ".agent-yes.config.yaml");
+    const originalContent = `# yaml-language-server: $schema=https://example.com/schema.json
+configDir: /test
+`;
+    await writeFile(configPath, originalContent);
+
+    const result = await ensureSchemaInConfigFiles({ projectDir: testDir, homeDir: testDir });
+    expect(result.skipped).toContain(configPath);
+    expect(result.modified).not.toContain(configPath);
+  });
 });

package/ts/configLoader.ts

@@ -2,7 +2,7 @@
 //! Supports JSON, YAML, YML formats
 //! Priority: project-dir > home-dir > package-dir
 
-import { readFile, access } from "node:fs/promises";
+import { readFile, writeFile, access } from "node:fs/promises";
 import path from "node:path";
 import os from "node:os";
 import { parse as parseYaml } from "yaml";
@@ -12,6 +12,8 @@ import { deepMixin } from "./utils.ts";
 
 const CONFIG_FILENAME = ".agent-yes.config";
 const CONFIG_EXTENSIONS = [".json", ".yml", ".yaml"] as const;
+const SCHEMA_URL = "https://raw.githubusercontent.com/snomiao/agent-yes/main/agent-yes.config.schema.json";
+const YAML_SCHEMA_COMMENT = `# yaml-language-server: $schema=${SCHEMA_URL}`;
 
 /**
  * Check if a file exists
@@ -146,3 +148,103 @@ export function getConfigPaths(options: ConfigLoadOptions = {}): string[] {
 
   return paths;
 }
+
+/**
+ * Check if a config file has a schema reference
+ */
+function hasSchemaReference(content: string, ext: string): boolean {
+  if (ext === ".json") {
+    try {
+      const parsed = JSON.parse(content);
+      return "$schema" in parsed;
+    } catch {
+      return false;
+    }
+  }
+  // YAML/YML - check for yaml-language-server comment
+  return content.includes("yaml-language-server:") && content.includes("$schema");
+}
+
+/**
+ * Add schema reference to a config file content
+ */
+function addSchemaReference(content: string, ext: string): string {
+  if (ext === ".json") {
+    try {
+      const parsed = JSON.parse(content);
+      if ("$schema" in parsed) {
+        return content; // Already has schema
+      }
+      // Add $schema as first property
+      const withSchema = { $schema: SCHEMA_URL, ...parsed };
+      return JSON.stringify(withSchema, null, 2) + "\n";
+    } catch {
+      return content; // Can't parse, return as-is
+    }
+  }
+
+  // YAML/YML - prepend comment
+  if (hasSchemaReference(content, ext)) {
+    return content; // Already has schema
+  }
+
+  // Add schema comment at the top, preserving any existing comments
+  const lines = content.split("\n");
+
+  // Find the first non-empty, non-comment line to insert before actual content
+  let insertIndex = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line && !line.startsWith("#")) {
+      insertIndex = i;
+      break;
+    }
+    insertIndex = i + 1;
+  }
+
+  // Insert schema comment before the first content line
+  lines.splice(insertIndex, 0, YAML_SCHEMA_COMMENT, "");
+  return lines.join("\n");
+}
+
+/**
+ * Ensure schema reference exists in config files
+ * Modifies files in-place if they don't have a schema reference
+ */
+export async function ensureSchemaInConfigFiles(
+  options: ConfigLoadOptions = {}
+): Promise<{ modified: string[]; skipped: string[] }> {
+  const projectDir = options.projectDir ?? process.cwd();
+  const homeDir = options.homeDir ?? os.homedir();
+
+  const modified: string[] = [];
+  const skipped: string[] = [];
+
+  // Check both project and home directories (not package dir - that's read-only)
+  for (const dir of [homeDir, projectDir]) {
+    const filepath = await findConfigInDir(dir);
+    if (!filepath) continue;
+
+    try {
+      const content = await readFile(filepath, "utf-8");
+      const ext = path.extname(filepath).toLowerCase();
+
+      if (hasSchemaReference(content, ext)) {
+        skipped.push(filepath);
+        logger.debug(`[config] Schema already present in: ${filepath}`);
+        continue;
+      }
+
+      const newContent = addSchemaReference(content, ext);
+      if (newContent !== content) {
+        await writeFile(filepath, newContent, "utf-8");
+        modified.push(filepath);
+        logger.info(`[config] Added schema reference to: ${filepath}`);
+      }
+    } catch (error) {
+      logger.warn(`[config] Failed to update schema in ${filepath}:`, error);
+    }
+  }
+
+  return { modified, skipped };
+}