Auto-load SYSTEM.md as custom system prompt

Closes #309

packages/coding-agent/CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Added
 
+- **Automatic custom system prompt loading**: Pi now auto-loads `SYSTEM.md` files to replace the default system prompt. Project-local `.pi/SYSTEM.md` takes precedence over global `~/.pi/agent/SYSTEM.md`. CLI `--system-prompt` flag overrides both. ([#309](https://github.com/badlogic/pi-mono/issues/309))
 - **Unified `/settings` command**: New settings menu consolidating thinking level, theme, queue mode, auto-compact, show images, hide thinking, and collapse changelog. Replaces individual `/thinking`, `/queue`, `/theme`, `/autocompact`, and `/show-images` commands. ([#310](https://github.com/badlogic/pi-mono/issues/310))
 
 ## [0.29.0] - 2025-12-25

packages/coding-agent/README.md

@@ -23,6 +23,7 @@ Works on Linux, macOS, and Windows (requires bash; see [Windows Setup](#windows-
   - [Branching](#branching)
 - [Configuration](#configuration)
   - [Project Context Files](#project-context-files)
+  - [Custom System Prompt](#custom-system-prompt)
   - [Custom Models and Providers](#custom-models-and-providers)
   - [Themes](#themes)
   - [Custom Slash Commands](#custom-slash-commands)
@@ -377,6 +378,26 @@ Use these for:
 - Prefer async/await over promises
 ```
 
+### Custom System Prompt
+
+Replace the default system prompt entirely by creating a `SYSTEM.md` file:
+
+1. **Project-local:** `.pi/SYSTEM.md` (takes precedence)
+2. **Global:** `~/.pi/agent/SYSTEM.md` (fallback)
+
+This is useful when using pi as different types of agents across repos (coding assistant, personal assistant, domain-specific agent, etc.).
+
+```markdown
+You are a technical writing assistant. Help users write clear documentation.
+
+Focus on:
+- Concise explanations
+- Code examples
+- Proper formatting
+```
+
+The `--system-prompt` CLI flag overrides both files. Use `--append-system-prompt` to add to (rather than replace) the prompt.
+
 ### Custom Models and Providers
 
 Add custom models (Ollama, vLLM, LM Studio, etc.) via `~/.pi/agent/models.json`:

packages/coding-agent/src/main.ts

@@ -8,12 +8,13 @@
 import type { Attachment } from "@mariozechner/pi-agent-core";
 import { supportsXhigh } from "@mariozechner/pi-ai";
 import chalk from "chalk";
+import { existsSync } from "fs";
 import { join } from "path";
 import { type Args, parseArgs, printHelp } from "./cli/args.js";
 import { processFileArguments } from "./cli/file-processor.js";
 import { listModels } from "./cli/list-models.js";
 import { selectSession } from "./cli/session-picker.js";
-import { getAgentDir, getModelsPath, VERSION } from "./config.js";
+import { CONFIG_DIR_NAME, getAgentDir, getModelsPath, VERSION } from "./config.js";
 import type { AgentSession } from "./core/agent-session.js";
 import { AuthStorage } from "./core/auth-storage.js";
 import type { LoadedCustomTool } from "./core/custom-tools/index.js";
@@ -182,6 +183,23 @@ function createSessionManager(parsed: Args, cwd: string): SessionManager | null
 	return null;
 }
 
+/** Discover SYSTEM.md file if no CLI system prompt was provided */
+function discoverSystemPromptFile(): string | undefined {
+	// Check project-local first: .pi/SYSTEM.md
+	const projectPath = join(process.cwd(), CONFIG_DIR_NAME, "SYSTEM.md");
+	if (existsSync(projectPath)) {
+		return projectPath;
+	}
+
+	// Fall back to global: ~/.pi/agent/SYSTEM.md
+	const globalPath = join(getAgentDir(), "SYSTEM.md");
+	if (existsSync(globalPath)) {
+		return globalPath;
+	}
+
+	return undefined;
+}
+
 function buildSessionOptions(
 	parsed: Args,
 	scopedModels: ScopedModel[],
@@ -190,7 +208,9 @@ function buildSessionOptions(
 ): CreateAgentSessionOptions {
 	const options: CreateAgentSessionOptions = {};
 
-	const resolvedSystemPrompt = resolvePromptInput(parsed.systemPrompt, "system prompt");
+	// Auto-discover SYSTEM.md if no CLI system prompt provided
+	const systemPromptSource = parsed.systemPrompt ?? discoverSystemPromptFile();
+	const resolvedSystemPrompt = resolvePromptInput(systemPromptSource, "system prompt");
 	const resolvedAppendPrompt = resolvePromptInput(parsed.appendSystemPrompt, "append system prompt");
 
 	if (sessionManager) {