htpx-cli 0.1.2 → 0.2.0

package/dist/shared/project.d.ts

@@ -2,15 +2,26 @@
  * Find the project root by looking for .htpx directory or .git directory.
  * Walks up the directory tree from the current working directory.
  * Returns undefined if no project root is found.
+ *
+ * When override is provided, returns the resolved override path only if
+ * it contains an .htpx or .git directory; otherwise returns undefined.
+ *
+ * @param startDir - Directory to start searching from. Pass `undefined` to
+ *   use `process.cwd()` (common when only providing an override).
+ * @param override - If provided, resolves this path (with `~` expansion)
+ *   and checks it directly instead of walking the tree.
  */
-export declare function findProjectRoot(startDir?: string): string | undefined;
+export declare function findProjectRoot(startDir?: string, override?: string): string | undefined;
 /**
  * Determine the project root, creating .htpx if needed.
  * - If .htpx exists anywhere in the tree, use that directory
  * - If .git exists, use the git root
- * - Otherwise, use the current working directory
+ * - Otherwise, fall back to the user's home directory (global instance)
+ *
+ * When override is provided, returns the resolved override path directly
+ * (the caller is responsible for creating .htpx as needed).
  */
-export declare function findOrCreateProjectRoot(startDir?: string): string;
+export declare function findOrCreateProjectRoot(startDir?: string, override?: string): string;
 /**
  * Get the .htpx directory path for a project root.
  */
@@ -32,6 +43,8 @@ export declare function getHtpxPaths(projectRoot: string): {
     caCertFile: string;
     pidFile: string;
     logFile: string;
+    configFile: string;
+    interceptorsDir: string;
 };
 /**
  * Read the proxy port from the .htpx directory.

package/dist/shared/project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../src/shared/project.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,GAAE,MAAsB,GAAG,MAAM,GAAG,SAAS,CAmBpF;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,GAAE,MAAsB,GAAG,MAAM,CAqBhF;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAQzD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM;;;;;;;;;EAa/C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAWrE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAGtE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAWrE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAGrE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAMzD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAQrD"}
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../src/shared/project.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,GAAE,MAAsB,EAChC,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CA8BpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,GAAE,MAAsB,EAChC,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAyBR;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAQzD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM;;;;;;;;;;;EAe/C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAWrE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAGtE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAWrE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAGrE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAMzD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAQrD"}

package/dist/shared/project.js

@@ -1,12 +1,44 @@
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 const HTPX_DIR = ".htpx";
+const HOME_DIR_PREFIX = "~";
+/**
+ * Resolve an override path, expanding ~ to the user's home directory
+ * and converting relative paths to absolute.
+ */
+function resolveOverridePath(override) {
+    if (override.startsWith(HOME_DIR_PREFIX + path.sep) || override === HOME_DIR_PREFIX) {
+        return path.join(os.homedir(), override.slice(HOME_DIR_PREFIX.length));
+    }
+    // Also handle ~/foo on platforms where sep is /
+    if (override.startsWith(HOME_DIR_PREFIX + "/")) {
+        return path.join(os.homedir(), override.slice(2));
+    }
+    return path.resolve(override);
+}
 /**
  * Find the project root by looking for .htpx directory or .git directory.
  * Walks up the directory tree from the current working directory.
  * Returns undefined if no project root is found.
+ *
+ * When override is provided, returns the resolved override path only if
+ * it contains an .htpx or .git directory; otherwise returns undefined.
+ *
+ * @param startDir - Directory to start searching from. Pass `undefined` to
+ *   use `process.cwd()` (common when only providing an override).
+ * @param override - If provided, resolves this path (with `~` expansion)
+ *   and checks it directly instead of walking the tree.
  */
-export function findProjectRoot(startDir = process.cwd()) {
+export function findProjectRoot(startDir = process.cwd(), override) {
+    if (override !== undefined) {
+        const resolved = resolveOverridePath(override);
+        if (fs.existsSync(path.join(resolved, HTPX_DIR)) ||
+            fs.existsSync(path.join(resolved, ".git"))) {
+            return resolved;
+        }
+        return undefined;
+    }
     let currentDir = path.resolve(startDir);
     const root = path.parse(currentDir).root;
     while (currentDir !== root) {
@@ -26,9 +58,15 @@ export function findProjectRoot(startDir = process.cwd()) {
  * Determine the project root, creating .htpx if needed.
  * - If .htpx exists anywhere in the tree, use that directory
  * - If .git exists, use the git root
- * - Otherwise, use the current working directory
+ * - Otherwise, fall back to the user's home directory (global instance)
+ *
+ * When override is provided, returns the resolved override path directly
+ * (the caller is responsible for creating .htpx as needed).
  */
-export function findOrCreateProjectRoot(startDir = process.cwd()) {
+export function findOrCreateProjectRoot(startDir = process.cwd(), override) {
+    if (override !== undefined) {
+        return resolveOverridePath(override);
+    }
     let currentDir = path.resolve(startDir);
     const root = path.parse(currentDir).root;
     let gitRoot;
@@ -43,8 +81,8 @@ export function findOrCreateProjectRoot(startDir = process.cwd()) {
         }
         currentDir = path.dirname(currentDir);
     }
-    // If we found a git root, use that; otherwise use cwd
-    return gitRoot ?? process.cwd();
+    // Fall back to home directory for a global htpx instance
+    return gitRoot ?? os.homedir();
 }
 /**
  * Get the .htpx directory path for a project root.
@@ -77,6 +115,8 @@ export function getHtpxPaths(projectRoot) {
         caCertFile: path.join(htpxDir, "ca.pem"),
         pidFile: path.join(htpxDir, "daemon.pid"),
         logFile: path.join(htpxDir, "htpx.log"),
+        configFile: path.join(htpxDir, "config.json"),
+        interceptorsDir: path.join(htpxDir, "interceptors"),
     };
 }
 /**

package/dist/shared/project.js.map

@@ -1 +1 @@
-{"version":3,"file":"project.js","sourceRoot":"","sources":["../../src/shared/project.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../../src/shared/project.ts"],"names":[],"mappings":"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"}

package/dist/shared/proxy-info.d.ts

@@ -0,0 +1,10 @@
+export interface ProxyInfo {
+    proxyUrl: string;
+    caCertPath: string;
+    envBlock: string;
+}
+/**
+ * Build proxy connection details from port and CA cert path.
+ */
+export declare function buildProxyInfo(proxyPort: number, caCertPath: string): ProxyInfo;
+//# sourceMappingURL=proxy-info.d.ts.map

package/dist/shared/proxy-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-info.d.ts","sourceRoot":"","sources":["../../src/shared/proxy-info.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,CAY/E"}

package/dist/shared/proxy-info.js

@@ -0,0 +1,15 @@
+/**
+ * Build proxy connection details from port and CA cert path.
+ */
+export function buildProxyInfo(proxyPort, caCertPath) {
+    const proxyUrl = `http://127.0.0.1:${proxyPort}`;
+    const envBlock = [
+        `export HTTP_PROXY="${proxyUrl}"`,
+        `export HTTPS_PROXY="${proxyUrl}"`,
+        `export SSL_CERT_FILE="${caCertPath}"`,
+        `export REQUESTS_CA_BUNDLE="${caCertPath}"`,
+        `export NODE_EXTRA_CA_CERTS="${caCertPath}"`,
+    ].join("\n");
+    return { proxyUrl, caCertPath, envBlock };
+}
+//# sourceMappingURL=proxy-info.js.map

package/dist/shared/proxy-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-info.js","sourceRoot":"","sources":["../../src/shared/proxy-info.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB,EAAE,UAAkB;IAClE,MAAM,QAAQ,GAAG,oBAAoB,SAAS,EAAE,CAAC;IAEjD,MAAM,QAAQ,GAAG;QACf,sBAAsB,QAAQ,GAAG;QACjC,uBAAuB,QAAQ,GAAG;QAClC,yBAAyB,UAAU,GAAG;QACtC,8BAA8B,UAAU,GAAG;QAC3C,+BAA+B,UAAU,GAAG;KAC7C,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC;AAC5C,CAAC"}

package/dist/shared/types.d.ts

@@ -1,6 +1,7 @@
 /**
  * Core types for htpx
  */
+export type InterceptionType = "modified" | "mocked";
 export interface CapturedRequest {
     id: string;
     sessionId: string;
@@ -12,10 +13,36 @@ export interface CapturedRequest {
     path: string;
     requestHeaders: Record<string, string>;
     requestBody?: Buffer;
+    requestBodyTruncated?: boolean;
     responseStatus?: number;
     responseHeaders?: Record<string, string>;
     responseBody?: Buffer;
+    responseBodyTruncated?: boolean;
     durationMs?: number;
+    interceptedBy?: string;
+    interceptionType?: InterceptionType;
+}
+/**
+ * Summary version of CapturedRequest for list views.
+ * Excludes body and header data to reduce transfer size.
+ */
+export interface CapturedRequestSummary {
+    id: string;
+    sessionId: string;
+    label?: string;
+    timestamp: number;
+    method: string;
+    url: string;
+    host: string;
+    path: string;
+    responseStatus?: number;
+    durationMs?: number;
+    /** Size of request body in bytes (without transferring the body itself) */
+    requestBodySize: number;
+    /** Size of response body in bytes (without transferring the body itself) */
+    responseBodySize: number;
+    interceptedBy?: string;
+    interceptionType?: InterceptionType;
 }
 export interface Session {
     id: string;
@@ -29,5 +56,73 @@ export interface DaemonStatus {
     sessionCount: number;
     requestCount: number;
     version: string;
+    interceptorCount?: number;
+}
+export interface RequestFilter {
+    methods?: string[];
+    statusRange?: string;
+    search?: string;
+    host?: string;
+    pathPrefix?: string;
+    since?: number;
+    before?: number;
+    headerName?: string;
+    headerValue?: string;
+    headerTarget?: "request" | "response" | "both";
+    interceptedBy?: string;
+}
+/**
+ * Result from a JSON body query — a summary with the extracted value appended.
+ */
+export interface JsonQueryResult extends CapturedRequestSummary {
+    extractedValue: unknown;
+}
+export interface InterceptorRequest {
+    method: string;
+    url: string;
+    host: string;
+    path: string;
+    headers: Record<string, string>;
+    body?: Buffer;
+}
+export interface InterceptorResponse {
+    status: number;
+    headers?: Record<string, string>;
+    body?: string | Buffer;
+}
+export interface InterceptorContext {
+    request: Readonly<InterceptorRequest>;
+    forward: () => Promise<InterceptorResponse>;
+    htpx: HtpxClient;
+    log: (message: string) => void;
+}
+export interface Interceptor {
+    name?: string;
+    match?: (request: InterceptorRequest) => boolean | Promise<boolean>;
+    handler: (ctx: InterceptorContext) => Promise<InterceptorResponse | undefined | void>;
+}
+export interface HtpxClient {
+    countRequests(filter?: RequestFilter): Promise<number>;
+    listRequests(options?: {
+        filter?: RequestFilter;
+        limit?: number;
+        offset?: number;
+    }): Promise<CapturedRequestSummary[]>;
+    getRequest(id: string): Promise<CapturedRequest | null>;
+    searchBodies(options: {
+        query: string;
+        filter?: RequestFilter;
+        limit?: number;
+    }): Promise<CapturedRequestSummary[]>;
+    queryJsonBodies(options: {
+        jsonPath: string;
+        filter?: RequestFilter;
+    }): Promise<JsonQueryResult[]>;
+}
+export interface InterceptorInfo {
+    name: string;
+    hasMatch: boolean;
+    sourceFile: string;
+    error?: string;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/shared/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,22 +1,35 @@
 {
   "name": "htpx-cli",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Terminal HTTP interception toolkit",
   "type": "module",
   "main": "dist/cli/index.js",
   "bin": {
     "htpx": "dist/cli/index.js"
   },
+  "exports": {
+    ".": "./dist/cli/index.js",
+    "./interceptors": {
+      "types": "./dist/interceptors.d.ts",
+      "default": "./dist/interceptors.js"
+    }
+  },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
+  "agents": {
+    "skills": [
+      { "name": "htpx", "path": "./skills/htpx" }
+    ]
+  },
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
     "start": "node dist/cli/index.js",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:unit": "vitest run --dir tests/unit",
+    "test:unit": "vitest run --dir src",
     "test:int": "vitest run --dir tests/integration",
     "lint": "eslint src tests",
     "lint:fix": "eslint src tests --fix",
@@ -43,7 +56,7 @@
     "terminal"
   ],
   "author": "",
-  "license": "MIT",
+  "license": "AGPL-3.0-or-later",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mtford90/htpx.git"
@@ -52,17 +65,23 @@
     "url": "https://github.com/mtford90/htpx/issues"
   },
   "homepage": "https://github.com/mtford90/htpx#readme",
+  "packageManager": "pnpm@10.13.1",
   "engines": {
     "node": ">=20"
   },
   "dependencies": {
+    "@ink-tools/ink-mouse": "^2.1.0",
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "better-sqlite3": "^12.6.2",
+    "cli-highlight": "^2.1.11",
     "commander": "^14.0.3",
     "ink": "^6.6.0",
     "ink-use-stdout-dimensions": "^1.0.5",
+    "jiti": "^2.6.1",
     "mockttp": "^4.2.1",
     "react": "^19.2.4",
-    "uuid": "^13.0.0"
+    "uuid": "^13.0.0",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",

package/skills/htpx/SKILL.md

@@ -0,0 +1,228 @@
+# /htpx
+
+Use htpx to inspect, filter, and intercept HTTP traffic. Activate when htpx MCP tools are available or when the user mentions HTTP traffic, API debugging, request interception, or mocking.
+
+## Installation & Setup
+
+If htpx is not installed or the daemon is not running, you can set it up:
+
+1. **Install**: `npm install -g htpx-cli`
+2. **Shell setup** (one-time): Add `eval "$(htpx init)"` to the user's shell config (`~/.zshrc` or `~/.bashrc`), then source it or ask them to restart their shell
+3. **Start intercepting**: `htpx on` in the project directory
+4. **MCP config**: Add htpx to the MCP configuration:
+   ```json
+   {
+     "mcpServers": {
+       "htpx": {
+         "command": "htpx",
+         "args": ["mcp"]
+       }
+     }
+   }
+   ```
+
+After setup, call `htpx_get_status` to verify the daemon is running.
+
+## When to Use htpx
+
+- **Debugging failing API calls** -- filter by status code, inspect headers and response bodies
+- **Understanding traffic patterns** -- count requests, group by host/path/method
+- **Writing mocks/interceptors** -- capture real traffic as a template, write TypeScript interceptors
+- **Investigating auth issues** -- filter by `authorization` header, inspect tokens
+- **Performance analysis** -- check response times (`durationMs`), body sizes
+
+## Preflight
+
+Always call `htpx_get_status` first to confirm the daemon is running. If it is not running, try to start it by running `htpx on` in the project directory. If htpx is not installed, follow the Installation & Setup steps above.
+
+## MCP Tool Reference
+
+| Tool | Purpose | Key Parameters |
+|------|---------|----------------|
+| `htpx_get_status` | Check daemon is running, get proxy port and request count | -- |
+| `htpx_list_requests` | Browse/filter captured traffic (returns summaries) | `method`, `status_range`, `search`, `host`, `path`, `header_name`, `header_value`, `header_target`, `intercepted_by`, `since`, `before`, `limit`, `offset`, `format` |
+| `htpx_get_request` | Full request details -- headers, bodies, timing | `id` (single or comma-separated IDs), `format` |
+| `htpx_search_bodies` | Full-text search in request/response bodies | `query`, plus all filter params |
+| `htpx_query_json` | Extract JSON values with JSONPath (SQLite `json_extract`) | `json_path`, `value`, `target` (`request`/`response`/`both`), plus filters |
+| `htpx_count_requests` | Count matching requests | All filter params, `format` |
+| `htpx_clear_requests` | Delete all captured traffic (irreversible) | -- |
+| `htpx_list_sessions` | List active proxy sessions | -- |
+| `htpx_list_interceptors` | List loaded interceptors with status/errors | `format` |
+| `htpx_reload_interceptors` | Hot-reload interceptors from disk | `format` |
+
+### Output Formats
+
+All query tools accept `format`:
+- `"text"` (default) -- human-readable markdown summaries
+- `"json"` -- structured JSON for programmatic processing
+
+Use `"json"` when you need to process results (e.g. extract IDs, compare values). Use `"text"` when presenting to the user.
+
+## Common Filter Patterns
+
+```
+status_range: "5xx"            # Server errors
+status_range: "4xx"            # Client errors
+status_range: "401"            # Exact status code
+status_range: "500-503"        # Numeric range
+method: "POST,PUT"             # Mutation requests only
+host: ".api.example.com"       # Suffix match (note leading dot)
+host: "api.example.com"        # Exact match
+path: "/api/v2"                # Path prefix match
+search: "api/users"            # URL substring match
+header_name: "authorization"   # Requests with this header
+header_name: "content-type", header_value: "application/json"  # Exact header match
+header_target: "request"       # Only search request headers
+intercepted_by: "my-mock"      # Requests handled by a specific interceptor
+since: "2024-01-15T10:30:00Z"  # Time-bounded queries
+```
+
+Filters can be combined freely. All are optional.
+
+## Workflow Patterns
+
+### Pattern 1: Investigate a Bug
+
+1. `htpx_list_requests` with relevant filters (status code, host, path) to find the request
+2. `htpx_get_request` with the ID to inspect full headers, bodies, timing
+3. If searching for specific content in bodies, use `htpx_search_bodies`
+
+### Pattern 2: Write a Mock Interceptor
+
+1. `htpx_list_requests` to understand the traffic pattern you want to mock
+2. `htpx_get_request` to capture a real response as a template
+3. Write a `.ts` file to `.htpx/interceptors/` (see interceptor patterns below)
+4. `htpx_reload_interceptors` to activate
+5. `htpx_list_interceptors` to verify it loaded without errors
+
+### Pattern 3: Analyse API Usage
+
+1. `htpx_count_requests` with various filters to understand volume
+2. `htpx_query_json` to extract specific values from JSON bodies
+3. `htpx_list_requests` with `format: "json"` for structured analysis
+
+### Pattern 4: Debug Auth Issues
+
+1. `htpx_list_requests` with `header_name: "authorization", header_target: "request"` to find authed requests
+2. `htpx_list_requests` with `status_range: "401"` to find failures
+3. `htpx_get_request` to compare auth headers between successful and failed requests
+
+## Writing Interceptors
+
+Interceptor files are TypeScript files placed in `.htpx/interceptors/`. Each file exports a default `Interceptor` object.
+
+### Mock -- Return a Canned Response
+
+```typescript
+import type { Interceptor } from "htpx-cli/interceptors";
+
+export default {
+  name: "mock-users",
+  match: (req) => req.path === "/api/users",
+  handler: async () => ({
+    status: 200,
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify([{ id: 1, name: "Alice" }]),
+  }),
+} satisfies Interceptor;
+```
+
+Do not call `ctx.forward()` -- the request never reaches upstream. This is recorded as `interceptionType: "mocked"`.
+
+### Modify -- Forward, Then Alter the Response
+
+```typescript
+import type { Interceptor } from "htpx-cli/interceptors";
+
+export default {
+  name: "inject-header",
+  match: (req) => req.host.includes("example.com"),
+  handler: async (ctx) => {
+    const response = await ctx.forward();
+    return { ...response, headers: { ...response.headers, "x-debug": "htpx" } };
+  },
+} satisfies Interceptor;
+```
+
+Calls `ctx.forward()` but returns a modified response. Recorded as `interceptionType: "modified"`.
+
+### Observe -- Log Without Altering
+
+```typescript
+import type { Interceptor } from "htpx-cli/interceptors";
+
+export default {
+  name: "log-api",
+  match: (req) => req.path.startsWith("/api/"),
+  handler: async (ctx) => {
+    ctx.log(`${ctx.request.method} ${ctx.request.url}`);
+    const response = await ctx.forward();
+    ctx.log(`  -> ${response.status}`);
+    return response;
+  },
+} satisfies Interceptor;
+```
+
+Calls `ctx.forward()` and returns the response unchanged. Useful for debugging.
+
+### InterceptorContext Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `ctx.request` | `Readonly<InterceptorRequest>` | The incoming request (read-only) |
+| `ctx.forward()` | `() => Promise<InterceptorResponse>` | Forward to upstream server, returns response |
+| `ctx.log(msg)` | `(message: string) => void` | Write to `.htpx/htpx.log` (`console.log` is `/dev/null` in daemon) |
+| `ctx.htpx` | `HtpxClient` | Full query API (see below) |
+
+### InterceptorRequest Shape
+
+| Property | Type |
+|----------|------|
+| `method` | `string` |
+| `url` | `string` |
+| `host` | `string` |
+| `path` | `string` |
+| `headers` | `Record<string, string>` |
+| `body` | `Buffer \| undefined` |
+
+### InterceptorResponse Shape
+
+| Property | Type |
+|----------|------|
+| `status` | `number` |
+| `headers` | `Record<string, string> \| undefined` |
+| `body` | `string \| Buffer \| undefined` |
+
+### HtpxClient API (available as `ctx.htpx`)
+
+```typescript
+ctx.htpx.countRequests(filter?)          // Promise<number>
+ctx.htpx.listRequests({ filter, limit, offset })  // Promise<CapturedRequestSummary[]>
+ctx.htpx.getRequest(id)                  // Promise<CapturedRequest | null>
+ctx.htpx.searchBodies({ query, filter, limit })    // Promise<CapturedRequestSummary[]>
+ctx.htpx.queryJsonBodies({ jsonPath, filter })      // Promise<JsonQueryResult[]>
+```
+
+This allows interceptors to make decisions based on previously captured traffic.
+
+### Interceptor Rules
+
+- Any `.ts` file in `.htpx/interceptors/` is loaded as an interceptor
+- Files are loaded alphabetically; **first matching interceptor wins**
+- `match` is optional -- omit it to match all requests
+- `name` is optional but strongly recommended (used in `intercepted_by` filter)
+- Use `satisfies Interceptor` for full type checking and intellisense
+- Handler timeout: 30 seconds. Match timeout: 5 seconds.
+- Errors in handlers result in graceful pass-through -- never crashes the proxy
+- `ctx.log()` writes to `.htpx/htpx.log` (since `console.log` goes nowhere in the daemon)
+- Hot-reload on file changes, or run `htpx interceptors reload` / `htpx_reload_interceptors` / `htpx daemon restart`
+
+## Tips
+
+- After writing an interceptor, always `htpx_reload_interceptors` then `htpx_list_interceptors` to verify it loaded without errors
+- The `search` filter matches URL substrings -- useful for quick filtering when you do not know the exact host or path
+- `htpx_query_json` uses SQLite `json_extract` syntax (e.g. `$.user.name`, `$.items[0].id`)
+- Use `limit` and `offset` for pagination when there are many results (default limit: 50, max: 500)
+- `htpx_get_request` accepts comma-separated IDs for batch fetching (e.g. `id: "id1,id2,id3"`)
+- Host suffix matching requires a leading dot: `.example.com` matches `api.example.com` and `www.example.com`
+- Time filters use ISO 8601 format: `since: "2024-01-15T10:30:00Z"`