feat: add --proxy-only flag for stateless proxying (#99)

## Summary

- Add `--proxy-only` CLI flag that proxies unmatched requests to
upstream providers without saving fixtures to disk or caching them in
memory
- Every unmatched request always hits the real provider — no stale
recorded responses
- Matched fixtures still work normally
- Adds `proxyOnly` field to `RecordConfig` type for programmatic usage

## Use case

Demo/live environments where aimock sits in front of real LLM providers
with local fixtures for known scenarios, but unmatched traffic should
always go upstream rather than getting cached after the first call.

## Files changed

- `src/types.ts` — `proxyOnly?: boolean` on `RecordConfig`
- `src/cli.ts` — `--proxy-only` flag parsing and help text
- `src/recorder.ts` — skip disk write + memory push when `proxyOnly` is
set
- `src/__tests__/proxy-only.test.ts` — 8 tests covering proxy-only and
contrast with record mode

## Test plan

- [x] 8 new tests covering all proxy-only behaviors
- [x] All 2214 tests pass
- [x] Build passes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: jpr5

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "source": {
         "source": "npm",
         "package": "@copilotkit/aimock",
-        "version": "^1.9.0"
+        "version": "^1.10.0"
       },
       "description": "Fixture authoring skill for @copilotkit/aimock — match fields, response types, embeddings, structured output, sequential responses, streaming physics, agent loop patterns, gotchas, and debugging"
     }

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "llmock",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Fixture authoring guidance for @copilotkit/aimock",
   "author": {
     "name": "CopilotKit"

CHANGELOG.md

@@ -1,5 +1,11 @@
 # @copilotkit/aimock
 
+## 1.10.0
+
+### Minor Changes
+
+- Add `--proxy-only` flag — proxy unmatched requests to upstream providers without saving fixtures to disk or caching in memory. Every unmatched request always hits the real provider, preventing stale recorded responses in demo/live environments (#99)
+
 ## 1.9.0
 
 ### Minor Changes

charts/aimock/Chart.yaml

@@ -3,4 +3,4 @@ name: aimock
 description: Mock infrastructure for AI application testing (OpenAI, Anthropic, Gemini, MCP, A2A, vector)
 type: application
 version: 0.1.0
-appVersion: "1.9.0"
+appVersion: "1.10.0"

docs/record-replay/index.html

@@ -70,6 +70,72 @@ <h2>How It Works</h2>
           <li>Subsequent identical requests match the newly recorded fixture</li>
         </ol>
 
+        <h2>Proxy-Only Mode</h2>
+        <p>
+          Use <code>--proxy-only</code> instead of <code>--record</code> when you want unmatched
+          requests to always reach the real provider &mdash; no fixture files are written to disk
+          and no responses are cached in memory. Matched fixtures still work normally.
+        </p>
+        <p>
+          This is ideal for <strong>demos and live environments</strong> where you have canned
+          fixtures for repeatable demo scenarios you want to show off, but also want regular
+          interactions to work normally by proxying to the real provider. Without
+          <code>--proxy-only</code>, the first real API call would get recorded and cached, and
+          subsequent identical requests would get the stale recorded response instead of hitting the
+          live provider.
+        </p>
+
+        <div class="cli-docker-tabs">
+          <div class="tab-cli">
+            <div class="code-block">
+              <div class="code-block-header">
+                Proxy-only mode <span class="lang-tag">shell</span>
+              </div>
+              <pre><code>$ npx aimock --fixtures ./fixtures \
+  --proxy-only \
+  --provider-openai https://api.openai.com</code></pre>
+            </div>
+          </div>
+          <div class="tab-docker">
+            <div class="code-block">
+              <div class="code-block-header">
+                Proxy-only mode <span class="lang-tag">shell</span>
+              </div>
+              <pre><code>$ docker run -d -p 4010:4010 \
+  -v ./fixtures:/fixtures \
+  ghcr.io/copilotkit/aimock \
+  npx aimock -f /fixtures \
+  --proxy-only \
+  --provider-openai https://api.openai.com</code></pre>
+            </div>
+          </div>
+        </div>
+
+        <table class="endpoint-table">
+          <thead>
+            <tr>
+              <th>Mode</th>
+              <th>Unmatched request</th>
+              <th>Writes to disk</th>
+              <th>Caches in memory</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td><code>--record</code></td>
+              <td>Proxy &rarr; save &rarr; replay next time</td>
+              <td>Yes</td>
+              <td>Yes</td>
+            </tr>
+            <tr>
+              <td><code>--proxy-only</code></td>
+              <td>Proxy &rarr; relay &rarr; proxy again next time</td>
+              <td>No</td>
+              <td>No</td>
+            </tr>
+          </tbody>
+        </table>
+
         <h2>Quick Start</h2>
 
         <div class="cli-docker-tabs">
@@ -107,7 +173,11 @@ <h2>CLI Flags</h2>
           <tbody>
             <tr>
               <td><code>--record</code></td>
-              <td>Enable record mode (proxy-on-miss)</td>
+              <td>Enable record mode (proxy, save, and cache on miss)</td>
+            </tr>
+            <tr>
+              <td><code>--proxy-only</code></td>
+              <td>Proxy mode (forward on miss, no saving or caching)</td>
             </tr>
             <tr>
               <td><code>--strict</code></td>
@@ -166,6 +236,7 @@ <h2>Programmatic API</h2>
     <span class="prop">anthropic</span>: <span class="str">"https://api.anthropic.com"</span>,
   },
   <span class="prop">fixturePath</span>: <span class="str">"./fixtures/recorded"</span>,
+  <span class="prop">proxyOnly</span>: <span class="kw">true</span>,  <span class="cmt">// omit to record fixtures</span>
 });
 
 <span class="cmt">// Make requests — unmatched ones are proxied and recorded</span>

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@copilotkit/aimock",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Mock infrastructure for AI application testing — LLM APIs, MCP tools, A2A agents, vector databases, search, and more. Zero dependencies.",
   "license": "MIT",
   "repository": {