From 6d7970f489aa3b0d27a95fc935eda72743bf6107 Mon Sep 17 00:00:00 2001
From: William Valentin <william.valentin.info@gmail.com>
Date: Tue, 17 Feb 2026 09:38:41 -0800
Subject: [PATCH] feat(backends): support explicit backends.default selection

---
 README.md                 |  3 ++-
 src/config/schema.test.ts |  2 ++
 src/daemon/index.test.ts  | 16 ++++++++++++++++
 3 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 2f6e5ff..c23331c 100644
--- a/README.md
+++ b/README.md
@@ -322,6 +322,7 @@ Flynn can run with the built-in native backend or delegate message processing to
 
 ```yaml
 backends:
+  default: codex
   native: { enabled: true }
   codex: { enabled: false, path: /usr/local/bin/codex, args: [], timeout_ms: 120000 }
   claude_code: { enabled: false, path: /usr/local/bin/claude, args: [], timeout_ms: 120000 }
@@ -333,7 +334,7 @@ When `args` is non-empty:
 - use `{prompt}` in an argument to inject the full generated prompt directly into argv.
 - if `{prompt}` is not present, Flynn writes the prompt to stdin.
 
-If multiple external backends are enabled, Flynn selects the first in this order: `codex` -> `claude_code` -> `opencode` -> `gemini`.
+If multiple external backends are enabled, set `backends.default` to choose explicitly. If omitted, Flynn selects by priority: `codex` -> `claude_code` -> `opencode` -> `gemini`.
 
 You can also route specific named agents to a backend:
 
diff --git a/src/config/schema.test.ts b/src/config/schema.test.ts
index e9079c1..1f0e8f1 100644
--- a/src/config/schema.test.ts
+++ b/src/config/schema.test.ts
@@ -223,11 +223,13 @@ describe('configSchema — backends', () => {
     const result = configSchema.parse({
       ...minimalConfig,
       backends: {
+        default: 'codex',
         native: { enabled: false },
         codex: { enabled: true, path: '/usr/local/bin/codex', args: ['run'], timeout_ms: 300000 },
         gemini: { enabled: true, path: '/usr/local/bin/gemini', args: ['chat'], timeout_ms: 60000 },
       },
     });
+    expect(result.backends.default).toBe('codex');
     expect(result.backends.native.enabled).toBe(false);
     expect(result.backends.codex.enabled).toBe(true);
     expect(result.backends.codex.path).toBe('/usr/local/bin/codex');
diff --git a/src/daemon/index.test.ts b/src/daemon/index.test.ts
index d33a000..4dd027b 100644
--- a/src/daemon/index.test.ts
+++ b/src/daemon/index.test.ts
@@ -52,4 +52,20 @@ describe('createConfiguredExternalBackend', () => {
     expect(configured.backends.codex?.name).toBe('codex');
     expect(configured.backends.gemini?.name).toBe('gemini');
   });
+
+  it('honors backends.default when that backend is enabled', () => {
+    const cfg = {
+      ...base,
+      backends: {
+        ...base.backends,
+        default: 'gemini' as const,
+        codex: { enabled: true, path: '/usr/bin/codex', args: [], timeout_ms: 120000 },
+        gemini: { enabled: true, path: '/usr/bin/gemini', args: [], timeout_ms: 120000 },
+      },
+    };
+    const configured = createConfiguredExternalBackends(cfg);
+    expect(configured.defaultName).toBe('gemini');
+    expect(configured.backends.codex?.name).toBe('codex');
+    expect(configured.backends.gemini?.name).toBe('gemini');
+  });
 });