Split main-new.ts into modules: cli/args, cli/file-processor, cli/session-picker, core/system-prompt, core/model-resolver

packages/coding-agent/src/cli/args.ts

@@ -0,0 +1,197 @@
+/**
+ * CLI argument parsing and help display
+ */
+
+import type { ThinkingLevel } from "@mariozechner/pi-agent-core";
+import chalk from "chalk";
+import { allTools, type ToolName } from "../core/tools/index.js";
+import { APP_NAME, CONFIG_DIR_NAME, ENV_AGENT_DIR, getModelsPath } from "../utils/config.js";
+
+export type Mode = "text" | "json" | "rpc";
+
+export interface Args {
+	provider?: string;
+	model?: string;
+	apiKey?: string;
+	systemPrompt?: string;
+	appendSystemPrompt?: string;
+	thinking?: ThinkingLevel;
+	continue?: boolean;
+	resume?: boolean;
+	help?: boolean;
+	mode?: Mode;
+	noSession?: boolean;
+	session?: string;
+	models?: string[];
+	tools?: ToolName[];
+	print?: boolean;
+	export?: string;
+	messages: string[];
+	fileArgs: string[];
+}
+
+const VALID_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+
+export function isValidThinkingLevel(level: string): level is ThinkingLevel {
+	return VALID_THINKING_LEVELS.includes(level as ThinkingLevel);
+}
+
+export function parseArgs(args: string[]): Args {
+	const result: Args = {
+		messages: [],
+		fileArgs: [],
+	};
+
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+
+		if (arg === "--help" || arg === "-h") {
+			result.help = true;
+		} else if (arg === "--mode" && i + 1 < args.length) {
+			const mode = args[++i];
+			if (mode === "text" || mode === "json" || mode === "rpc") {
+				result.mode = mode;
+			}
+		} else if (arg === "--continue" || arg === "-c") {
+			result.continue = true;
+		} else if (arg === "--resume" || arg === "-r") {
+			result.resume = true;
+		} else if (arg === "--provider" && i + 1 < args.length) {
+			result.provider = args[++i];
+		} else if (arg === "--model" && i + 1 < args.length) {
+			result.model = args[++i];
+		} else if (arg === "--api-key" && i + 1 < args.length) {
+			result.apiKey = args[++i];
+		} else if (arg === "--system-prompt" && i + 1 < args.length) {
+			result.systemPrompt = args[++i];
+		} else if (arg === "--append-system-prompt" && i + 1 < args.length) {
+			result.appendSystemPrompt = args[++i];
+		} else if (arg === "--no-session") {
+			result.noSession = true;
+		} else if (arg === "--session" && i + 1 < args.length) {
+			result.session = args[++i];
+		} else if (arg === "--models" && i + 1 < args.length) {
+			result.models = args[++i].split(",").map((s) => s.trim());
+		} else if (arg === "--tools" && i + 1 < args.length) {
+			const toolNames = args[++i].split(",").map((s) => s.trim());
+			const validTools: ToolName[] = [];
+			for (const name of toolNames) {
+				if (name in allTools) {
+					validTools.push(name as ToolName);
+				} else {
+					console.error(
+						chalk.yellow(`Warning: Unknown tool "${name}". Valid tools: ${Object.keys(allTools).join(", ")}`),
+					);
+				}
+			}
+			result.tools = validTools;
+		} else if (arg === "--thinking" && i + 1 < args.length) {
+			const level = args[++i];
+			if (isValidThinkingLevel(level)) {
+				result.thinking = level;
+			} else {
+				console.error(
+					chalk.yellow(
+						`Warning: Invalid thinking level "${level}". Valid values: ${VALID_THINKING_LEVELS.join(", ")}`,
+					),
+				);
+			}
+		} else if (arg === "--print" || arg === "-p") {
+			result.print = true;
+		} else if (arg === "--export" && i + 1 < args.length) {
+			result.export = args[++i];
+		} else if (arg.startsWith("@")) {
+			result.fileArgs.push(arg.slice(1)); // Remove @ prefix
+		} else if (!arg.startsWith("-")) {
+			result.messages.push(arg);
+		}
+	}
+
+	return result;
+}
+
+export function printHelp(): void {
+	console.log(`${chalk.bold(APP_NAME)} - AI coding assistant with read, bash, edit, write tools
+
+${chalk.bold("Usage:")}
+  ${APP_NAME} [options] [@files...] [messages...]
+
+${chalk.bold("Options:")}
+  --provider <name>              Provider name (default: google)
+  --model <id>                   Model ID (default: gemini-2.5-flash)
+  --api-key <key>                API key (defaults to env vars)
+  --system-prompt <text>         System prompt (default: coding assistant prompt)
+  --append-system-prompt <text>  Append text or file contents to the system prompt
+  --mode <mode>                  Output mode: text (default), json, or rpc
+  --print, -p                    Non-interactive mode: process prompt and exit
+  --continue, -c                 Continue previous session
+  --resume, -r                   Select a session to resume
+  --session <path>               Use specific session file
+  --no-session                   Don't save session (ephemeral)
+  --models <patterns>            Comma-separated model patterns for quick cycling with Ctrl+P
+  --tools <tools>                Comma-separated list of tools to enable (default: read,bash,edit,write)
+                                 Available: read, bash, edit, write, grep, find, ls
+  --thinking <level>             Set thinking level: off, minimal, low, medium, high, xhigh
+  --export <file>                Export session file to HTML and exit
+  --help, -h                     Show this help
+
+${chalk.bold("Examples:")}
+  # Interactive mode
+  ${APP_NAME}
+
+  # Interactive mode with initial prompt
+  ${APP_NAME} "List all .ts files in src/"
+
+  # Include files in initial message
+  ${APP_NAME} @prompt.md @image.png "What color is the sky?"
+
+  # Non-interactive mode (process and exit)
+  ${APP_NAME} -p "List all .ts files in src/"
+
+  # Multiple messages (interactive)
+  ${APP_NAME} "Read package.json" "What dependencies do we have?"
+
+  # Continue previous session
+  ${APP_NAME} --continue "What did we discuss?"
+
+  # Use different model
+  ${APP_NAME} --provider openai --model gpt-4o-mini "Help me refactor this code"
+
+  # Limit model cycling to specific models
+  ${APP_NAME} --models claude-sonnet,claude-haiku,gpt-4o
+
+  # Cycle models with fixed thinking levels
+  ${APP_NAME} --models sonnet:high,haiku:low
+
+  # Start with a specific thinking level
+  ${APP_NAME} --thinking high "Solve this complex problem"
+
+  # Read-only mode (no file modifications possible)
+  ${APP_NAME} --tools read,grep,find,ls -p "Review the code in src/"
+
+  # Export a session file to HTML
+  ${APP_NAME} --export ~/${CONFIG_DIR_NAME}/agent/sessions/--path--/session.jsonl
+  ${APP_NAME} --export session.jsonl output.html
+
+${chalk.bold("Environment Variables:")}
+  ANTHROPIC_API_KEY       - Anthropic Claude API key
+  ANTHROPIC_OAUTH_TOKEN   - Anthropic OAuth token (alternative to API key)
+  OPENAI_API_KEY          - OpenAI GPT API key
+  GEMINI_API_KEY          - Google Gemini API key
+  GROQ_API_KEY            - Groq API key
+  CEREBRAS_API_KEY        - Cerebras API key
+  XAI_API_KEY             - xAI Grok API key
+  OPENROUTER_API_KEY      - OpenRouter API key
+  ZAI_API_KEY             - ZAI API key
+  ${ENV_AGENT_DIR.padEnd(23)} - Session storage directory (default: ~/${CONFIG_DIR_NAME}/agent)
+
+${chalk.bold("Available Tools (default: read, bash, edit, write):")}
+  read   - Read file contents
+  bash   - Execute bash commands
+  edit   - Edit files with find/replace
+  write  - Write files (creates/overwrites)
+  grep   - Search file contents (read-only, off by default)
+  find   - Find files by glob pattern (read-only, off by default)
+  ls     - List directory contents (read-only, off by default)
+`);
+}

packages/coding-agent/src/cli/file-processor.ts

@@ -0,0 +1,99 @@
+/**
+ * Process @file CLI arguments into text content and image attachments
+ */
+
+import type { Attachment } from "@mariozechner/pi-agent-core";
+import chalk from "chalk";
+import { existsSync, readFileSync, statSync } from "fs";
+import { homedir } from "os";
+import { extname, resolve } from "path";
+
+/** Map of file extensions to MIME types for common image formats */
+const IMAGE_MIME_TYPES: Record<string, string> = {
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".png": "image/png",
+	".gif": "image/gif",
+	".webp": "image/webp",
+};
+
+/** Check if a file is an image based on its extension, returns MIME type or null */
+function isImageFile(filePath: string): string | null {
+	const ext = extname(filePath).toLowerCase();
+	return IMAGE_MIME_TYPES[ext] || null;
+}
+
+/** Expand ~ to home directory */
+function expandPath(filePath: string): string {
+	if (filePath === "~") {
+		return homedir();
+	}
+	if (filePath.startsWith("~/")) {
+		return homedir() + filePath.slice(1);
+	}
+	return filePath;
+}
+
+export interface ProcessedFiles {
+	textContent: string;
+	imageAttachments: Attachment[];
+}
+
+/** Process @file arguments into text content and image attachments */
+export function processFileArguments(fileArgs: string[]): ProcessedFiles {
+	let textContent = "";
+	const imageAttachments: Attachment[] = [];
+
+	for (const fileArg of fileArgs) {
+		// Expand and resolve path
+		const expandedPath = expandPath(fileArg);
+		const absolutePath = resolve(expandedPath);
+
+		// Check if file exists
+		if (!existsSync(absolutePath)) {
+			console.error(chalk.red(`Error: File not found: ${absolutePath}`));
+			process.exit(1);
+		}
+
+		// Check if file is empty
+		const stats = statSync(absolutePath);
+		if (stats.size === 0) {
+			// Skip empty files
+			continue;
+		}
+
+		const mimeType = isImageFile(absolutePath);
+
+		if (mimeType) {
+			// Handle image file
+			const content = readFileSync(absolutePath);
+			const base64Content = content.toString("base64");
+
+			const attachment: Attachment = {
+				id: `file-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
+				type: "image",
+				fileName: absolutePath.split("/").pop() || absolutePath,
+				mimeType,
+				size: stats.size,
+				content: base64Content,
+			};
+
+			imageAttachments.push(attachment);
+
+			// Add text reference to image
+			textContent += `<file name="${absolutePath}"></file>\n`;
+		} else {
+			// Handle text file
+			try {
+				const content = readFileSync(absolutePath, "utf-8");
+				textContent += `<file name="${absolutePath}">\n${content}\n</file>\n`;
+			} catch (error: unknown) {
+				const message = error instanceof Error ? error.message : String(error);
+				console.error(chalk.red(`Error: Could not read file ${absolutePath}: ${message}`));
+				process.exit(1);
+			}
+		}
+	}
+
+	return { textContent, imageAttachments };
+}

packages/coding-agent/src/cli/session-picker.ts

@@ -0,0 +1,37 @@
+/**
+ * TUI session selector for --resume flag
+ */
+
+import { ProcessTerminal, TUI } from "@mariozechner/pi-tui";
+import type { SessionManager } from "../core/session-manager.js";
+import { SessionSelectorComponent } from "../modes/interactive/components/session-selector.js";
+
+/** Show TUI session selector and return selected session path or null if cancelled */
+export async function selectSession(sessionManager: SessionManager): Promise<string | null> {
+	return new Promise((resolve) => {
+		const ui = new TUI(new ProcessTerminal());
+		let resolved = false;
+
+		const selector = new SessionSelectorComponent(
+			sessionManager,
+			(path: string) => {
+				if (!resolved) {
+					resolved = true;
+					ui.stop();
+					resolve(path);
+				}
+			},
+			() => {
+				if (!resolved) {
+					resolved = true;
+					ui.stop();
+					resolve(null);
+				}
+			},
+		);
+
+		ui.addChild(selector);
+		ui.setFocus(selector.getSessionList());
+		ui.start();
+	});
+}

packages/coding-agent/src/core/model-resolver.ts

@@ -0,0 +1,317 @@
+/**
+ * Model resolution, scoping, and initial selection
+ */
+
+import type { ThinkingLevel } from "@mariozechner/pi-agent-core";
+import type { Api, KnownProvider, Model } from "@mariozechner/pi-ai";
+import chalk from "chalk";
+import { isValidThinkingLevel } from "../cli/args.js";
+import { findModel, getApiKeyForModel, getAvailableModels } from "./model-config.js";
+import type { SettingsManager } from "./settings-manager.js";
+
+/** Default model IDs for each known provider */
+export const defaultModelPerProvider: Record<KnownProvider, string> = {
+	anthropic: "claude-sonnet-4-5",
+	openai: "gpt-5.1-codex",
+	google: "gemini-2.5-pro",
+	openrouter: "openai/gpt-5.1-codex",
+	xai: "grok-4-fast-non-reasoning",
+	groq: "openai/gpt-oss-120b",
+	cerebras: "zai-glm-4.6",
+	zai: "glm-4.6",
+};
+
+export interface ScopedModel {
+	model: Model<Api>;
+	thinkingLevel: ThinkingLevel;
+}
+
+/**
+ * Resolve model patterns to actual Model objects with optional thinking levels
+ * Format: "pattern:level" where :level is optional
+ * For each pattern, finds all matching models and picks the best version:
+ * 1. Prefer alias (e.g., claude-sonnet-4-5) over dated versions (claude-sonnet-4-5-20250929)
+ * 2. If no alias, pick the latest dated version
+ */
+export async function resolveModelScope(patterns: string[]): Promise<ScopedModel[]> {
+	const { models: availableModels, error } = await getAvailableModels();
+
+	if (error) {
+		console.warn(chalk.yellow(`Warning: Error loading models: ${error}`));
+		return [];
+	}
+
+	const scopedModels: ScopedModel[] = [];
+
+	for (const pattern of patterns) {
+		// Parse pattern:level format
+		const parts = pattern.split(":");
+		const modelPattern = parts[0];
+		let thinkingLevel: ThinkingLevel = "off";
+
+		if (parts.length > 1) {
+			const level = parts[1];
+			if (isValidThinkingLevel(level)) {
+				thinkingLevel = level;
+			} else {
+				console.warn(
+					chalk.yellow(`Warning: Invalid thinking level "${level}" in pattern "${pattern}". Using "off" instead.`),
+				);
+			}
+		}
+
+		// Check for provider/modelId format (provider is everything before the first /)
+		const slashIndex = modelPattern.indexOf("/");
+		if (slashIndex !== -1) {
+			const provider = modelPattern.substring(0, slashIndex);
+			const modelId = modelPattern.substring(slashIndex + 1);
+			const providerMatch = availableModels.find(
+				(m) => m.provider.toLowerCase() === provider.toLowerCase() && m.id.toLowerCase() === modelId.toLowerCase(),
+			);
+			if (providerMatch) {
+				if (
+					!scopedModels.find(
+						(sm) => sm.model.id === providerMatch.id && sm.model.provider === providerMatch.provider,
+					)
+				) {
+					scopedModels.push({ model: providerMatch, thinkingLevel });
+				}
+				continue;
+			}
+			// No exact provider/model match - fall through to other matching
+		}
+
+		// Check for exact ID match (case-insensitive)
+		const exactMatch = availableModels.find((m) => m.id.toLowerCase() === modelPattern.toLowerCase());
+		if (exactMatch) {
+			// Exact match found - use it directly
+			if (!scopedModels.find((sm) => sm.model.id === exactMatch.id && sm.model.provider === exactMatch.provider)) {
+				scopedModels.push({ model: exactMatch, thinkingLevel });
+			}
+			continue;
+		}
+
+		// No exact match - fall back to partial matching
+		const matches = availableModels.filter(
+			(m) =>
+				m.id.toLowerCase().includes(modelPattern.toLowerCase()) ||
+				m.name?.toLowerCase().includes(modelPattern.toLowerCase()),
+		);
+
+		if (matches.length === 0) {
+			console.warn(chalk.yellow(`Warning: No models match pattern "${modelPattern}"`));
+			continue;
+		}
+
+		// Helper to check if a model ID looks like an alias (no date suffix)
+		// Dates are typically in format: -20241022 or -20250929
+		const isAlias = (id: string): boolean => {
+			// Check if ID ends with -latest
+			if (id.endsWith("-latest")) return true;
+
+			// Check if ID ends with a date pattern (-YYYYMMDD)
+			const datePattern = /-\d{8}$/;
+			return !datePattern.test(id);
+		};
+
+		// Separate into aliases and dated versions
+		const aliases = matches.filter((m) => isAlias(m.id));
+		const datedVersions = matches.filter((m) => !isAlias(m.id));
+
+		let bestMatch: Model<Api>;
+
+		if (aliases.length > 0) {
+			// Prefer alias - if multiple aliases, pick the one that sorts highest
+			aliases.sort((a, b) => b.id.localeCompare(a.id));
+			bestMatch = aliases[0];
+		} else {
+			// No alias found, pick latest dated version
+			datedVersions.sort((a, b) => b.id.localeCompare(a.id));
+			bestMatch = datedVersions[0];
+		}
+
+		// Avoid duplicates
+		if (!scopedModels.find((sm) => sm.model.id === bestMatch.id && sm.model.provider === bestMatch.provider)) {
+			scopedModels.push({ model: bestMatch, thinkingLevel });
+		}
+	}
+
+	return scopedModels;
+}
+
+export interface InitialModelResult {
+	model: Model<Api> | null;
+	thinkingLevel: ThinkingLevel;
+	fallbackMessage: string | null;
+}
+
+/**
+ * Find the initial model to use based on priority:
+ * 1. CLI args (provider + model)
+ * 2. First model from scoped models (if not continuing/resuming)
+ * 3. Restored from session (if continuing/resuming)
+ * 4. Saved default from settings
+ * 5. First available model with valid API key
+ */
+export async function findInitialModel(options: {
+	cliProvider?: string;
+	cliModel?: string;
+	scopedModels: ScopedModel[];
+	isContinuing: boolean;
+	settingsManager: SettingsManager;
+}): Promise<InitialModelResult> {
+	const { cliProvider, cliModel, scopedModels, isContinuing, settingsManager } = options;
+
+	let model: Model<Api> | null = null;
+	let thinkingLevel: ThinkingLevel = "off";
+
+	// 1. CLI args take priority
+	if (cliProvider && cliModel) {
+		const { model: found, error } = findModel(cliProvider, cliModel);
+		if (error) {
+			console.error(chalk.red(error));
+			process.exit(1);
+		}
+		if (!found) {
+			console.error(chalk.red(`Model ${cliProvider}/${cliModel} not found`));
+			process.exit(1);
+		}
+		return { model: found, thinkingLevel: "off", fallbackMessage: null };
+	}
+
+	// 2. Use first model from scoped models (skip if continuing/resuming)
+	if (scopedModels.length > 0 && !isContinuing) {
+		return {
+			model: scopedModels[0].model,
+			thinkingLevel: scopedModels[0].thinkingLevel,
+			fallbackMessage: null,
+		};
+	}
+
+	// 3. Try saved default from settings
+	const defaultProvider = settingsManager.getDefaultProvider();
+	const defaultModelId = settingsManager.getDefaultModel();
+	if (defaultProvider && defaultModelId) {
+		const { model: found, error } = findModel(defaultProvider, defaultModelId);
+		if (error) {
+			console.error(chalk.red(error));
+			process.exit(1);
+		}
+		if (found) {
+			model = found;
+			// Also load saved thinking level
+			const savedThinking = settingsManager.getDefaultThinkingLevel();
+			if (savedThinking) {
+				thinkingLevel = savedThinking;
+			}
+			return { model, thinkingLevel, fallbackMessage: null };
+		}
+	}
+
+	// 4. Try first available model with valid API key
+	const { models: availableModels, error } = await getAvailableModels();
+
+	if (error) {
+		console.error(chalk.red(error));
+		process.exit(1);
+	}
+
+	if (availableModels.length > 0) {
+		// Try to find a default model from known providers
+		for (const provider of Object.keys(defaultModelPerProvider) as KnownProvider[]) {
+			const defaultId = defaultModelPerProvider[provider];
+			const match = availableModels.find((m) => m.provider === provider && m.id === defaultId);
+			if (match) {
+				return { model: match, thinkingLevel: "off", fallbackMessage: null };
+			}
+		}
+
+		// If no default found, use first available
+		return { model: availableModels[0], thinkingLevel: "off", fallbackMessage: null };
+	}
+
+	// 5. No model found
+	return { model: null, thinkingLevel: "off", fallbackMessage: null };
+}
+
+/**
+ * Restore model from session, with fallback to available models
+ */
+export async function restoreModelFromSession(
+	savedProvider: string,
+	savedModelId: string,
+	currentModel: Model<Api> | null,
+	shouldPrintMessages: boolean,
+): Promise<{ model: Model<Api> | null; fallbackMessage: string | null }> {
+	const { model: restoredModel, error } = findModel(savedProvider, savedModelId);
+
+	if (error) {
+		console.error(chalk.red(error));
+		process.exit(1);
+	}
+
+	// Check if restored model exists and has a valid API key
+	const hasApiKey = restoredModel ? !!(await getApiKeyForModel(restoredModel)) : false;
+
+	if (restoredModel && hasApiKey) {
+		if (shouldPrintMessages) {
+			console.log(chalk.dim(`Restored model: ${savedProvider}/${savedModelId}`));
+		}
+		return { model: restoredModel, fallbackMessage: null };
+	}
+
+	// Model not found or no API key - fall back
+	const reason = !restoredModel ? "model no longer exists" : "no API key available";
+
+	if (shouldPrintMessages) {
+		console.error(chalk.yellow(`Warning: Could not restore model ${savedProvider}/${savedModelId} (${reason}).`));
+	}
+
+	// If we already have a model, use it as fallback
+	if (currentModel) {
+		if (shouldPrintMessages) {
+			console.log(chalk.dim(`Falling back to: ${currentModel.provider}/${currentModel.id}`));
+		}
+		return {
+			model: currentModel,
+			fallbackMessage: `Could not restore model ${savedProvider}/${savedModelId} (${reason}). Using ${currentModel.provider}/${currentModel.id}.`,
+		};
+	}
+
+	// Try to find any available model
+	const { models: availableModels, error: availableError } = await getAvailableModels();
+	if (availableError) {
+		console.error(chalk.red(availableError));
+		process.exit(1);
+	}
+
+	if (availableModels.length > 0) {
+		// Try to find a default model from known providers
+		let fallbackModel: Model<Api> | null = null;
+		for (const provider of Object.keys(defaultModelPerProvider) as KnownProvider[]) {
+			const defaultId = defaultModelPerProvider[provider];
+			const match = availableModels.find((m) => m.provider === provider && m.id === defaultId);
+			if (match) {
+				fallbackModel = match;
+				break;
+			}
+		}
+
+		// If no default found, use first available
+		if (!fallbackModel) {
+			fallbackModel = availableModels[0];
+		}
+
+		if (shouldPrintMessages) {
+			console.log(chalk.dim(`Falling back to: ${fallbackModel.provider}/${fallbackModel.id}`));
+		}
+
+		return {
+			model: fallbackModel,
+			fallbackMessage: `Could not restore model ${savedProvider}/${savedModelId} (${reason}). Using ${fallbackModel.provider}/${fallbackModel.id}.`,
+		};
+	}
+
+	// No models available
+	return { model: null, fallbackMessage: null };
+}

packages/coding-agent/src/core/system-prompt.ts

@@ -0,0 +1,247 @@
+/**
+ * System prompt construction and project context loading
+ */
+
+import chalk from "chalk";
+import { existsSync, readFileSync } from "fs";
+import { join, resolve } from "path";
+import { getAgentDir, getReadmePath } from "../utils/config.js";
+import type { ToolName } from "./tools/index.js";
+
+/** Tool descriptions for system prompt */
+const toolDescriptions: Record<ToolName, string> = {
+	read: "Read file contents",
+	bash: "Execute bash commands (ls, grep, find, etc.)",
+	edit: "Make surgical edits to files (find exact text and replace)",
+	write: "Create or overwrite files",
+	grep: "Search file contents for patterns (respects .gitignore)",
+	find: "Find files by glob pattern (respects .gitignore)",
+	ls: "List directory contents",
+};
+
+/** Resolve input as file path or literal string */
+function resolvePromptInput(input: string | undefined, description: string): string | undefined {
+	if (!input) {
+		return undefined;
+	}
+
+	if (existsSync(input)) {
+		try {
+			return readFileSync(input, "utf-8");
+		} catch (error) {
+			console.error(chalk.yellow(`Warning: Could not read ${description} file ${input}: ${error}`));
+			return input;
+		}
+	}
+
+	return input;
+}
+
+/** Look for AGENTS.md or CLAUDE.md in a directory (prefers AGENTS.md) */
+function loadContextFileFromDir(dir: string): { path: string; content: string } | null {
+	const candidates = ["AGENTS.md", "CLAUDE.md"];
+	for (const filename of candidates) {
+		const filePath = join(dir, filename);
+		if (existsSync(filePath)) {
+			try {
+				return {
+					path: filePath,
+					content: readFileSync(filePath, "utf-8"),
+				};
+			} catch (error) {
+				console.error(chalk.yellow(`Warning: Could not read ${filePath}: ${error}`));
+			}
+		}
+	}
+	return null;
+}
+
+/**
+ * Load all project context files in order:
+ * 1. Global: ~/{CONFIG_DIR_NAME}/agent/AGENTS.md or CLAUDE.md
+ * 2. Parent directories (top-most first) down to cwd
+ * Each returns {path, content} for separate messages
+ */
+export function loadProjectContextFiles(): Array<{ path: string; content: string }> {
+	const contextFiles: Array<{ path: string; content: string }> = [];
+
+	// 1. Load global context from ~/{CONFIG_DIR_NAME}/agent/
+	const globalContextDir = getAgentDir();
+	const globalContext = loadContextFileFromDir(globalContextDir);
+	if (globalContext) {
+		contextFiles.push(globalContext);
+	}
+
+	// 2. Walk up from cwd to root, collecting all context files
+	const cwd = process.cwd();
+	const ancestorContextFiles: Array<{ path: string; content: string }> = [];
+
+	let currentDir = cwd;
+	const root = resolve("/");
+
+	while (true) {
+		const contextFile = loadContextFileFromDir(currentDir);
+		if (contextFile) {
+			// Add to beginning so we get top-most parent first
+			ancestorContextFiles.unshift(contextFile);
+		}
+
+		// Stop if we've reached root
+		if (currentDir === root) break;
+
+		// Move up one directory
+		const parentDir = resolve(currentDir, "..");
+		if (parentDir === currentDir) break; // Safety check
+		currentDir = parentDir;
+	}
+
+	// Add ancestor files in order (top-most → cwd)
+	contextFiles.push(...ancestorContextFiles);
+
+	return contextFiles;
+}
+
+/** Build the system prompt with tools, guidelines, and context */
+export function buildSystemPrompt(
+	customPrompt?: string,
+	selectedTools?: ToolName[],
+	appendSystemPrompt?: string,
+): string {
+	const resolvedCustomPrompt = resolvePromptInput(customPrompt, "system prompt");
+	const resolvedAppendPrompt = resolvePromptInput(appendSystemPrompt, "append system prompt");
+
+	const now = new Date();
+	const dateTime = now.toLocaleString("en-US", {
+		weekday: "long",
+		year: "numeric",
+		month: "long",
+		day: "numeric",
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit",
+		timeZoneName: "short",
+	});
+
+	const appendSection = resolvedAppendPrompt ? `\n\n${resolvedAppendPrompt}` : "";
+
+	if (resolvedCustomPrompt) {
+		let prompt = resolvedCustomPrompt;
+
+		if (appendSection) {
+			prompt += appendSection;
+		}
+
+		// Append project context files
+		const contextFiles = loadProjectContextFiles();
+		if (contextFiles.length > 0) {
+			prompt += "\n\n# Project Context\n\n";
+			prompt += "The following project context files have been loaded:\n\n";
+			for (const { path: filePath, content } of contextFiles) {
+				prompt += `## ${filePath}\n\n${content}\n\n`;
+			}
+		}
+
+		// Add date/time and working directory last
+		prompt += `\nCurrent date and time: ${dateTime}`;
+		prompt += `\nCurrent working directory: ${process.cwd()}`;
+
+		return prompt;
+	}
+
+	// Get absolute path to README.md
+	const readmePath = getReadmePath();
+
+	// Build tools list based on selected tools
+	const tools = selectedTools || (["read", "bash", "edit", "write"] as ToolName[]);
+	const toolsList = tools.map((t) => `- ${t}: ${toolDescriptions[t]}`).join("\n");
+
+	// Build guidelines based on which tools are actually available
+	const guidelinesList: string[] = [];
+
+	const hasBash = tools.includes("bash");
+	const hasEdit = tools.includes("edit");
+	const hasWrite = tools.includes("write");
+	const hasGrep = tools.includes("grep");
+	const hasFind = tools.includes("find");
+	const hasLs = tools.includes("ls");
+	const hasRead = tools.includes("read");
+
+	// Read-only mode notice (no bash, edit, or write)
+	if (!hasBash && !hasEdit && !hasWrite) {
+		guidelinesList.push("You are in READ-ONLY mode - you cannot modify files or execute arbitrary commands");
+	}
+
+	// Bash without edit/write = read-only bash mode
+	if (hasBash && !hasEdit && !hasWrite) {
+		guidelinesList.push(
+			"Use bash ONLY for read-only operations (git log, gh issue view, curl, etc.) - do NOT modify any files",
+		);
+	}
+
+	// File exploration guidelines
+	if (hasBash && !hasGrep && !hasFind && !hasLs) {
+		guidelinesList.push("Use bash for file operations like ls, grep, find");
+	} else if (hasBash && (hasGrep || hasFind || hasLs)) {
+		guidelinesList.push("Prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)");
+	}
+
+	// Read before edit guideline
+	if (hasRead && hasEdit) {
+		guidelinesList.push("Use read to examine files before editing");
+	}
+
+	// Edit guideline
+	if (hasEdit) {
+		guidelinesList.push("Use edit for precise changes (old text must match exactly)");
+	}
+
+	// Write guideline
+	if (hasWrite) {
+		guidelinesList.push("Use write only for new files or complete rewrites");
+	}
+
+	// Output guideline (only when actually writing/executing)
+	if (hasEdit || hasWrite) {
+		guidelinesList.push(
+			"When summarizing your actions, output plain text directly - do NOT use cat or bash to display what you did",
+		);
+	}
+
+	// Always include these
+	guidelinesList.push("Be concise in your responses");
+	guidelinesList.push("Show file paths clearly when working with files");
+
+	const guidelines = guidelinesList.map((g) => `- ${g}`).join("\n");
+
+	let prompt = `You are an expert coding assistant. You help users with coding tasks by reading files, executing commands, editing code, and writing new files.
+
+Available tools:
+${toolsList}
+
+Guidelines:
+${guidelines}
+
+Documentation:
+- Your own documentation (including custom model setup and theme creation) is at: ${readmePath}
+- Read it when users ask about features, configuration, or setup, and especially if the user asks you to add a custom model or provider, or create a custom theme.`;
+
+	if (appendSection) {
+		prompt += appendSection;
+	}
+
+	// Append project context files
+	const contextFiles = loadProjectContextFiles();
+	if (contextFiles.length > 0) {
+		prompt += "\n\n# Project Context\n\n";
+		prompt += "The following project context files have been loaded:\n\n";
+		for (const { path: filePath, content } of contextFiles) {
+			prompt += `## ${filePath}\n\n${content}\n\n`;
+		}
+	}
+
+	// Add date/time and working directory last
+	prompt += `\nCurrent date and time: ${dateTime}`;
+	prompt += `\nCurrent working directory: ${process.cwd()}`;
+
+	return prompt;
+}