You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Replaced the five-minute walkthrough README with a concise, confident two-paragraph introduction. Added ten README variants under `docs/readme-variants/` for the team to review and choose from.
This is a five-minute walkthrough. By the end, you’ll have a **stateful, type-safe, hot-reloading API simulator** running locally—and you’ll understand why it’s different from traditional mock servers.
18
-
19
-
Built for frontend developers, test engineers, and AI agents that need a predictable API to work against.
11
+
You've used mock servers. You know where they stop being useful: static responses, no shared state, no way to inject a failure mid-run, no control without restarting. Counterfact picks up where they leave off.
20
12
21
-
22
-
23
-
## Minute 1 — Start the server
13
+
Point it at an OpenAPI spec and it generates TypeScript handlers for every endpoint—type-safe, hot-reloading, sharing state across routes. A built-in REPL gives you a live control surface: seed data, trigger error conditions, proxy individual routes to a real backend, all on a running server. Whether you're a frontend developer waiting on a backend, a test engineer who needs clean reproducible state, or an AI agent that needs a stable API to work against, Counterfact is the simulator that doesn't plateau.
24
14
25
15
```sh
26
16
npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api
27
17
```
28
18
29
-
> **Requires Node ≥ 22.0.0**
30
-
31
-
That’s it.
32
-
33
-
Counterfact reads your spec, generates a TypeScript handler for every endpoint, and starts a server at `http://localhost:3100`.
34
-
35
-
Open `http://localhost:3100/counterfact/swagger/`.
36
-
37
-
Every endpoint is already live, returning random, schema-valid responses. No code written yet.
Counterfact turns an OpenAPI spec into a live, stateful API server you can program in TypeScript. Point it at a spec and every endpoint is immediately live—returning schema-valid responses, sharing state across routes, and hot-reloading when you edit a handler.
12
+
13
+
That's where traditional mock servers stop. Counterfact keeps going. A built-in REPL lets you inspect and manipulate the running server: seed data, trigger failure modes, flip a proxy on or off—without restarting. It's a direct control surface for a running API. It works for frontend developers who can't wait on a backend, for test engineers who need reproducible states, and for AI coding agents that need a programmable, predictable sandbox to iterate in.
14
+
15
+
```sh
16
+
npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api
17
+
```
18
+
19
+
> Requires Node ≥ 22.0.0
20
+
21
+
## Go deeper
22
+
23
+
|||
24
+
|---|---|
25
+
|[Getting started](../getting-started.md)| Detailed walkthrough with state, REPL, and proxy |
26
+
|[Usage](../usage.md)| Feature index: routes, context, REPL, proxy, middleware, and more |
27
+
|[Patterns](../patterns/index.md)| Failures, latency, AI sandboxes, integration tests |
The shift toward AI-assisted development changes what a mock server needs to be. Agents iterate fast, depend on state carrying over between requests, and need to simulate failures and edge cases on demand. Static mocks—fixed responses, no memory, no runtime control—aren't enough anymore.
12
+
13
+
Counterfact is a programmable API simulator built for this moment. It reads an OpenAPI spec and starts a stateful TypeScript server in one command. A built-in REPL lets you—or an agent—control the running system: seed data, trigger failures, proxy individual routes to a real backend. The handlers it generates are type-safe, hot-reloading, and share state across routes. It works equally well for human developers who can't wait on a backend and for AI agents that need a reliable sandbox to reason about.
14
+
15
+
```sh
16
+
npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api
17
+
```
18
+
19
+
> Requires Node ≥ 22.0.0
20
+
21
+
## Go deeper
22
+
23
+
|||
24
+
|---|---|
25
+
|[Getting started](../getting-started.md)| Detailed walkthrough with state, REPL, and proxy |
26
+
|[Usage](../usage.md)| Feature index: routes, context, REPL, proxy, middleware, and more |
27
+
|[Patterns](../patterns/index.md)| Failures, latency, AI sandboxes, integration tests |
Mock servers have a familiar ceiling: static responses, no memory between requests, no way to control them while they're running. They're useful for simple demos but break down when you need real behavior—state that accumulates, errors that happen on demand, responses that depend on what came before.
12
+
13
+
Counterfact is a programmable API simulator. Give it an OpenAPI spec and it generates typed TypeScript handlers for every endpoint, starts a stateful server, and opens a REPL. From the REPL you can inspect context, seed data, and inject failure modes live—no restart, no HTTP scripts, no ceremony. When the real backend is ready, toggle a proxy endpoint by endpoint and let the rest stay simulated. It's the right tool for frontend development, integration testing, and AI coding agents that need a stable API to work against.
14
+
15
+
```sh
16
+
npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api
17
+
```
18
+
19
+
> Requires Node ≥ 22.0.0
20
+
21
+
## Go deeper
22
+
23
+
|||
24
+
|---|---|
25
+
|[Getting started](../getting-started.md)| Detailed walkthrough with state, REPL, and proxy |
26
+
|[Usage](../usage.md)| Feature index: routes, context, REPL, proxy, middleware, and more |
27
+
|[Patterns](../patterns/index.md)| Failures, latency, AI sandboxes, integration tests |
AI coding agents need APIs that behave predictably across many requests. Static mock servers return fixed data, which isn't enough when an agent is iterating on real workflows that depend on state, error paths, or sequential side effects. Counterfact gives agents—and the developers working alongside them—a fully programmable API sandbox: stateful, type-safe, hot-reloading, and controllable at runtime.
12
+
13
+
Give it an OpenAPI spec and it generates TypeScript handlers for every endpoint and starts a server. The built-in REPL is the key differentiator: inspect state, seed test data, simulate failures, and toggle a proxy to a real backend—all on a live server, without restarting. It works just as well for a frontend developer who can't wait on a backend or a test engineer who needs clean, reproducible API behavior.
14
+
15
+
```sh
16
+
npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api
17
+
```
18
+
19
+
> Requires Node ≥ 22.0.0
20
+
21
+
## Go deeper
22
+
23
+
|||
24
+
|---|---|
25
+
|[Getting started](../getting-started.md)| Detailed walkthrough with state, REPL, and proxy |
26
+
|[Usage](../usage.md)| Feature index: routes, context, REPL, proxy, middleware, and more |
27
+
|[Patterns](../patterns/index.md)| Failures, latency, AI sandboxes, integration tests |
Most mock servers are passive. You configure them, they respond, and you can't touch them while they're running. Counterfact includes a REPL—a live control surface for the running server. Inspect state. Inject data. Trigger failure modes. Toggle a proxy to a real backend. All without restarting, while your clients are connected.
12
+
13
+
Everything else follows from that: Counterfact reads your OpenAPI spec and generates typed TypeScript handlers for every endpoint. Handlers share state across routes. The server hot-reloads when you edit a file. Schema validation catches contract violations before you make the request. It works for frontend developers, test engineers, and AI coding agents that need a stable, programmable API sandbox.
14
+
15
+
```sh
16
+
npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api
17
+
```
18
+
19
+
> Requires Node ≥ 22.0.0
20
+
21
+
## Go deeper
22
+
23
+
|||
24
+
|---|---|
25
+
|[Getting started](../getting-started.md)| Detailed walkthrough with state, REPL, and proxy |
26
+
|[Usage](../usage.md)| Feature index: routes, context, REPL, proxy, middleware, and more |
27
+
|[Patterns](../patterns/index.md)| Failures, latency, AI sandboxes, integration tests |
0 commit comments