Feature/model override config

README.md

@@ -52,6 +52,7 @@ Claude Code (LLM Runtime)
 Agent Binary
   +-- --custom-instructions  -> system prompt
   +-- serve-mcp              -> MCP server (tools + memory)
+  +-- config get|set|reset   -> runtime config overrides
   +-- --version              -> semver
   +-- --describe             -> JSON manifest
   +-- validate               -> check wiring
@@ -115,6 +116,26 @@ agentfile install github.com/you/my-agent
 | **Distribution** | Copy the file | Folder copy | N/A | `agentfile install` from anywhere |
 | **Context isolation** | No | No | Yes | No |
 | **Cost model** | One-time | Text in context | Baseline per call | Marginal per turn |
+| **Runtime config** | Edit the file | N/A | N/A | `config set model opus` — override without rebuilding |
+
+## Runtime Configuration
+
+Agents ship with compiled defaults, but consumers can override settings without rebuilding:
+
+```bash
+# Override the model hint at install time
+agentfile install --model opus github.com/acme/my-agent
+
+# Or change it later
+./my-agent config set model opus
+./my-agent config get model          # opus (override)
+./my-agent config reset model        # revert to compiled default
+
+# Show all config (compiled defaults + overrides)
+./my-agent config get
+```
+
+Overrides are stored at `~/.agentfile/<name>/config.yaml`. The model hint is surfaced to the runtime via MCP server instructions. See the [model-override example](examples/model-override/) for a complete setup.
 
 ## Install
 

cmd/agentfile/install.go

@@ -8,13 +8,15 @@ import (
 	"time"
 
 	"github.com/spf13/cobra"
+	"github.com/teabranch/agentfile/pkg/config"
 	"github.com/teabranch/agentfile/pkg/fsutil"
 	"github.com/teabranch/agentfile/pkg/github"
 	"github.com/teabranch/agentfile/pkg/registry"
 )
 
 func newInstallCommand() *cobra.Command {
 	var global bool
+	var modelOverride string
 
 	cmd := &cobra.Command{
 		Use:   "install <agent-name | github.com/owner/repo[/agent][@version]>",
@@ -29,17 +31,42 @@ Remote install (from GitHub Releases):
   agentfile install github.com/owner/repo/agent@1.0.0
 
 By default, installs to .agentfile/bin/ (project-local) and updates .mcp.json.
-With --global, installs to /usr/local/bin/ and updates ~/.claude/mcp.json.`,
+With --global, installs to /usr/local/bin/ and updates ~/.claude/mcp.json.
+
+Override settings at install time:
+  agentfile install --model gpt-5 github.com/owner/repo/agent`,
 		Args: cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
+			var agentName string
 			if github.IsRemoteRef(args[0]) {
-				return runRemoteInstall(args[0], global)
+				parsed, err := github.ParseRef(args[0])
+				if err != nil {
+					return err
+				}
+				agentName = parsed.Agent
+				if err := runRemoteInstall(args[0], global); err != nil {
+					return err
+				}
+			} else {
+				agentName = args[0]
+				if err := runLocalInstall(args[0], global); err != nil {
+					return err
+				}
+			}
+
+			// Write config override if --model was specified.
+			if modelOverride != "" {
+				if err := config.WriteField(agentName, "model", modelOverride); err != nil {
+					return fmt.Errorf("writing model override: %w", err)
+				}
+				fmt.Printf("Set model override: %s → %s\n", agentName, modelOverride)
 			}
-			return runLocalInstall(args[0], global)
+			return nil
 		},
 	}
 
 	cmd.Flags().BoolVarP(&global, "global", "g", false, "Install globally to /usr/local/bin")
+	cmd.Flags().StringVar(&modelOverride, "model", "", "Override the agent's model in ~/.agentfile/<name>/config.yaml")
 
 	return cmd
 }

docs/concepts.md

@@ -15,6 +15,7 @@ Agent Binary (Agentfile)
   +-- --custom-instructions  -> system prompt text
   +-- run-tool <name>        -> execute a tool (CLI or builtin)
   +-- memory read|write|list|delete|append  -> persistent state
+  +-- config get|set|reset|path            -> runtime config overrides
   +-- serve-mcp              -> MCP-over-stdio server
   +-- validate               -> check agent wiring
 
@@ -89,6 +90,7 @@ agent.Execute()        Wire Cobra CLI, register tools, init memory
        +-- cli.NewServeMCPCommand()  Add serve-mcp subcommand
        +-- cli.NewValidateCommand()  Add validate subcommand
        +-- cli.NewMemoryCommand()    Add memory subcommand group (if enabled)
+       +-- cli.NewConfigCommand()    Add config subcommand (get/set/reset/path)
        |
        v
 cmd.Execute()          Run the Cobra command tree
@@ -208,6 +210,28 @@ Within a version, the embedded system prompt is immutable. It is baked into the
 
 For development, use the override mechanism: place an `override.md` file at `~/.agentfile/<name>/override.md` and it replaces the embedded prompt without rebuilding. See the [Prompts Guide](./guides/prompts.md).
 
+## Runtime Config Overrides
+
+While the binary ships with compiled defaults, consumers can override certain settings without rebuilding via `~/.agentfile/<name>/config.yaml`:
+
+```bash
+./my-agent config set model opus        # override the model hint
+./my-agent config set tool_timeout 120s # override tool timeout
+./my-agent config get                   # show all (compiled + overrides)
+./my-agent config reset model           # revert to compiled default
+./my-agent config path                  # print config file location
+```
+
+Overridable fields: `model`, `tool_timeout`, `memory_limits`, `command_policy`. Overrides are loaded at startup — the `--describe` manifest and MCP server instructions reflect the effective (post-override) values.
+
+Install-time overrides are also supported:
+
+```bash
+agentfile install --model opus github.com/acme/my-agent
+```
+
+This writes the override to `config.yaml` during install so it takes effect immediately.
+
 ## When to Use What
 
 **Use CLAUDE.md when:**

docs/faq.md

@@ -61,6 +61,19 @@ Other options:
 
 Since agents compile to static Go binaries, they have no runtime dependencies.
 
+## How do I override agent settings without rebuilding?
+
+Use the `config` subcommand:
+
+```bash
+./my-agent config set model opus          # override the model hint
+./my-agent config set tool_timeout 120s   # override tool timeout
+./my-agent config get                     # see all settings with source
+./my-agent config reset model             # revert to compiled default
+```
+
+Overrides are stored at `~/.agentfile/<name>/config.yaml`. You can also set overrides at install time: `agentfile install --model opus github.com/owner/repo/agent`.
+
 ## What about secrets and configuration?
 
 Do not embed secrets in the binary. Use environment variables:

docs/guides/agentfile-format.md

@@ -56,7 +56,7 @@ The first frontmatter block identifies the agent to Claude Code:
 | `name` | yes | Agent name (used as binary name if not overridden by Agentfile) |
 | `description` | no | Short description shown in Claude Code's agent picker |
 | `memory` | no | Set to any value (e.g. `project`) to enable persistent memory |
-| `model` | no | Hint for Claude Code (not used by the binary) |
+| `model` | no | Model hint for the runtime (surfaced in `--describe` and MCP instructions). Can be overridden at install time (`--model`) or via `config set model` |
 
 ### Block 2 — Tools and Detailed Description
 

docs/guides/distribution.md

@@ -148,6 +148,16 @@ agentfile install github.com/your-org/private-repo/agent
 
 The token is also used for GitHub API rate limiting on public repos.
 
+### Install-Time Config Overrides
+
+Override settings at install time without editing config files:
+
+```bash
+agentfile install --model opus github.com/owner/repo/agent
+```
+
+This writes the override to `~/.agentfile/<name>/config.yaml`. The agent's `--describe` manifest and MCP instructions reflect the overridden value immediately. You can change it later with `<agent> config set model <value>` or revert with `<agent> config reset model`.
+
 ### Local Install (unchanged)
 
 Local installs from `./build/` continue to work as before, and now also track in the registry:

docs/guides/mcp.md

@@ -19,6 +19,16 @@ Example tool listing for an agent with `tools: Read, Write` and memory enabled:
 
 The system prompt is set as the MCP server's `instructions` field during the initialization handshake. MCP clients that support server instructions receive the prompt automatically.
 
+If a model hint is configured (via the agent definition or a config override), a `## Model Preference` section is appended to the instructions, e.g.:
+
+```
+## Model Preference
+
+This agent was designed for model: claude-opus-4-6
+```
+
+This is informational — the runtime decides which model to use.
+
 ### Resources (when memory is enabled)
 
 - `memory://<name>/` -- JSON array of all memory keys

docs/quickstart.md

@@ -110,6 +110,11 @@ See the [Agentfile Format Guide](./guides/agentfile-format.md) for full details.
 
 # Validate wiring (checks prompt, tools, memory, version)
 ./build/my-agent validate
+
+# Runtime config overrides (no rebuild needed)
+./build/my-agent config get                    # show compiled defaults
+./build/my-agent config set model opus         # override the model hint
+./build/my-agent config reset model            # revert to default
 ```
 
 ## Step 6: Connect to Claude Code

docs/reference.md

@@ -45,6 +45,18 @@ Enables or disables persistent memory. Default: `false`. When enabled, creates a
 
 Sets capacity limits for the memory store. Only meaningful when memory is enabled.
 
+### `WithModel(model string) Option`
+
+Sets the agent's model hint. This is informational metadata — the runtime (Claude Code, etc.) picks its own model. The value is surfaced in `--describe` JSON and as a "Model Preference" hint in MCP server instructions.
+
+### `WithLazyToolLoading(enabled bool) Option`
+
+Enables lazy tool loading via the `search_tools` meta-tool. When enabled, the MCP server only registers `search_tools` and `get_instructions` initially; clients discover other tools by searching.
+
+### `WithConfigPath(path string) Option`
+
+Overrides the default config.yaml location (`~/.agentfile/<name>/config.yaml`). Primarily useful for testing.
+
 ### `WithLogger(logger *slog.Logger) Option`
 
 Sets the structured logger. Default: `slog.NewTextHandler(os.Stderr, nil)`. Logs go to stderr so they do not interfere with MCP protocol on stdout.
@@ -103,6 +115,43 @@ Commands:
   delete <key>            Delete a key from memory
 ```
 
+### `config`
+
+Inspect and modify runtime configuration overrides stored at `~/.agentfile/<name>/config.yaml`.
+
+```
+Usage:
+  <agent-name> config [command]
+
+Commands:
+  get [field]             Show configuration (compiled defaults + overrides)
+  set <field> <value>     Set a config override
+  reset <field>           Remove an override, reverting to compiled default
+  path                    Print the config file path
+```
+
+Examples:
+
+```bash
+./my-agent config get                   # show all fields with source
+./my-agent config get model             # show just model
+./my-agent config set model opus        # set override
+./my-agent config set tool_timeout 120s # set timeout override
+./my-agent config reset model           # revert to compiled default
+./my-agent config path                  # ~/.agentfile/my-agent/config.yaml
+```
+
+Output format for `get`:
+
+```
+model: opus (override)
+tool_timeout: 30s (compiled)
+```
+
+Supported fields for `set`/`reset`: `model`, `tool_timeout`. Complex fields (`memory_limits`, `command_policy`) can be set by editing the YAML directly.
+
+When `reset` removes the last field, the config file is deleted.
+
 ### `serve-mcp`
 
 Start an MCP-over-stdio server.
@@ -152,6 +201,8 @@ Validation PASSED
   "name": "string",
   "version": "string",
   "description": "string",
+  "model": "string",
+  "toolTimeout": "30s",
   "tools": [
     {
       "name": "string",
@@ -177,6 +228,8 @@ Validation PASSED
 ```
 
 Notes:
+- `model` is only present if set (compiled default or config override)
+- `toolTimeout` is only present if non-default
 - `tools` includes both user-registered tools and memory tools (if enabled)
 - `memoryLimits` is only present when memory is enabled and limits are set
 - `annotations` is only present when set on the tool definition
@@ -394,14 +447,16 @@ func NewBridge(cfg BridgeConfig) *Bridge
 
 ```go
 type BridgeConfig struct {
-    Name        string
-    Version     string
-    Description string
-    Registry    *tools.Registry
-    Executor    *tools.Executor
-    Loader      *prompt.Loader
-    Memory      *memory.Manager   // nil if memory disabled
-    Logger      *slog.Logger      // nil disables logging
+    Name            string
+    Version         string
+    Description     string
+    Model           string          // model hint, appended to instructions
+    Registry        *tools.Registry
+    Executor        *tools.Executor
+    Loader          *prompt.Loader
+    Memory          *memory.Manager // nil if memory disabled
+    Logger          *slog.Logger    // nil disables logging
+    LazyToolLoading bool            // only register search_tools initially
 }
 ```
 
@@ -436,7 +491,8 @@ Usage:
   agentfile install <agent-name | github.com/owner/repo[/agent][@version]> [flags]
 
 Flags:
-  -g, --global   Install globally to /usr/local/bin
+  -g, --global        Install globally to /usr/local/bin
+      --model string  Override the agent's model in ~/.agentfile/<name>/config.yaml
 ```
 
 Installs an agent binary and wires it into MCP. Supports two modes:

examples/README.md

@@ -44,6 +44,28 @@ agentfile build            # -> ./build/golang-pro, ./build/code-reviewer + .mcp
 
 Both agents are auto-discovered by Claude Code via the generated `.mcp.json`.
 
+### [`model-override/`](model-override/)
+
+Demonstrates the runtime config override feature. The agent declares a model hint (`model: claude-opus-4-6`) and consumers can override it at install time or later via the `config` subcommand.
+
+```
+model-override/
+  Agentfile                     # declares one agent with a model hint
+  agents/smart-reviewer.md      # code reviewer recommending opus
+```
+
+Build and use:
+
+```bash
+cd model-override
+agentfile build                 # -> ./build/smart-reviewer + .mcp.json
+./build/smart-reviewer --describe             # shows model in manifest
+./build/smart-reviewer config get             # shows compiled defaults
+./build/smart-reviewer config set model sonnet  # override at runtime
+./build/smart-reviewer config get model       # sonnet (override)
+./build/smart-reviewer config reset model     # revert to compiled default
+```
+
 ## Creating Your Own
 
 1. Create an `Agentfile` at your project root

examples/model-override/Agentfile

@@ -0,0 +1,5 @@
+version: "1"
+agents:
+  smart-reviewer:
+    path: agents/smart-reviewer.md
+    version: 0.1.0

examples/model-override/agents/smart-reviewer.md

@@ -0,0 +1,18 @@
+---
+name: smart-reviewer
+memory: project
+model: claude-opus-4-6
+---
+
+---
+description: "A code reviewer that recommends a specific model"
+tools: Read, Glob, Grep
+---
+
+You are a thorough code reviewer. When reviewing changes:
+1. Read the modified files to understand the changes
+2. Search for related patterns in the codebase
+3. Check for bugs, security issues, and style violations
+4. Provide actionable feedback with file and line references
+
+Focus on correctness first, then readability, then style.