v0.5.1 — AGENTS.md project file support

kode now auto-loads AGENTS.md from the working directory and appends
its content to the system prompt with a "Project Instructions" header.

- LoadProjectFile() reads AGENTS.md from cwd (silently absent)
- Appended to SystemMessage in kode.New() with clear section marker
- --no-agents CLI flag to skip (or Config.NoProjectFile = true)
- Works for both CLI and programmatic API users

Author: jkyberneees

README.md

@@ -87,6 +87,8 @@ kode run --model gpt-4o "Write a Go test for the loop engine"
 | `--max-iter <n>` | int | `90` | Maximum think→act cycles before giving up |
 | `--thinking <level>` | string | profile default | Reasoning depth — see [Thinking Levels](#thinking-levels). Leave empty for profile/provider default. |
 | `--sandbox` | bool | false | Run all shell commands inside an isolated Docker container |
+| `--no-color` | bool | false | Disable colored terminal output |
+| `--no-agents` | bool | false | Skip loading AGENTS.md from working directory |
 | `--system <prompt>` | string | built-in | Override the system prompt |
 
 ### Examples
@@ -494,6 +496,37 @@ kode run --system "Answer with only the code. No explanations." "Sort a slice of
 
 ---
 
+## Project Instructions (AGENTS.md)
+
+kode automatically loads `AGENTS.md` from the working directory and appends it to the system prompt with a `# Project Instructions` header. Use this file to document project conventions, architecture, style rules, or any context the agent should know.
+
+```markdown
+# Project Conventions
+
+- Use tabs, not spaces
+- Module: github.com/myorg/myproject
+- All errors must be handled, never ignored
+- Go 1.24+, stdlib only
+```
+
+### How it works
+
+1. When `kode.New()` is called, kode looks for `AGENTS.md` in `os.Getwd()`
+2. If found, the content is **appended** to the system message
+3. The default system prompt is preserved — `AGENTS.md` adds project context on top
+4. Programmatic API users also get this automatically
+
+### Skipping AGENTS.md
+
+```bash
+# Ignore AGENTS.md for this one-off task
+kode run --no-agents "Quick status check"
+```
+
+Set `Config.NoProjectFile = true` to skip programmatically.
+
+---
+
 ## Architecture
 
 ```
@@ -568,7 +601,7 @@ Requires Go 1.24+. Zero external test dependencies — tests use `httptest`, `te
 
 | Package | Tests | Focus |
 |---------|-------|-------|
-| `kode` | 25 | Config defaults, API key fallback, thinking passthrough, system message, model profiles, lookup, label, timeout |
+| `kode` | 31 | Config defaults, API key fallback, thinking passthrough, system message, model profiles, lookup, label, timeout, project file (AGENTS.md) |
 | `internal/llm` | 14 | JSON marshaling, thinking/reasoning_effort fields, response parsing, custom timeout |
 | `internal/loop` | 7 | ReAct engine with httptest mock (simple answer, tool calls, max iter, cancellation) |
 | `internal/tool` | 7 | Registry CRUD, Get (found/not found), duplicate detection |

cmd/kode/main.go

@@ -55,6 +55,7 @@ type runFlags struct {
 	MaxIter  int
 	Sandbox  bool
 	NoColor  bool
+	NoAgents bool
 	Task     string
 }
 
@@ -88,6 +89,9 @@ func parseRunFlags(args []string) (runFlags, error) {
 		case "--no-color":
 			f.NoColor = true
 			i++
+		case "--no-agents":
+			f.NoAgents = true
+			i++
 		default:
 			// Not a flag — treat remaining as the task
 			goto done
@@ -117,6 +121,7 @@ Flags:
                        Empty = profile default = provider default.
   --sandbox            Run in isolated Docker container
   --no-color           Disable colored terminal output
+  --no-agents          Skip loading AGENTS.md from working directory
   --system <prompt>    System prompt override`)
 }
 
@@ -157,6 +162,7 @@ func run(args []string) error {
 		BaseURL:        f.BaseURL,
 		MaxIterations:  f.MaxIter,
 		SystemMessage:  f.System,
+		NoProjectFile:  f.NoAgents,
 		Thinking:       f.Thinking,
 		Tools:          tools,
 		SandboxCleanup: sandboxCleanup,

cmd/kode/main_test.go

@@ -200,6 +200,8 @@ func TestPrintUsage(t *testing.T) {
 		"--thinking",
 		"profile default",
 		"--sandbox",
+		"--no-color",
+		"--no-agents",
 		"--system",
 	}
 	for _, req := range required {

kode.go

@@ -69,8 +69,15 @@ type Config struct {
 	MaxIterations int
 
 	// SystemMessage is the system prompt injected at the start of every run.
+	// If AGENTS.md exists in the working directory, its content is appended
+	// automatically. Set NoProjectFile to true to skip this.
 	SystemMessage string
 
+	// NoProjectFile disables automatic loading of AGENTS.md from the
+	// working directory. By default, kode reads AGENTS.md and appends
+	// its content to the system message with a "Project Instructions" header.
+	NoProjectFile bool
+
 	// SandboxCleanup, if set, is called by Agent.Close() to destroy the
 	// Docker sandbox container. Set by the CLI when --sandbox is active.
 	SandboxCleanup func() error
@@ -179,6 +186,25 @@ func ProfileLabel(model string) string {
 	return model
 }
 
+// ── Project File (AGENTS.md) ─────────────────────────────────────────
+
+// ProjectFileName is the name of the project-level instructions file
+// that kode automatically loads from the working directory.
+const ProjectFileName = "AGENTS.md"
+
+// LoadProjectFile reads ProjectFileName from the current working directory.
+// Returns the file content (trimmed) if it exists and is readable.
+// Returns empty string if the file doesn't exist or can't be read.
+// The content is intended to be appended to the system message with a
+// clear header — use it for project conventions, architecture notes, etc.
+func LoadProjectFile() string {
+	data, err := os.ReadFile(ProjectFileName)
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(data))
+}
+
 // ── Defaults ──────────────────────────────────────────────────────────
 
 const (
@@ -240,6 +266,17 @@ func New(cfg Config) (*Agent, error) {
 		tools[i] = &toolAdapter{t}
 	}
 
+	// Load AGENTS.md from the working directory and append to system message
+	if !cfg.NoProjectFile {
+		if projectContent := LoadProjectFile(); projectContent != "" {
+			if cfg.SystemMessage != "" {
+				cfg.SystemMessage += "\n\n# Project Instructions\n\n" + projectContent
+			} else {
+				cfg.SystemMessage = "# Project Instructions\n\n" + projectContent
+			}
+		}
+	}
+
 	registry := tool.NewRegistry(tools)
 	client := llm.New(cfg.BaseURL, cfg.APIKey, cfg.Model, cfg.Thinking, time.Duration(timeout)*time.Second)
 	engine := loop.New(client, registry, cfg.MaxIterations, cfg.SystemMessage, cfg.Renderer, maxContext)

kode_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"os"
+	"strings"
 	"testing"
 )
 
@@ -525,3 +526,121 @@ func TestProfileMaxContext_Unknown(t *testing.T) {
 		t.Errorf("LookupProfile for unknown model = %v, want nil", p)
 	}
 }
+
+
+// ── Project File (AGENTS.md) Tests ───────────────────────────────────
+
+func TestLoadProjectFile_Missing(t *testing.T) {
+	// No AGENTS.md in current dir — should return empty
+	content := LoadProjectFile()
+	if content != "" {
+		t.Errorf("LoadProjectFile() with no file = %q, want empty", content)
+	}
+}
+
+func TestLoadProjectFile_WithFile(t *testing.T) {
+	dir := t.TempDir()
+	cwd, _ := os.Getwd()
+	os.Chdir(dir)
+	defer os.Chdir(cwd)
+
+	if err := os.WriteFile("AGENTS.md", []byte("This project uses Go 1.24."), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	content := LoadProjectFile()
+	if content != "This project uses Go 1.24." {
+		t.Errorf("LoadProjectFile() = %q, want %q", content, "This project uses Go 1.24.")
+	}
+}
+
+func TestLoadProjectFile_TrimsWhitespace(t *testing.T) {
+	dir := t.TempDir()
+	cwd, _ := os.Getwd()
+	os.Chdir(dir)
+	defer os.Chdir(cwd)
+
+	if err := os.WriteFile("AGENTS.md", []byte("  \n  project instructions  \n  "), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	content := LoadProjectFile()
+	if content != "project instructions" {
+		t.Errorf("LoadProjectFile() = %q, want %q", content, "project instructions")
+	}
+}
+
+func TestNew_ProjectFileAppended(t *testing.T) {
+	dir := t.TempDir()
+	cwd, _ := os.Getwd()
+	os.Chdir(dir)
+	defer os.Chdir(cwd)
+
+	if err := os.WriteFile("AGENTS.md", []byte("Use tabs, not spaces."), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	cfg := Config{
+		APIKey:        "sk-test",
+		SystemMessage: "You are a bot.",
+	}
+	agent, err := New(cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(agent.config.SystemMessage, "Use tabs, not spaces.") {
+		t.Errorf("SystemMessage should contain AGENTS.md content, got: %q", agent.config.SystemMessage)
+	}
+	if !strings.Contains(agent.config.SystemMessage, "Project Instructions") {
+		t.Errorf("SystemMessage should have 'Project Instructions' header, got: %q", agent.config.SystemMessage)
+	}
+	if !strings.Contains(agent.config.SystemMessage, "You are a bot.") {
+		t.Errorf("SystemMessage should keep original content, got: %q", agent.config.SystemMessage)
+	}
+}
+
+func TestNew_ProjectFileWithNoOriginalSystem(t *testing.T) {
+	dir := t.TempDir()
+	cwd, _ := os.Getwd()
+	os.Chdir(dir)
+	defer os.Chdir(cwd)
+
+	if err := os.WriteFile("AGENTS.md", []byte("Just these instructions."), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	cfg := Config{
+		APIKey: "sk-test",
+	}
+	agent, err := New(cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if agent.config.SystemMessage != "# Project Instructions\n\nJust these instructions." {
+		t.Errorf("SystemMessage = %q, want 'Project Instructions' + content", agent.config.SystemMessage)
+	}
+}
+
+func TestNew_NoProjectFileOptOut(t *testing.T) {
+	dir := t.TempDir()
+	cwd, _ := os.Getwd()
+	os.Chdir(dir)
+	defer os.Chdir(cwd)
+
+	if err := os.WriteFile("AGENTS.md", []byte("Should not appear."), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	cfg := Config{
+		APIKey:        "sk-test",
+		SystemMessage: "Only this.",
+		NoProjectFile: true,
+	}
+	agent, err := New(cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if agent.config.SystemMessage != "Only this." {
+		t.Errorf("SystemMessage = %q, want original only (no project file)", agent.config.SystemMessage)
+	}
+}