Skip to content

The agent that turns websites into APIs!

refactor: extract prompts to markdown templates, improve LLM guidelines

kalil032184c732c1f15b
diff --git a/src/reverse_api/auto_engineer.py b/src/reverse_api/auto_engineer.py
index 60d3944..71311d1 100644
--- a/src/reverse_api/auto_engineer.py
+++ b/src/reverse_api/auto_engineer.py
@@ -51,365 +51,54 @@ class ClaudeAutoEngineer(ClaudeEngineer):
self.mcp_run_id = run_id
self.agent_provider = agent_provider
- def _build_auto_prompt(self) -> str:
- """Build autonomous browsing + engineering prompt."""
- language_name = {
- "python": "Python",
- "javascript": "JavaScript",
- "typescript": "TypeScript",
- }.get(self.output_language, "Python")
+ def _build_auto_prompts(self) -> tuple[str, str]:
+ """Build (system_prompt, user_message) for auto mode.
- client_filename = self._get_client_filename()
- run_command = self._get_run_command()
-
- # Build language-specific generation instructions
- if self.output_language == "javascript":
- generation_instructions = f"""2. **Generate JavaScript API client** at `{self.scripts_dir}/{client_filename}`:
- - Use modern JavaScript (ES2022+) with ESM modules (import/export)
- - Use native `fetch` API for HTTP requests (Node.js 18+ built-in)
- - If advanced features needed (retries, interceptors), use `axios`
- - Include proper authentication handling
- - Create separate async functions for each API endpoint
- - Add JSDoc comments for type documentation
- - Include example usage in main section
- - Make it production-ready and maintainable
- - If using external dependencies, generate package.json
-
-3. **Create documentation** at `{self.scripts_dir}/README.md`:
- - Explain what APIs were discovered
- - How authentication works
- - How to use each function
- - Requirements: Node.js 18+
- - Any limitations or requirements
-
-4. **Test your implementation**:
- - If package.json was generated, first run: npm install
- - Run with: {run_command}
- - You have up to 5 attempts to fix any issues
- - If initial implementation fails, analyze errors and iterate"""
- output_files = f"""1. `{self.scripts_dir}/{client_filename}` - Production JavaScript API client
-2. `{self.scripts_dir}/README.md` - Documentation with usage examples
-3. `{self.scripts_dir}/package.json` - Only if external dependencies are needed"""
-
- elif self.output_language == "typescript":
- generation_instructions = f"""2. **Generate TypeScript API client** at `{self.scripts_dir}/{client_filename}`:
- - Use TypeScript with strict typing enabled
- - Use ESM modules (import/export syntax)
- - Use native `fetch` API for HTTP requests (Node.js 18+ built-in)
- - If advanced features needed, use `axios`
- - Define TypeScript interfaces for all request/response types
- - Include proper authentication handling
- - Create separate async functions for each API endpoint
- - Export a class-based API client with proper encapsulation
- - Include example usage in main section
- - Make it production-ready and maintainable
- - Generate package.json with tsx, typescript, @types/node
-
-3. **Create documentation** at `{self.scripts_dir}/README.md`:
- - Explain what APIs were discovered
- - How authentication works
- - How to use each function
- - Requirements: Node.js 18+
- - Any limitations or requirements
-
-4. **Test your implementation**:
- - Run: npm install && {run_command}
- - You have up to 5 attempts to fix any issues
- - If initial implementation fails, analyze errors and iterate"""
- output_files = f"""1. `{self.scripts_dir}/{client_filename}` - Production TypeScript API client
-2. `{self.scripts_dir}/README.md` - Documentation with usage examples
-3. `{self.scripts_dir}/package.json` - Dependencies and run scripts"""
-
- else: # python
- generation_instructions = f"""2. **Generate Python API client** at `{self.scripts_dir}/{client_filename}`:
- - Use `requests` library as default (or Playwright if needed for bot detection)
- - Include proper authentication handling
- - Create separate functions for each API endpoint
- - Add type hints, docstrings, error handling
- - Include example usage in main section
- - Make it production-ready and maintainable
-
-3. **Create documentation** at `{self.scripts_dir}/README.md`:
- - Explain what APIs were discovered
- - How authentication works
- - How to use each function
- - Example usage
- - Any limitations or requirements
-
-4. **Test your implementation**:
- - After generating the code, test it to ensure it works
- - Run with: {run_command}
- - You have up to 5 attempts to fix any issues
- - If initial implementation fails, analyze errors and iterate"""
- output_files = f"""1. `{self.scripts_dir}/{client_filename}` - Production Python API client
-2. `{self.scripts_dir}/README.md` - Documentation with usage examples"""
-
- return f"""You are an autonomous AI agent with browser control via MCP tools.
- Your mission is to browse, monitor network traffic, and generate production-ready {language_name} API code.
-
-<mission>
-{self.prompt}
-</mission>
-
-<output_directory>
-{self.scripts_dir}
-</output_directory>
-
-## WORKFLOW
-
-Follow this workflow step-by-step:
-
-### Phase 1: BROWSE
-Use browser MCP tools to accomplish the mission goal, here are some of the tools you can use.
-This list is not exhaustive, but it's a good starting point:
-- `browser_navigate` - Navigate to a URL
-- `browser_click` - Click an element
-- `browser_scroll` - Scroll the page
-- `browser_close` - Close the browser
-- `browser_evaluate` - Evaluate JavaScript code
-- `browser_press_key` - Press a key
-- `browser_run_code` - Run Playwright code
-- `browser_type` - Type text into input
-- `browser_wait_for` - Wait for text to appear or disappear or a specified time to pass
-- `browser_snapshot` - Get accessibility tree (useful alternative to screenshots for understanding page structure)
-- `browser_take_screenshot` - Take screenshot for context (IMPORTANT: Prefer element-specific screenshots over full-page to avoid size limits)
-- And other browser MCP tools available
-
-**Screenshot Guidelines:**
-- Screenshots have a 1MB size limit - avoid full-page screenshots when possible
-- Prefer taking element-specific screenshots using CSS selectors
-- If you need context, take multiple smaller screenshots of key areas
-- Use `browser_snapshot()` when you need page structure information without visual details
-
-### Phase 2: MONITOR
-While browsing, periodically call `browser_network_requests()` to monitor API traffic in real-time.
-Keep in mind that you will also have access to the full network traffic when closing the browser:
-- Analyze requests and responses
-- Identify authentication patterns (cookies, tokens, headers)
-- Note API endpoints, methods, parameters
-- Track response structures
-
-### Phase 3: CAPTURE
-When you have sufficient data or have accomplished the mission goal, call `browser_close()` to save the HAR file:
-- This saves all captured network traffic to: {self.har_path}
-- Returns: {{"har_path": str, "resources": {{...}}}}
-
-### Phase 4: REVERSE ENGINEER
-Based on the network traffic you observed, generate production-ready {language_name} code:
-
-1. **Analyze the HAR file** you just captured at {self.har_path}
- - Read and parse the HAR file
- - Extract all API calls, authentication, patterns
-
-{generation_instructions}
-
-## IMPORTANT NOTES
-
-- Think step-by-step and narrate your actions as you browse
-- Call `browser_network_requests()` frequently to monitor traffic
-- Don't rush - ensure you capture all necessary API calls before closing browser
-- After generating code, always test it to verify it works
-- Handle bot detection by switching to Playwright with CDP if needed
-- **Screenshot size limit**: Screenshots must be under 1MB. Prefer element-specific screenshots over full-page screenshots to avoid errors
-
-## OUTPUT FILES REQUIRED
-
-{output_files}
-
-Your final response should confirm the files were created and provide a brief summary of:
-- What APIs were discovered
-- The authentication method used
-- Whether the implementation works
-- Any limitations or caveats
-"""
+ The system prompt contains the agent role, codegen instructions, and output
+ format. The user message contains the mission, workflow, and tool-specific
+ instructions.
+ """
+ from .prompts import load
- def _build_chrome_mcp_prompt(self) -> str:
- """Build autonomous browsing + engineering prompt for Chrome DevTools MCP."""
- language_name = {
- "python": "Python",
- "javascript": "JavaScript",
- "typescript": "TypeScript",
- }.get(self.output_language, "Python")
+ language_name = self._get_language_name()
+ codegen_instructions = self._get_codegen_instructions()
client_filename = self._get_client_filename()
- run_command = self._get_run_command()
-
- if self.output_language == "javascript":
- generation_instructions = f"""2. **Generate JavaScript API client** at `{self.scripts_dir}/{client_filename}`:
- - Use modern JavaScript (ES2022+) with ESM modules (import/export)
- - Use native `fetch` API for HTTP requests (Node.js 18+ built-in)
- - If advanced features needed (retries, interceptors), use `axios`
- - Include proper authentication handling
- - Create separate async functions for each API endpoint
- - Add JSDoc comments for type documentation
- - Include example usage in main section
- - Make it production-ready and maintainable
- - If using external dependencies, generate package.json
-
-3. **Create documentation** at `{self.scripts_dir}/README.md`:
- - Explain what APIs were discovered
- - How authentication works
- - How to use each function
- - Requirements: Node.js 18+
- - Any limitations or requirements
-
-4. **Test your implementation**:
- - If package.json was generated, first run: npm install
- - Run with: {run_command}
- - You have up to 5 attempts to fix any issues
- - If initial implementation fails, analyze errors and iterate"""
- output_files = f"""1. `{self.scripts_dir}/{client_filename}` - Production JavaScript API client
-2. `{self.scripts_dir}/README.md` - Documentation with usage examples
-3. `{self.scripts_dir}/package.json` - Only if external dependencies are needed"""
-
- elif self.output_language == "typescript":
- generation_instructions = f"""2. **Generate TypeScript API client** at `{self.scripts_dir}/{client_filename}`:
- - Use TypeScript with strict typing enabled
- - Use ESM modules (import/export syntax)
- - Use native `fetch` API for HTTP requests (Node.js 18+ built-in)
- - If advanced features needed, use `axios`
- - Define TypeScript interfaces for all request/response types
- - Include proper authentication handling
- - Create separate async functions for each API endpoint
- - Export a class-based API client with proper encapsulation
- - Include example usage in main section
- - Make it production-ready and maintainable
- - Generate package.json with tsx, typescript, @types/node
-
-3. **Create documentation** at `{self.scripts_dir}/README.md`:
- - Explain what APIs were discovered
- - How authentication works
- - How to use each function
- - Requirements: Node.js 18+
- - Any limitations or requirements
-
-4. **Test your implementation**:
- - Run: npm install && {run_command}
- - You have up to 5 attempts to fix any issues
- - If initial implementation fails, analyze errors and iterate"""
- output_files = f"""1. `{self.scripts_dir}/{client_filename}` - Production TypeScript API client
-2. `{self.scripts_dir}/README.md` - Documentation with usage examples
-3. `{self.scripts_dir}/package.json` - Dependencies and run scripts"""
-
- else: # python
- generation_instructions = f"""2. **Generate Python API client** at `{self.scripts_dir}/{client_filename}`:
- - Use `requests` library as default (or Playwright if needed for bot detection)
- - Include proper authentication handling
- - Create separate functions for each API endpoint
- - Add type hints, docstrings, error handling
- - Include example usage in main section
- - Make it production-ready and maintainable
-
-3. **Create documentation** at `{self.scripts_dir}/README.md`:
- - Explain what APIs were discovered
- - How authentication works
- - How to use each function
- - Example usage
- - Any limitations or requirements
-
-4. **Test your implementation**:
- - After generating the code, test it to ensure it works
- - Run with: {run_command}
- - You have up to 5 attempts to fix any issues
- - If initial implementation fails, analyze errors and iterate"""
- output_files = f"""1. `{self.scripts_dir}/{client_filename}` - Production Python API client
-2. `{self.scripts_dir}/README.md` - Documentation with usage examples"""
-
- return f"""You are an autonomous AI agent with browser control via Chrome DevTools MCP tools.
-You are connected to the user's REAL Chrome browser with their existing sessions, cookies, and authentication.
-Your mission is to browse, monitor network traffic, and generate production-ready {language_name} API code.
-
-<mission>
-{self.prompt}
-</mission>
-
-<output_directory>
-{self.scripts_dir}
-</output_directory>
-
-## WORKFLOW
-
-Follow this workflow step-by-step:
-
-### Phase 1: BROWSE
-Use Chrome DevTools MCP tools to accomplish the mission goal. Available tools:
-- `navigate_page` - Navigate to a URL (type: "url", url: "..."), go back/forward/reload
-- `click` - Click an element by its uid
-- `fill` - Type text into an input, textarea, or select (uid, value)
-- `fill_form` - Fill multiple form elements at once
-- `hover` - Hover over an element
-- `press_key` - Press a key or combination (e.g. "Enter", "Control+A")
-- `new_page` - Open a new page/tab
-- `list_pages` - List open browser pages
-- `select_page` - Switch to a specific page/tab
-- `wait_for` - Wait for text to appear on the page
-- `take_snapshot` - Get accessibility tree (useful for understanding page structure and element uids)
-- `take_screenshot` - Take a screenshot for visual context
-- `evaluate_script` - Execute JavaScript in the current page
-- `list_console_messages` - Check console for errors/logs
-
-**IMPORTANT: You are controlling the user's actual Chrome browser. Their existing login sessions and cookies are available - you do NOT need to log in to sites where they are already authenticated.**
-
-**Screenshot Guidelines:**
-- Screenshots have a 1MB size limit - avoid full-page screenshots when possible
-- Use `take_snapshot()` when you need page structure information without visual details
-- The snapshot gives you element `uid` values needed for `click`, `fill`, etc.
-
-### Phase 2: MONITOR
-While browsing, periodically call `list_network_requests()` to monitor API traffic in real-time:
-- Filter by type (e.g. "xhr", "fetch") to focus on API calls
-- Analyze request URLs, methods, and response status codes
-- Identify authentication patterns (cookies, tokens, headers)
-- Note API endpoints and parameters
-
-For detailed inspection, use `get_network_request(reqid)` to get:
-- Full request headers and body
-- Full response headers and body
-- Timing information
-
-### Phase 3: CAPTURE
-When you have sufficient data or have accomplished the mission goal:
-1. Call `list_network_requests()` one final time to get all requests
-2. For each important API request, call `get_network_request(reqid)` to capture full details
-3. Pay special attention to: authentication headers, API endpoints, request/response bodies
-
-**There is no HAR file.** You must capture all network data you need using these tools before proceeding.
-
-### Phase 4: REVERSE ENGINEER
-Based on the network traffic you observed, generate production-ready {language_name} code:
-
-1. **Analyze the captured network data**
- - Review all API calls you collected via list_network_requests and get_network_request
- - Extract authentication patterns, endpoints, parameters, response structures
-
-{generation_instructions}
-
-## IMPORTANT NOTES
-
-- Think step-by-step and narrate your actions as you browse
-- Call `list_network_requests()` frequently to monitor traffic
-- Use `get_network_request(reqid)` to capture full request/response details for important API calls
-- Don't rush - ensure you capture all necessary API calls before generating code
-- After generating code, always test it to verify it works
-- **Screenshot size limit**: Screenshots must be under 1MB. Prefer `take_snapshot()` over screenshots when possible
-- You have access to the user's real browser sessions - leverage existing auth when possible
-
-## OUTPUT FILES REQUIRED
-
-{output_files}
-
-Your final response should confirm the files were created and provide a brief summary of:
-- What APIs were discovered
-- The authentication method used
-- Whether the implementation works
-- Any limitations or caveats
-"""
+ output_files = self._get_auto_output_files(language_name, client_filename)
- def _get_active_prompt(self) -> str:
- """Return the appropriate prompt based on agent_provider."""
- if self.agent_provider == "chrome-mcp":
- return self._build_chrome_mcp_prompt()
- return self._build_auto_prompt()
+ browser_tool_label = (
+ "Chrome DevTools MCP"
+ if self.agent_provider == "chrome-mcp"
+ else "MCP"
+ )
+
+ system_prompt = load(
+ "auto/system",
+ browser_tool_label=browser_tool_label,
+ language_name=language_name,
+ codegen_instructions=codegen_instructions,
+ output_files=output_files,
+ )
+
+ template = (
+ "auto/user_chrome_mcp"
+ if self.agent_provider == "chrome-mcp"
+ else "auto/user_playwright"
+ )
+
+ template_kwargs = {
+ "prompt": self.prompt,
+ "scripts_dir": str(self.scripts_dir),
+ }
+ if self.agent_provider != "chrome-mcp":
+ template_kwargs["har_path"] = str(self.har_path)
+
+ user_message = load(template, **template_kwargs)
+ return system_prompt, user_message
+
+ def _get_active_prompts(self) -> tuple[str, str]:
+ """Return (system_prompt, user_message) based on agent_provider."""
+ return self._build_auto_prompts()
async def _handle_tool_permission(self, tool_name: str, input_data: dict[str, Any], context: ToolPermissionContext) -> PermissionResultAllow:
"""Handle tool permission requests, with interactive UI for AskUserQuestion."""
@@ -449,16 +138,17 @@ Your final response should confirm the files were created and provide a brief su
self.ui.header(self.run_id, self.prompt, self.model, mode="agent")
self.ui.start_analysis()
- active_prompt = self._get_active_prompt()
- self.message_store.save_prompt(active_prompt)
+ system_prompt, user_message = self._get_active_prompts()
+ self.message_store.save_prompt(user_message)
mcp_name, mcp_config = self._get_mcp_config()
options = ClaudeAgentOptions(
+ system_prompt=system_prompt,
mcp_servers={mcp_name: mcp_config},
permission_mode="bypassPermissions",
can_use_tool=self._handle_tool_permission,
- cwd=str(self.scripts_dir.parent.parent), # Project root
+ cwd=str(self.scripts_dir.parent.parent),
model=self.model,
env={"CLAUDECODE": ""},
stderr=self._handle_cli_stderr,
@@ -468,7 +158,7 @@ Your final response should confirm the files were created and provide a brief su
try:
async with ClaudeSDKClient(options=options) as client:
- await client.query(active_prompt)
+ await client.query(user_message)
# Process initial response
last_result = await self._process_streaming_response(client)
@@ -534,13 +224,8 @@ class OpenCodeAutoEngineer(OpenCodeEngineer):
self.agent_provider = agent_provider
self.mcp_name = None
- def _build_auto_prompt(self) -> str:
- return ClaudeAutoEngineer._build_auto_prompt(self)
-
- def _get_active_prompt(self) -> str:
- if self.agent_provider == "chrome-mcp":
- return ClaudeAutoEngineer._build_chrome_mcp_prompt(self)
- return self._build_auto_prompt()
+ def _get_active_prompts(self) -> tuple[str, str]:
+ return ClaudeAutoEngineer._build_auto_prompts(self)
def _get_opencode_mcp_config(self) -> dict:
"""Return OpenCode MCP registration payload based on agent_provider."""
@@ -578,8 +263,9 @@ class OpenCodeAutoEngineer(OpenCodeEngineer):
self.opencode_ui.header(self.run_id, self.prompt, self.opencode_model, mode="agent")
self.opencode_ui.start_analysis()
- active_prompt = self._get_active_prompt()
- self.message_store.save_prompt(active_prompt)
+ system_prompt, user_message = self._get_active_prompts()
+ active_prompt = f"{system_prompt}\n\n{user_message}"
+ self.message_store.save_prompt(user_message)
try:
auth = self._get_auth()
@@ -798,11 +484,11 @@ class CopilotAutoEngineer:
eng.ui.header(eng.run_id, eng.prompt, eng.copilot_model, eng.sdk, mode="agent")
eng.ui.start_analysis()
- if self.agent_provider == "chrome-mcp":
- auto_prompt = ClaudeAutoEngineer._build_chrome_mcp_prompt(eng)
- else:
- auto_prompt = ClaudeAutoEngineer._build_auto_prompt(eng)
- eng.message_store.save_prompt(auto_prompt)
+ # CopilotEngineer doesn't have agent_provider; set it temporarily for prompt building
+ eng.agent_provider = self.agent_provider
+ system_prompt, user_message = ClaudeAutoEngineer._build_auto_prompts(eng)
+ auto_prompt = f"{system_prompt}\n\n{user_message}"
+ eng.message_store.save_prompt(user_message)
done_event = asyncio.Event()
loop = asyncio.get_running_loop()
diff --git a/src/reverse_api/base_engineer.py b/src/reverse_api/base_engineer.py
index 2e7e3e6..4fd91b4 100644
--- a/src/reverse_api/base_engineer.py
+++ b/src/reverse_api/base_engineer.py
@@ -396,14 +396,13 @@ class BaseEngineer(ABC):
return ""
language_name = self._get_language_name()
- return f"""
-There is already an existing {language_name} client for this run:
-<existing_client>
-{self.existing_client_path}
-</existing_client>
-
-**IMPORTANT: This is an iterative edit. Update that file in place and keep the implementation in {language_name} unless the user explicitly asks for a fresh rewrite.**
-"""
+ return (
+ f"\nThere is already an existing {language_name} client for this run:\n"
+ f"<existing_client>\n{self.existing_client_path}\n</existing_client>\n\n"
+ f"**IMPORTANT: This is an iterative edit. Update that file in place and "
+ f"keep the implementation in {language_name} unless the user explicitly asks "
+ f"for a fresh rewrite.**\n"
+ )
def _get_client_filename(self) -> str:
"""Return the output filename based on mode."""
@@ -419,195 +418,44 @@ There is already an existing {language_name} client for this run:
"typescript": "npx tsx api_client.ts",
}.get(self.output_language, "python api_client.py")
- def _get_language_instructions(self) -> str:
- """Return language-specific code generation instructions."""
- client_filename = self._get_client_filename()
- run_command = self._get_run_command()
-
- if self.output_language == "javascript":
- return f"""4. **Generate a JavaScript module** that replicates these API calls with the following requirements:
- - Use modern JavaScript (ES2022+) with ESM modules (import/export)
- - Use native `fetch` API for HTTP requests (Node.js 18+ built-in)
- - If advanced features are needed (retries, interceptors), use `axios` instead
- - Include proper authentication handling (sessions, headers, tokens)
- - Create separate async functions for each distinct API endpoint
- - Use JSDoc comments for type documentation on all functions
- - Implement proper error handling with try-catch blocks
- - Create custom Error classes for API errors
- - Add console logging for debugging purposes
- - Make the code production-ready and maintainable
- - Include a main section with example usage (wrapped in async IIFE or top-level await)
- - If using external dependencies (like axios), generate a package.json with:
- - "type": "module" for ESM support
- - Required dependencies
- - scripts: {{ "start": "node api_client.js" }}
-
-5. **Create documentation**:
- - Generate a README.md file that explains:
- - What APIs were discovered
- - How authentication works
- - How to use each function
- - Example usage
- - Requirements: Node.js 18+
- - Any limitations or requirements
-
-6. **Test your implementation**:
- - If package.json was generated, first run: npm install
- - Run with: {run_command}
- - You have up to 5 attempts to fix any issues
- - If the initial implementation fails, analyze the error and try again
-
-After your analysis, generate the files:
-
-1. Save the JavaScript module to: {self.scripts_dir}/{client_filename}
-2. Save the documentation to: {self.scripts_dir}/README.md
-3. If external dependencies are used, save: {self.scripts_dir}/package.json"""
+ def _get_codegen_instructions(self) -> str:
+ """Return codegen instructions from the appropriate template partial."""
+ from .prompts import load
- elif self.output_language == "typescript":
- return f"""4. **Generate a TypeScript module** that replicates these API calls with the following requirements:
- - Use TypeScript with strict typing enabled
- - Use ESM modules (import/export syntax)
- - Use native `fetch` API for HTTP requests (Node.js 18+ built-in)
- - If advanced features are needed (retries, interceptors), use `axios` instead
- - Define TypeScript interfaces for all request/response types
- - Include proper authentication handling (sessions, headers, tokens)
- - Create separate async functions for each distinct API endpoint
- - Use async/await patterns throughout
- - Export a class-based API client with proper encapsulation
- - Implement proper error handling with custom error types
- - Add console logging for debugging purposes
- - Make the code production-ready and maintainable
- - Include a main section with example usage
- - Generate a package.json with:
- - "type": "module" for ESM support
- - devDependencies: tsx, typescript, @types/node
- - dependencies: axios (only if used)
- - scripts: {{ "start": "npx tsx api_client.ts" }}
-
-5. **Create documentation**:
- - Generate a README.md file that explains:
- - What APIs were discovered
- - How authentication works
- - How to use each function
- - Example usage
- - Requirements: Node.js 18+
- - Any limitations or requirements
-
-6. **Test your implementation**:
- - Run: npm install && {run_command}
- - npx auto-downloads tsx if not installed
- - You have up to 5 attempts to fix any issues
- - If the initial implementation fails, analyze the error and try again
-
-After your analysis, generate the files:
-
-1. Save the TypeScript module to: {self.scripts_dir}/{client_filename}
-2. Save the documentation to: {self.scripts_dir}/README.md
-3. Save the package.json to: {self.scripts_dir}/package.json"""
-
- else: # python (default)
- return f"""4. **Generate a Python script** that replicates these API calls with the following requirements:
- - Use the `requests` library as the default choice
- - Include proper authentication handling (sessions, headers, tokens)
- - Create separate functions for each distinct API endpoint
- - Include type hints for all function parameters and return values
- - Write comprehensive docstrings for each function
- - Implement proper error handling with try-except blocks
- - Add logging for debugging purposes
- - Make the code production-ready and maintainable
- - Include a main section with example usage
-
-5. **Create documentation**:
- - Generate a README.md file that explains:
- - What APIs were discovered
- - How authentication works
- - How to use each function
- - Example usage
- - Any limitations or requirements
-
-6. **Test your implementation**:
- - After generating the code, test it to ensure it works
- - Run with: {run_command}
- - You have up to 5 attempts to fix any issues
- - If the initial implementation fails, analyze the error and try again
- - Keep in mind that some websites have bot detection mechanisms
-
-7. **Handle bot detection**:
- - If you encounter bot detection, CAPTCHA, or anti-scraping measures with `requests`
- - Consider switching to Playwright with CDP (Chrome DevTools Protocol) or using httpcloak
- - Use the real user browser context to bypass detection
- - Maintain the same code quality standards regardless of approach
-
-After your analysis, generate the files:
-
-1. Save the Python script to: {self.scripts_dir}/{client_filename}
-2. Save the documentation to: {self.scripts_dir}/README.md"""
-
- def _get_docs_instructions(self) -> str:
- """Return OpenAPI documentation generation instructions."""
- return f"""4. **Generate an OpenAPI 3.0 specification** that documents these API endpoints:
- - Use OpenAPI 3.0.0 format (https://swagger.io/specification/)
- - Include all discovered endpoints with:
- - Correct HTTP methods (GET, POST, PUT, DELETE, etc.)
- - Path parameters and query parameters
- - Request body schemas (JSON Schema format)
- - Response schemas for common status codes (200, 400, 401, 404, 500)
- - Authentication/security schemes (API keys, Bearer tokens, OAuth, etc.)
- - Organize endpoints into logical tags/groups (e.g., "Users", "Products", "Orders")
- - Infer meaningful descriptions for:
- - Each endpoint's purpose (what it does)
- - Parameters (what they control)
- - Response fields (what they represent)
- - Include examples where patterns are clear from the HAR data
- - Use JSON Schema $ref for shared components/schemas
- - Document authentication requirements in security schemes
- - Add a servers array with the base URL from the HAR file
-
-5. **Enhance documentation with AI inference**:
- - Analyze request/response patterns to infer parameter types and constraints
- - Group related endpoints into logical operations
- - Generate human-readable descriptions (not just field names)
- - Identify required vs optional parameters based on HAR observations
- - Add example values from actual captured requests
- - Document error responses observed in the HAR
- - Note rate limiting headers if present
- - Describe authentication flow if multi-step
-
-6. **Create supplementary documentation**:
- - Generate a README.md file that explains:
- - API overview and purpose
- - Authentication method and how to obtain credentials
- - Base URL and versioning
- - Common use cases with example requests
- - Rate limiting information (if observed)
- - Any special headers or requirements
- - Link to view the OpenAPI spec (e.g., in Swagger UI)
-
-After your analysis, generate the files:
-
-1. Save the OpenAPI spec to: {self.scripts_dir}/openapi.json
-2. Save the README to: {self.scripts_dir}/README.md
-3. Optionally create: {self.scripts_dir}/examples.md with curl examples
-
-Your OpenAPI spec should be production-ready and suitable for:
-- API documentation portals (Swagger UI, Redoc, Stoplight)
-- Code generation (OpenAPI Generator, swagger-codegen)
-- API testing (Postman, Insomnia)
-- Contract testing and validation"""
-
- def _build_analysis_prompt(self) -> str:
- """Build the prompt for analyzing the HAR file."""
if self.output_mode == "docs":
+ return load("partials/_docs_instructions", scripts_dir=str(self.scripts_dir))
+
+ return load(
+ f"partials/_language_{self.output_language}",
+ scripts_dir=str(self.scripts_dir),
+ client_filename=self._get_client_filename(),
+ run_command=self._get_run_command(),
+ )
+
+ def _build_prompts(self) -> tuple[str, str]:
+ """Build the (system_prompt, user_message) pair for analysis.
+
+ Returns:
+ Tuple of (system_prompt_text, user_message_text).
+ """
+ from .prompts import load
+
+ is_docs = self.output_mode == "docs"
+ language_name = self._get_language_name()
+
+ if is_docs:
mode_description = "generate an OpenAPI 3.0 specification documenting"
task_description = "OpenAPI documentation"
else:
- language_name = self._get_language_name()
- mode_description = f"reverse engineer API calls and generate production-ready {language_name} code that replicates"
+ mode_description = (
+ f"reverse engineer API calls and generate production-ready "
+ f"{language_name} code that replicates"
+ )
task_description = f"{language_name} API client"
attempt_log_section = (
""
- if self.output_mode == "docs"
+ if is_docs
else (
"If your first attempt doesn't work, analyze what went wrong and try again. "
"Document each attempt and what you learned.\n\n"
@@ -620,116 +468,65 @@ Your OpenAPI spec should be production-ready and suitable for:
"</attempt_log>\n\n"
)
)
- after_verb = "documenting" if self.output_mode == "docs" else "testing"
- output_type = "spec" if self.output_mode == "docs" else "code"
- quality_check = "The completeness and accuracy of the OpenAPI spec" if self.output_mode == "docs" else "Whether the implementation works"
-
- base_prompt = f"""You are tasked with analyzing a HAR (HTTP Archive) file to {mode_description} those calls.
-
-Here is the HAR file path you need to analyze:
-<har_path>
-{self.har_path}
-</har_path>
-
-Here is the original user prompt with context about what they're trying to accomplish:
-<user_prompt>
-{self.prompt}
-</user_prompt>
-
-Here is the output directory where you should save your generated files:
-<output_dir>
-{self.scripts_dir}
-</output_dir>
-{self._get_existing_client_guidance()}
-
-**IMPORTANT: You have access to the AskUserQuestion tool to ask clarifying questions during your analysis.**
-Use this tool when you need to clarify functional requirements, prioritize features, choose between implementation approaches, or gather any other information that would help you generate better {task_description}.
-
-The AskUserQuestion tool supports:
-- **Multiple questions** in a single call (list of question objects)
-- **Single-select** questions with predefined options (user picks one, or types a custom answer)
-- **Multi-select** questions with predefined options (user picks multiple, or adds a custom answer)
-- **Free-form** questions with no options (user types their answer freely)
-
-Use free-form questions (empty options list) for open-ended input like URLs, credentials, descriptions, or any question where predefined choices don't make sense.
-
-Your task is to:
-
-1. **Read and analyze the HAR file** to understand all API calls that were captured. Look for:
- - HTTP methods (GET, POST, PUT, DELETE, etc.)
- - Request URLs and endpoints
- - Request headers (especially authentication-related ones)
- - Request bodies and parameters
- - Response structures
- - Response status codes
-
-2. **Identify authentication patterns** such as:
- - Cookies and session tokens
- - Authorization headers (Bearer tokens, API keys, etc.)
- - CSRF tokens or other security mechanisms
- - Custom authentication headers
-
-3. **Extract request/response patterns** for each distinct endpoint:
- - Required vs optional parameters
- - Data formats (JSON, form data, etc.)
- - Query parameters vs body parameters
- - Response data structures
-
-4. **Ask clarifying questions using AskUserQuestion** if needed:
- - When multiple authentication methods are found, ask which to prioritize
- - If uncertain about feature priorities, ask the user
- - When implementation approaches are ambiguous, ask for preferences
- - Use the tool for any clarifications that would improve the final output
-
-{self._get_docs_instructions() if self.output_mode == "docs" else self._get_language_instructions()}
-
-Before generating your output, use a scratchpad to plan your approach:
-
-<scratchpad>
-In your scratchpad:
-- Summarize the key API endpoints found in the HAR file
-- Note the authentication mechanism being used
-- Identify any patterns or commonalities between requests
-- Plan the structure of your {task_description}
-- Consider potential issues (rate limiting, versioning, etc.)
-{"- Decide whether `requests` will be sufficient or if Playwright is needed" if self.output_mode != "docs" else ""}
-- Identify any ambiguities or questions you should ask the user using AskUserQuestion
-</scratchpad>
-
-{attempt_log_section}After {after_verb}, provide your final response with:
-- A summary of the APIs discovered
-- The authentication method used
-- {quality_check}
-- Any limitations or caveats
-- The paths to the generated files
-
-Your final output should confirm that the files have been created and provide a brief summary of what was accomplished.
-Do not include the full {output_type} in your response - just confirm the files were saved and summarize the key findings.
-"""
- if self.additional_instructions:
- base_prompt += f"\n\nAdditional instructions:\n{self.additional_instructions}"
-
- tag_context = f"""
-## Tag-Based Workflows
-
-This session uses tag-based context loading:
-
-- **@id <run_id>** {"@docs" if self.output_mode == "docs" else ""}: {"Documentation" if self.output_mode == "docs" else "Re-engineer"} mode active
- - Target run: {self.run_id}
- - HAR location: {self.har_path.parent}
- - Existing {"docs" if self.output_mode == "docs" else "scripts"}: {self.scripts_dir}
- - Message history: {self.message_store.messages_path.parent} (available for reference if needed)
- - Fresh mode: {str(self.is_fresh).lower()}
-
-By default, treat this as an iterative refinement. The user's prompt describes
-changes or improvements to make to the existing {"documentation" if self.output_mode == "docs" else "script"}. If fresh mode is enabled,
-ignore previous implementation and start from scratch.
-
-Note: Full message history is available at the messages path above if you need
-to understand previous context, but it is not automatically loaded into this
-conversation.
-"""
- return base_prompt + tag_context
+
+ scratchpad_extra = (
+ ""
+ if is_docs
+ else "- Decide whether `requests` will be sufficient or if Playwright is needed"
+ )
+
+ system_prompt = load(
+ "engineer/system",
+ mode_description=mode_description,
+ task_description=task_description,
+ codegen_instructions=self._get_codegen_instructions(),
+ scratchpad_extra=scratchpad_extra,
+ attempt_log_section=attempt_log_section,
+ after_verb="documenting" if is_docs else "testing",
+ quality_check=(
+ "The completeness and accuracy of the OpenAPI spec"
+ if is_docs
+ else "Whether the implementation works"
+ ),
+ output_type="spec" if is_docs else "code",
+ )
+
+ additional_instructions = (
+ f"\n\nAdditional instructions:\n{self.additional_instructions}"
+ if self.additional_instructions
+ else ""
+ )
+
+ user_message = load(
+ "engineer/user",
+ har_path=str(self.har_path),
+ prompt=self.prompt,
+ scripts_dir=str(self.scripts_dir),
+ existing_client_guidance=self._get_existing_client_guidance(),
+ additional_instructions=additional_instructions,
+ tag_extra="@docs" if is_docs else "",
+ tag_mode_label="Documentation" if is_docs else "Re-engineer",
+ run_id=self.run_id,
+ har_parent=str(self.har_path.parent),
+ existing_label="docs" if is_docs else "scripts",
+ messages_path=str(self.message_store.messages_path.parent),
+ is_fresh=str(self.is_fresh).lower(),
+ existing_artifact="documentation" if is_docs else "script",
+ )
+
+ return system_prompt, user_message
+
+ def _get_auto_output_files(self, language_name: str, client_filename: str) -> str:
+ """Return the output files list for auto mode prompts."""
+ base = (
+ f"1. `{self.scripts_dir}/{client_filename}` - Production {language_name} API client\n"
+ f"2. `{self.scripts_dir}/README.md` - Documentation with usage examples"
+ )
+ if self.output_language == "javascript":
+ return base + f"\n3. `{self.scripts_dir}/package.json` - Only if external dependencies are needed"
+ elif self.output_language == "typescript":
+ return base + f"\n3. `{self.scripts_dir}/package.json` - Dependencies and run scripts"
+ return base
@abstractmethod
async def analyze_and_generate(self) -> dict[str, Any] | None:
diff --git a/src/reverse_api/cli.py b/src/reverse_api/cli.py
index ade24c3..8c6f32d 100644
--- a/src/reverse_api/cli.py
+++ b/src/reverse_api/cli.py
@@ -719,16 +719,15 @@ def handle_settings(mode_color=THEME_PRIMARY):
console.print(f" [dim]updated[/dim] agent provider: {provider}")
if provider == "chrome-mcp":
console.print()
- console.print(" [bold yellow]Chrome DevTools MCP Setup[/bold yellow]")
+ console.print(" [dim]chrome devtools mcp setup:[/dim]")
+ console.print(" [dim] 1. open chrome (version 146 or newer)[/dim]")
+ console.print(" [dim] 2. go to chrome://inspect/#remote-debugging[/dim]")
+ console.print(' [dim] 3. click "Enable auto-connect"[/dim]')
+ console.print(" [dim] 4. node.js v20.19+ required[/dim]")
console.print()
- console.print(" [white]1.[/white] Open Chrome (version 146 or newer)")
- console.print(" [white]2.[/white] Navigate to [cyan]chrome://inspect/#remote-debugging[/cyan]")
- console.print(' [white]3.[/white] Click [bold]"Enable auto-connect"[/bold]')
- console.print(" [white]4.[/white] Make sure Node.js v20.19+ is installed")
- console.print()
- console.print(" [dim]The agent will connect to your real Chrome browser via auto-connect.[/dim]")
- console.print(" [dim]Your existing sessions, cookies, and auth will be available.[/dim]")
- console.print(" [dim]Avoid browsing sensitive sites while the agent is active.[/dim]")
+ console.print(" [dim]the agent will connect to your real chrome browser.[/dim]")
+ console.print(" [dim]existing sessions, cookies, and auth will be available.[/dim]")
+ console.print(" [dim]avoid browsing sensitive sites while the agent is active.[/dim]")
console.print()
elif action == "opencode_provider":
diff --git a/src/reverse_api/collector.py b/src/reverse_api/collector.py
index dc5e742..d061525 100644
--- a/src/reverse_api/collector.py
+++ b/src/reverse_api/collector.py
@@ -74,7 +74,8 @@ class Collector:
self.items_path = self._collected_dir / "items.jsonl"
- self.message_store.save_prompt(self._build_collector_prompt())
+ self._system_prompt, self._user_message = self._build_prompts()
+ self.message_store.save_prompt(self._user_message)
result = await self._agent_loop()
@@ -83,40 +84,22 @@ class Collector:
return result
- def _build_collector_prompt(self) -> str:
- """Build system prompt for collector agent."""
- return f"""You are a web data collection agent.
+ def _build_prompts(self) -> tuple[str, str]:
+ """Build (system_prompt, user_message) for the collector agent."""
+ from .prompts import load
-<mission>
-{self.prompt}
-</mission>
-
-<output>
-Save collected items to: {self.items_path}
-Format: JSONL (one JSON object per line, append mode)
-</output>
-
-## Guidelines
-
-- Use WebFetch or WebSearch to find relevant sources
-- Extract structured data with consistent field names across items
-- Include source_url in each item when possible
-- Save items incrementally as you find them
-- Aim for complete data, but partial items are still valuable
-
-## Output Format
-
-Each item should be a single-line JSON object:
-```
-{{"name": "...", "website": "...", "description": "...", "source_url": "..."}}
-```
-
-When complete, briefly summarize what was collected.
-"""
+ system_prompt = load("collector/system")
+ user_message = load(
+ "collector/user",
+ prompt=self.prompt,
+ items_path=str(self.items_path),
+ )
+ return system_prompt, user_message
async def _agent_loop(self) -> dict[str, Any] | None:
"""Run Claude Agent SDK loop."""
options = ClaudeAgentOptions(
+ system_prompt=self._system_prompt,
permission_mode="bypassPermissions",
allowed_tools=[
"Read",
@@ -131,7 +114,7 @@ When complete, briefly summarize what was collected.
try:
async with ClaudeSDKClient(options=options) as client:
- await client.query(self._build_collector_prompt())
+ await client.query(self._user_message)
async for message in client.receive_response():
# Track usage
diff --git a/src/reverse_api/copilot_engineer.py b/src/reverse_api/copilot_engineer.py
index de6922b..4c9dc90 100644
--- a/src/reverse_api/copilot_engineer.py
+++ b/src/reverse_api/copilot_engineer.py
@@ -72,8 +72,9 @@ class CopilotEngineer(BaseEngineer):
self.ui.header(self.run_id, self.prompt, self.copilot_model, self.sdk, mode="engineer")
self.ui.start_analysis()
- prompt = self._build_analysis_prompt()
- self.message_store.save_prompt(prompt)
+ system_prompt, user_message = self._build_prompts()
+ prompt = f"{system_prompt}\n\n{user_message}"
+ self.message_store.save_prompt(user_message)
done_event = asyncio.Event()
loop = asyncio.get_running_loop()
diff --git a/src/reverse_api/engineer.py b/src/reverse_api/engineer.py
index b5f21d8..b958f4f 100644
--- a/src/reverse_api/engineer.py
+++ b/src/reverse_api/engineer.py
@@ -144,12 +144,15 @@ class ClaudeEngineer(BaseEngineer):
"""
self.ui.header(self.run_id, self.prompt, self.model, self.sdk, mode="engineer")
self.ui.start_analysis()
- self.message_store.save_prompt(self._build_analysis_prompt())
+
+ system_prompt, user_message = self._build_prompts()
+ self.message_store.save_prompt(user_message)
options = ClaudeAgentOptions(
+ system_prompt=system_prompt,
permission_mode="acceptEdits",
can_use_tool=self._handle_tool_permission,
- cwd=str(self.scripts_dir.parent.parent), # Project root
+ cwd=str(self.scripts_dir.parent.parent),
model=self.model,
env={"CLAUDECODE": ""},
stderr=self._handle_cli_stderr,
@@ -159,7 +162,7 @@ class ClaudeEngineer(BaseEngineer):
try:
async with ClaudeSDKClient(options=options) as client:
- await client.query(self._build_analysis_prompt())
+ await client.query(user_message)
# Process initial response
last_result = await self._process_streaming_response(client)
diff --git a/src/reverse_api/native_host.py b/src/reverse_api/native_host.py
index bc836df..a06a5c6 100644
--- a/src/reverse_api/native_host.py
+++ b/src/reverse_api/native_host.py
@@ -748,33 +748,16 @@ This script was generated by the Reverse API Engineer Chrome Extension.
scripts_dir = get_scripts_dir(run_id)
scripts_dir.mkdir(parents=True, exist_ok=True)
- # Build the prompt with HAR context
- har_content = har_path.read_text()
+ from .prompts import load
- # System prompt for API client generation
- system_context = f"""You are an expert at reverse engineering APIs from HTTP traffic.
-
-The user has captured browser traffic (HAR format) and wants to create a Python API client.
-
-HAR file location: {har_path}
-Output directory: {scripts_dir}
-
-When analyzing, focus on:
-1. Authentication patterns (cookies, tokens, headers)
-2. API endpoints and their purposes
-3. Request/response formats
-4. Rate limiting or pagination patterns
-
-Generate clean, production-ready Python code with:
-- Type hints
-- Error handling
-- Session management
-- Docstrings
-
-The HAR content is available at the path above. Use the Read tool to analyze it.
-"""
+ system_prompt = load(
+ "chat/system",
+ har_path=str(har_path),
+ scripts_dir=str(scripts_dir),
+ )
options = ClaudeAgentOptions(
+ system_prompt=system_prompt,
allowed_tools=[
"Read",
"Write",
@@ -789,9 +772,7 @@ The HAR content is available at the path above. Use the Read tool to analyze it.
try:
async with ClaudeSDKClient(options=options) as client:
- # Send the user message with context
- full_prompt = f"{system_context}\n\nUser request: {user_message}"
- await client.query(full_prompt)
+ await client.query(user_message)
final_text = ""
last_tool_name = None
diff --git a/src/reverse_api/opencode_engineer.py b/src/reverse_api/opencode_engineer.py
index 4c5fb2b..7c5e9d9 100644
--- a/src/reverse_api/opencode_engineer.py
+++ b/src/reverse_api/opencode_engineer.py
@@ -139,8 +139,9 @@ class OpenCodeEngineer(BaseEngineer):
self.opencode_ui.header(self.run_id, self.prompt, self.opencode_model, self.sdk, mode="engineer")
self.opencode_ui.start_analysis()
- # Save the prompt to messages
- self.message_store.save_prompt(self._build_analysis_prompt())
+ system_prompt, user_message = self._build_prompts()
+ combined_prompt = f"{system_prompt}\n\n{user_message}"
+ self.message_store.save_prompt(user_message)
try:
auth = self._get_auth()
@@ -190,7 +191,7 @@ class OpenCodeEngineer(BaseEngineer):
"providerID": self.opencode_provider,
"modelID": model_id,
},
- "parts": [{"type": "text", "text": self._build_analysis_prompt()}],
+ "parts": [{"type": "text", "text": combined_prompt}],
}
prompt_r = await client.post(f"/session/{self._session_id}/message", json=prompt_body)
diff --git a/src/reverse_api/prompts/__init__.py b/src/reverse_api/prompts/__init__.py
new file mode 100644
index 0000000..9c0cb6e
--- /dev/null
+++ b/src/reverse_api/prompts/__init__.py
@@ -0,0 +1,67 @@
+"""Prompt template loader for reverse-api-engineer.
+
+All LLM prompt text lives in `.md` files alongside this module.
+Templates use `{placeholder}` syntax for dynamic values and
+`{include:_partial_name}` to inline shared partials (resolved from
+the `partials/` subdirectory).
+
+Template names use `/` as a path separator, e.g. `"auto/system"` resolves
+to `auto/system.md` relative to this package directory.
+"""
+
+from pathlib import Path
+
+_PROMPTS_DIR = Path(__file__).parent
+_PARTIALS_DIR = _PROMPTS_DIR / "partials"
+
+_INCLUDE_PREFIX = "{include:"
+_INCLUDE_SUFFIX = "}"
+
+
+def _resolve_includes(text: str) -> str:
+ """Recursively resolve `{include:_partial_name}` directives."""
+ while _INCLUDE_PREFIX in text:
+ start = text.index(_INCLUDE_PREFIX)
+ end = text.index(_INCLUDE_SUFFIX, start + len(_INCLUDE_PREFIX))
+ partial_name = text[start + len(_INCLUDE_PREFIX) : end]
+ partial_path = _PARTIALS_DIR / f"{partial_name}.md"
+ partial_text = partial_path.read_text()
+ partial_text = _resolve_includes(partial_text)
+ text = text[:start] + partial_text + text[end + 1 :]
+ return text
+
+
+def load(template_name: str, **kwargs: str) -> str:
+ """Load a markdown prompt template and fill placeholders.
+
+ Args:
+ template_name: Path to the `.md` file (without extension),
+ e.g. ``"auto/system"`` or ``"collector/user"``.
+ **kwargs: Values to substitute for `{placeholder}` tokens.
+
+ Returns:
+ The fully rendered prompt string.
+ """
+ path = _PROMPTS_DIR / f"{template_name}.md"
+ text = path.read_text()
+ text = _resolve_includes(text)
+ if kwargs:
+ text = text.format_map(kwargs)
+ return text
+
+
+def load_language_partial(language: str, **kwargs: str) -> str:
+ """Load the language-specific codegen instructions partial.
+
+ Args:
+ language: One of "python", "javascript", "typescript".
+ **kwargs: Placeholder values (scripts_dir, client_filename, run_command).
+ """
+ return load(f"partials/_language_{language}", **kwargs)
+
+
+FOLDER_NAME_PROMPT = (
+ "Generate a short folder name (1-3 words, lowercase, underscores) "
+ "for this task: {prompt}\n\n"
+ "Respond with ONLY the folder name, nothing else. Example: apple_jobs_api"
+)
diff --git a/src/reverse_api/prompts/auto/system.md b/src/reverse_api/prompts/auto/system.md
new file mode 100644
index 0000000..34cba02
--- /dev/null
+++ b/src/reverse_api/prompts/auto/system.md
@@ -0,0 +1,23 @@
+You are an autonomous AI agent with browser control via {browser_tool_label} tools.
+Your mission is to browse, monitor network traffic, and generate production-ready {language_name} API code.
+
+**Core principle:** The generated scripts must work immediately with zero user effort. Hardcode all credentials, cookies, tokens, and session data you discover. No env vars, no config files, no manual setup required. If you observe a token refresh, cookie renewal, or login flow in the traffic, implement automatic re-authentication so the script doesn't go stale.
+
+**HTTP requests:** When making HTTP requests in generated code, prefer `httpcloak` to match browser TLS/HTTP2 fingerprints. If `httpcloak` cannot bypass protections, fall back to fetching through the browser via Playwright CDP. Only use full browser automation as a last resort.
+
+## Code generation
+
+{codegen_instructions}
+
+## Guidelines
+
+- Narrate your actions as you browse
+- Capture all necessary API calls before generating code
+- Test your generated code to verify it works
+- Screenshots must be under 1MB — prefer element-specific screenshots or use snapshots for structure
+
+## Output files
+
+{output_files}
+
+Confirm the files were created and briefly summarize: APIs discovered, auth method, whether it works, any caveats.
\ No newline at end of file
diff --git a/src/reverse_api/prompts/auto/user_chrome_mcp.md b/src/reverse_api/prompts/auto/user_chrome_mcp.md
new file mode 100644
index 0000000..f492813
--- /dev/null
+++ b/src/reverse_api/prompts/auto/user_chrome_mcp.md
@@ -0,0 +1,43 @@
+<mission>
+{prompt}
+</mission>
+
+<output_directory>
+{scripts_dir}
+</output_directory>
+
+You are connected to the user's REAL Chrome browser with their existing sessions, cookies, and authentication.
+
+## Workflow
+
+Use this workflow as a guide — adapt as needed:
+
+### Phase 1: BROWSE
+Use Chrome DevTools MCP tools to accomplish the mission goal. Available tools:
+- `navigate_page` - Navigate to a URL (type: "url", url: "...")
+- `click` - Click an element by uid
+- `fill` - Type text into an input (uid, value)
+- `fill_form` - Fill multiple form elements
+- `hover` - Hover over an element
+- `press_key` - Press a key combination
+- `new_page` / `list_pages` / `select_page` - Tab management
+- `wait_for` - Wait for text to appear
+- `take_snapshot` - Get accessibility tree (gives element uids for click/fill)
+- `take_screenshot` - Visual context (prefer snapshots to avoid 1MB limit)
+- `evaluate_script` - Execute JavaScript
+- `list_console_messages` - Check console
+
+The user's existing login sessions and cookies are available — you do NOT need to log in where they're already authenticated.
+
+### Phase 2: MONITOR
+Periodically call `list_network_requests()` to monitor API traffic. Use `get_network_request(reqid)` for full request/response details on important calls. Focus on XHR/fetch requests, auth headers, and response bodies.
+
+### Phase 3: CAPTURE
+When done, call `list_network_requests()` one final time and use `get_network_request(reqid)` to capture full details for each important API request.
+
+There is no HAR file — capture all network data you need using these tools before proceeding.
+
+### Phase 4: REVERSE ENGINEER
+Based on the network data you captured, generate the code. Extract all API calls, authentication patterns, and data structures.
+
+Leverage existing auth from the user's browser sessions when possible.
\ No newline at end of file
diff --git a/src/reverse_api/prompts/auto/user_playwright.md b/src/reverse_api/prompts/auto/user_playwright.md
new file mode 100644
index 0000000..2eba890
--- /dev/null
+++ b/src/reverse_api/prompts/auto/user_playwright.md
@@ -0,0 +1,37 @@
+<mission>
+{prompt}
+</mission>
+
+<output_directory>
+{scripts_dir}
+</output_directory>
+
+## Workflow
+
+Use this workflow as a guide — adapt as needed:
+
+### Phase 1: BROWSE
+Use browser MCP tools to accomplish the mission goal. Some available tools:
+- `browser_navigate` - Navigate to a URL
+- `browser_click` - Click an element
+- `browser_scroll` - Scroll the page
+- `browser_close` - Close the browser
+- `browser_evaluate` - Evaluate JavaScript code
+- `browser_press_key` - Press a key
+- `browser_run_code` - Run Playwright code
+- `browser_type` - Type text into input
+- `browser_wait_for` - Wait for text/time
+- `browser_snapshot` - Get accessibility tree (good alternative to screenshots)
+- `browser_take_screenshot` - Take screenshot (prefer element-specific to avoid 1MB limit)
+- `browser_network_requests` - List captured network requests
+
+### Phase 2: MONITOR
+Periodically call `browser_network_requests()` to monitor API traffic. You'll also get full traffic when closing the browser. Look for auth patterns (cookies, tokens, headers), endpoints, and response structures.
+
+### Phase 3: CAPTURE
+When done, call `browser_close()` to save the HAR file to: {har_path}
+
+### Phase 4: REVERSE ENGINEER
+Analyze the HAR file at `{har_path}` and generate the code. Extract all API calls, authentication patterns, and data structures.
+
+Call `browser_network_requests()` frequently to monitor traffic.
\ No newline at end of file
diff --git a/src/reverse_api/prompts/chat/system.md b/src/reverse_api/prompts/chat/system.md
new file mode 100644
index 0000000..452b766
--- /dev/null
+++ b/src/reverse_api/prompts/chat/system.md
@@ -0,0 +1,20 @@
+You are an expert at reverse engineering APIs from HTTP traffic.
+
+The user has captured browser traffic (HAR format) and wants to create a Python API client.
+
+HAR file location: {har_path}
+Output directory: {scripts_dir}
+
+When analyzing, focus on:
+1. Authentication patterns (cookies, tokens, headers)
+2. API endpoints and their purposes
+3. Request/response formats
+4. Rate limiting or pagination patterns
+
+Generate clean, production-ready Python code with:
+- Type hints
+- Error handling
+- Session management
+- Docstrings
+
+The HAR content is available at the path above. Use the Read tool to analyze it.
\ No newline at end of file
diff --git a/src/reverse_api/prompts/collector/system.md b/src/reverse_api/prompts/collector/system.md
new file mode 100644
index 0000000..256ef34
--- /dev/null
+++ b/src/reverse_api/prompts/collector/system.md
@@ -0,0 +1,18 @@
+You are a web data collection agent.
+
+## Guidelines
+
+- Use WebFetch or WebSearch to find relevant sources
+- Extract structured data with consistent field names across items
+- Include source_url in each item when possible
+- Save items incrementally as you find them
+- Aim for complete data, but partial items are still valuable
+
+## Output Format
+
+Each item should be a single-line JSON object:
+```
+{{"name": "...", "website": "...", "description": "...", "source_url": "..."}}
+```
+
+When complete, briefly summarize what was collected.
\ No newline at end of file
diff --git a/src/reverse_api/prompts/collector/user.md b/src/reverse_api/prompts/collector/user.md
new file mode 100644
index 0000000..7ccc8cf
--- /dev/null
+++ b/src/reverse_api/prompts/collector/user.md
@@ -0,0 +1,8 @@
+<mission>
+{prompt}
+</mission>
+
+<output>
+Save collected items to: {items_path}
+Format: JSONL (one JSON object per line, append mode)
+</output>
\ No newline at end of file
diff --git a/src/reverse_api/prompts/engineer/system.md b/src/reverse_api/prompts/engineer/system.md
new file mode 100644
index 0000000..6c3a82b
--- /dev/null
+++ b/src/reverse_api/prompts/engineer/system.md
@@ -0,0 +1,34 @@
+You are tasked with analyzing a HAR (HTTP Archive) file to {mode_description} those calls.
+
+**Core principle:** The generated output must work immediately with zero user effort. Hardcode all credentials, cookies, tokens, and session data found in the traffic. No env vars, no config files, no manual setup. If the traffic reveals a token refresh or login flow, implement automatic re-authentication so the script doesn't go stale when cookies or tokens expire.
+
+You have access to the AskUserQuestion tool to ask clarifying questions during your analysis. Use it when you need to clarify requirements, prioritize features, or choose between approaches. It supports single-select, multi-select, and free-form questions.
+
+## Analysis guidelines
+
+These are guidelines for your analysis, not a rigid checklist — use your judgment:
+
+1. **Read the HAR file** — understand the API surface: endpoints, methods, headers, request/response shapes, status codes
+2. **Identify auth patterns** — cookies, Bearer tokens, API keys, CSRF tokens, session tokens. Hardcode whatever you find
+3. **Extract endpoint patterns** — required vs optional params, data formats, query vs body params
+4. **Ask the user** if anything is ambiguous (which auth to prioritize, feature priorities, implementation approach)
+
+{codegen_instructions}
+
+Plan your approach in a scratchpad before generating:
+
+<scratchpad>
+- Key endpoints and auth mechanism
+- Structure of your {task_description}
+{scratchpad_extra}
+- Any questions to ask the user
+</scratchpad>
+
+{attempt_log_section}After {after_verb}, provide your final response with:
+- A summary of the APIs discovered
+- The authentication method used
+- {quality_check}
+- Any limitations or caveats
+- The paths to the generated files
+
+Do not include the full {output_type} in your response - just confirm the files were saved and summarize the key findings.
\ No newline at end of file
diff --git a/src/reverse_api/prompts/engineer/user.md b/src/reverse_api/prompts/engineer/user.md
new file mode 100644
index 0000000..b265f47
--- /dev/null
+++ b/src/reverse_api/prompts/engineer/user.md
@@ -0,0 +1,34 @@
+Here is the HAR file path you need to analyze:
+<har_path>
+{har_path}
+</har_path>
+
+Here is the original user prompt with context about what they're trying to accomplish:
+<user_prompt>
+{prompt}
+</user_prompt>
+
+Here is the output directory where you should save your generated files:
+<output_dir>
+{scripts_dir}
+</output_dir>
+{existing_client_guidance}
+{additional_instructions}
+## Tag-Based Workflows
+
+This session uses tag-based context loading:
+
+- **@id <run_id>** {tag_extra}: {tag_mode_label} mode active
+ - Target run: {run_id}
+ - HAR location: {har_parent}
+ - Existing {existing_label}: {scripts_dir}
+ - Message history: {messages_path} (available for reference if needed)
+ - Fresh mode: {is_fresh}
+
+By default, treat this as an iterative refinement. The user's prompt describes
+changes or improvements to make to the existing {existing_artifact}. If fresh mode is enabled,
+ignore previous implementation and start from scratch.
+
+Note: Full message history is available at the messages path above if you need
+to understand previous context, but it is not automatically loaded into this
+conversation.
\ No newline at end of file
diff --git a/src/reverse_api/prompts/partials/_docs_instructions.md b/src/reverse_api/prompts/partials/_docs_instructions.md
new file mode 100644
index 0000000..eec194a
--- /dev/null
+++ b/src/reverse_api/prompts/partials/_docs_instructions.md
@@ -0,0 +1,20 @@
+**Generate an OpenAPI 3.0 specification** documenting the API endpoints found in the traffic. Guidelines — use your judgment:
+
+- Use OpenAPI 3.0.0 format
+- Include all discovered endpoints with methods, parameters, request/response schemas, and auth schemes
+- Organize endpoints into logical tags/groups
+- Infer meaningful descriptions for endpoints, parameters, and response fields
+- Use JSON Schema `$ref` for shared components
+- Add a `servers` array with the base URL from the HAR
+
+**Enhance with inference:**
+- Identify required vs optional params, add example values from captured requests
+- Document error responses and rate limiting headers if observed
+- Describe multi-step auth flows if present
+
+**Supplementary docs:**
+- Generate a README.md covering: API overview, auth method, base URL, common use cases, rate limiting, special headers
+
+Save the OpenAPI spec to: `{scripts_dir}/openapi.json`
+Save the README to: `{scripts_dir}/README.md`
+Optionally create: `{scripts_dir}/examples.md` with curl examples
\ No newline at end of file
diff --git a/src/reverse_api/prompts/partials/_language_javascript.md b/src/reverse_api/prompts/partials/_language_javascript.md
new file mode 100644
index 0000000..26aca5b
--- /dev/null
+++ b/src/reverse_api/prompts/partials/_language_javascript.md
@@ -0,0 +1,22 @@
+**Generate a JavaScript module** that replicates the API calls found in the traffic. The following are guidelines — use your judgment:
+
+- Use modern JavaScript (ES2022+) with ESM modules
+- Prefer native `fetch` (Node.js 18+); use `axios` only if you need retries or interceptors
+- Create separate async functions for each endpoint
+- Add JSDoc comments and error handling where they add clarity
+- Include example usage in a main section
+- If using external deps, generate a `package.json` with `"type": "module"`
+
+**Authentication & credentials:**
+- Hardcode all cookies, tokens, session IDs, and auth headers found in the traffic directly in the script
+- The user should be able to run the script immediately with zero configuration — no env vars, no config files, no manual setup
+- Handle auth refresh so the script doesn't go stale: if you see a token refresh or login endpoint in the traffic, implement automatic re-authentication on 401/403. If cookies have expiry, re-fetch them before they expire
+
+**Testing:**
+- If `package.json` was generated, first run: `npm install`
+- Run with: `{run_command}`
+- You have up to 5 attempts to fix issues
+
+Save the module to: `{scripts_dir}/{client_filename}`
+Save documentation to: `{scripts_dir}/README.md`
+If external dependencies are used, save: `{scripts_dir}/package.json`
\ No newline at end of file
diff --git a/src/reverse_api/prompts/partials/_language_python.md b/src/reverse_api/prompts/partials/_language_python.md
new file mode 100644
index 0000000..ba72191
--- /dev/null
+++ b/src/reverse_api/prompts/partials/_language_python.md
@@ -0,0 +1,25 @@
+**Generate a Python script** using `requests` that replicates the API calls found in the traffic. The following are guidelines — use your judgment on what's appropriate for the specific API:
+
+- Prefer `requests` with a `Session` for connection reuse and cookie persistence
+- Create separate functions for each distinct API endpoint
+- Include type hints, docstrings, and error handling where they add clarity
+- Include a `main` section with example usage
+
+**Authentication & credentials:**
+- Hardcode all cookies, tokens, session IDs, and auth headers found in the traffic directly in the script
+- The user should be able to run the script immediately with zero configuration — no env vars, no config files, no manual setup
+- If the API uses cookies, set them on the session directly
+- If the API uses Bearer tokens or API keys, hardcode them in the headers
+- Handle auth refresh so the script doesn't go stale: if you see a token refresh endpoint, OAuth refresh flow, or login endpoint in the traffic, implement automatic re-authentication when a request returns 401/403. If cookies have expiry, re-fetch them before they expire
+
+**Bot detection:**
+- If you encounter bot detection or anti-scraping measures, first try `httpcloak` to cloak your HTTP fingerprint (TLS, HTTP/2, header order)
+- If `httpcloak` cannot bypass the protection, fall back to making fetch requests through the browser via Playwright CDP
+- As a last resort, use full Playwright browser automation
+
+**Testing:**
+- After generating the code, test it: `{run_command}`
+- You have up to 5 attempts to fix issues
+
+Save the script to: `{scripts_dir}/{client_filename}`
+Save documentation to: `{scripts_dir}/README.md`
\ No newline at end of file
diff --git a/src/reverse_api/prompts/partials/_language_typescript.md b/src/reverse_api/prompts/partials/_language_typescript.md
new file mode 100644
index 0000000..8b68e98
--- /dev/null
+++ b/src/reverse_api/prompts/partials/_language_typescript.md
@@ -0,0 +1,21 @@
+**Generate a TypeScript module** that replicates the API calls found in the traffic. The following are guidelines — use your judgment:
+
+- Use strict typing with interfaces for request/response types
+- Use ESM modules and native `fetch` (Node.js 18+); use `axios` only if needed
+- Create separate async functions for each endpoint
+- Export a class-based API client with proper encapsulation
+- Include example usage in a main section
+- Generate a `package.json` with `"type": "module"`, `tsx`, `typescript`, `@types/node`
+
+**Authentication & credentials:**
+- Hardcode all cookies, tokens, session IDs, and auth headers found in the traffic directly in the script
+- The user should be able to run the script immediately with zero configuration — no env vars, no config files, no manual setup
+- Handle auth refresh so the script doesn't go stale: if you see a token refresh or login endpoint in the traffic, implement automatic re-authentication on 401/403. If cookies have expiry, re-fetch them before they expire
+
+**Testing:**
+- Run: `npm install && {run_command}`
+- You have up to 5 attempts to fix issues
+
+Save the module to: `{scripts_dir}/{client_filename}`
+Save documentation to: `{scripts_dir}/README.md`
+Save the package.json to: `{scripts_dir}/package.json`
\ No newline at end of file
diff --git a/src/reverse_api/utils.py b/src/reverse_api/utils.py
index fba9dff..e6b4da1 100644
--- a/src/reverse_api/utils.py
+++ b/src/reverse_api/utils.py
@@ -43,6 +43,9 @@ def generate_folder_name(prompt: str, sdk: str = None, session_id: str = None) -
sdk: The SDK to use ("opencode" or "claude"). If None, checks config.
session_id: Optional OpenCode session ID to reuse. Only used when sdk="opencode".
"""
+ from rich.console import Console
+ from rich.status import Status
+
# Get SDK from config if not provided
if sdk is None:
try:
@@ -64,10 +67,12 @@ def generate_folder_name(prompt: str, sdk: str = None, session_id: str = None) -
# Already in async context, use fallback to avoid nested asyncio.run
return _slugify(prompt)
- if sdk == "opencode":
- return asyncio.run(_generate_folder_name_opencode_async(prompt, session_id))
- else:
- return asyncio.run(_generate_folder_name_async(prompt))
+ console = Console()
+ with Status(" [dim]generating folder name...[/dim]", console=console, spinner="dots", spinner_style="dim"):
+ if sdk == "opencode":
+ return asyncio.run(_generate_folder_name_opencode_async(prompt, session_id))
+ else:
+ return asyncio.run(_generate_folder_name_async(prompt))
except Exception:
pass
@@ -98,11 +103,10 @@ async def _generate_folder_name_async(prompt: str) -> str:
folder_name = ""
+ from .prompts import FOLDER_NAME_PROMPT
+
async with ClaudeSDKClient(options=options) as client:
- await client.query(
- f"Generate a short folder name (1-3 words, lowercase, underscores) for this task: {prompt}\n\n"
- f"Respond with ONLY the folder name, nothing else. Example: apple_jobs_api"
- )
+ await client.query(FOLDER_NAME_PROMPT.format(prompt=prompt))
async for message in client.receive_response():
if isinstance(message, AssistantMessage):
@@ -139,10 +143,9 @@ async def _generate_folder_name_opencode_async(prompt: str, session_id: str = No
opencode_provider = config_manager.get("opencode_provider", "anthropic")
opencode_model = config_manager.get("opencode_model", "claude-opus-4-6")
- folder_prompt = (
- f"Generate a short folder name (1-3 words, lowercase, underscores) for this task: {prompt}\n\n"
- f"Respond with ONLY the folder name, nothing else. Example: apple_jobs_api"
- )
+ from .prompts import FOLDER_NAME_PROMPT
+
+ folder_prompt = FOLDER_NAME_PROMPT.format(prompt=prompt)
async with httpx.AsyncClient(base_url=BASE_URL, timeout=15.0) as client:
try:
diff --git a/tests/test_auto_engineer.py b/tests/test_auto_engineer.py
index d7c6d2d..bd132a4 100644
--- a/tests/test_auto_engineer.py
+++ b/tests/test_auto_engineer.py
@@ -113,49 +113,52 @@ class TestClaudeAutoEngineerPrompt:
def test_python_prompt(self, tmp_path):
"""Python prompt includes correct language references."""
eng = self._make_engineer(tmp_path)
- prompt = eng._build_auto_prompt()
- assert "Python" in prompt
- assert "requests" in prompt
- assert "api_client.py" in prompt
+ sys_p, user_p = eng._build_auto_prompts()
+ combined = sys_p + user_p
+ assert "Python" in combined
+ assert "requests" in sys_p
+ assert "api_client.py" in sys_p
def test_javascript_prompt(self, tmp_path):
"""JavaScript prompt includes JS-specific instructions."""
eng = self._make_engineer(tmp_path, output_language="javascript")
- prompt = eng._build_auto_prompt()
- assert "JavaScript" in prompt
- assert "fetch" in prompt
- assert "api_client.js" in prompt
- assert "package.json" in prompt
+ sys_p, user_p = eng._build_auto_prompts()
+ combined = sys_p + user_p
+ assert "JavaScript" in combined
+ assert "fetch" in sys_p
+ assert "api_client.js" in sys_p
+ assert "package.json" in sys_p
def test_typescript_prompt(self, tmp_path):
"""TypeScript prompt includes TS-specific instructions."""
eng = self._make_engineer(tmp_path, output_language="typescript")
- prompt = eng._build_auto_prompt()
- assert "TypeScript" in prompt
- assert "interfaces" in prompt
- assert "api_client.ts" in prompt
+ sys_p, user_p = eng._build_auto_prompts()
+ combined = sys_p + user_p
+ assert "TypeScript" in combined
+ assert "interfaces" in sys_p
+ assert "api_client.ts" in sys_p
def test_prompt_includes_mcp_tools(self, tmp_path):
"""Prompt includes MCP browser tool references."""
eng = self._make_engineer(tmp_path)
- prompt = eng._build_auto_prompt()
- assert "browser_navigate" in prompt
- assert "browser_click" in prompt
- assert "browser_close" in prompt
- assert "browser_network_requests" in prompt
+ sys_p, user_p = eng._build_auto_prompts()
+ assert "browser_navigate" in user_p
+ assert "browser_click" in user_p
+ assert "browser_close" in user_p
+ assert "browser_network_requests" in user_p
def test_prompt_includes_har_path(self, tmp_path):
"""Prompt includes HAR file path."""
eng = self._make_engineer(tmp_path)
- prompt = eng._build_auto_prompt()
- assert "recording.har" in prompt
+ sys_p, user_p = eng._build_auto_prompts()
+ assert "recording.har" in user_p
def test_prompt_includes_screenshot_guidelines(self, tmp_path):
"""Prompt includes screenshot guidelines."""
eng = self._make_engineer(tmp_path)
- prompt = eng._build_auto_prompt()
- assert "Screenshot" in prompt
- assert "1MB" in prompt
+ sys_p, user_p = eng._build_auto_prompts()
+ assert "Screenshot" in sys_p or "Screenshot" in user_p
+ assert "1MB" in sys_p or "1MB" in user_p
class TestChromeMcpPrompt:
@@ -178,61 +181,61 @@ class TestChromeMcpPrompt:
def test_chrome_mcp_prompt_uses_chrome_tools(self, tmp_path):
"""Chrome MCP prompt uses Chrome DevTools tool names."""
eng = self._make_engineer(tmp_path)
- prompt = eng._build_chrome_mcp_prompt()
- assert "navigate_page" in prompt
- assert "click" in prompt
- assert "fill" in prompt
- assert "take_snapshot" in prompt
- assert "list_network_requests" in prompt
- assert "get_network_request" in prompt
+ sys_p, user_p = eng._build_auto_prompts()
+ assert "navigate_page" in user_p
+ assert "click" in user_p
+ assert "fill" in user_p
+ assert "take_snapshot" in user_p
+ assert "list_network_requests" in user_p
+ assert "get_network_request" in user_p
def test_chrome_mcp_prompt_no_har_file(self, tmp_path):
"""Chrome MCP prompt does not reference HAR file saving."""
eng = self._make_engineer(tmp_path)
- prompt = eng._build_chrome_mcp_prompt()
- assert "There is no HAR file" in prompt
- assert "browser_close" not in prompt
+ sys_p, user_p = eng._build_auto_prompts()
+ assert "There is no HAR file" in user_p
+ assert "browser_close" not in user_p
def test_chrome_mcp_prompt_mentions_real_browser(self, tmp_path):
"""Chrome MCP prompt mentions real Chrome browser."""
eng = self._make_engineer(tmp_path)
- prompt = eng._build_chrome_mcp_prompt()
- assert "REAL Chrome browser" in prompt
- assert "existing sessions" in prompt
+ sys_p, user_p = eng._build_auto_prompts()
+ assert "REAL Chrome browser" in user_p
+ assert "existing sessions" in user_p
def test_chrome_mcp_prompt_python(self, tmp_path):
"""Chrome MCP Python prompt includes correct language."""
eng = self._make_engineer(tmp_path)
- prompt = eng._build_chrome_mcp_prompt()
- assert "Python" in prompt
- assert "requests" in prompt
+ sys_p, user_p = eng._build_auto_prompts()
+ assert "Python" in sys_p
+ assert "requests" in sys_p
def test_chrome_mcp_prompt_javascript(self, tmp_path):
"""Chrome MCP JavaScript prompt includes JS instructions."""
eng = self._make_engineer(tmp_path, output_language="javascript")
- prompt = eng._build_chrome_mcp_prompt()
- assert "JavaScript" in prompt
- assert "fetch" in prompt
+ sys_p, user_p = eng._build_auto_prompts()
+ assert "JavaScript" in sys_p
+ assert "fetch" in sys_p
def test_chrome_mcp_prompt_typescript(self, tmp_path):
"""Chrome MCP TypeScript prompt includes TS instructions."""
eng = self._make_engineer(tmp_path, output_language="typescript")
- prompt = eng._build_chrome_mcp_prompt()
- assert "TypeScript" in prompt
- assert "interfaces" in prompt
+ sys_p, user_p = eng._build_auto_prompts()
+ assert "TypeScript" in sys_p
+ assert "interfaces" in sys_p
- def test_get_active_prompt_chrome_mcp(self, tmp_path):
- """_get_active_prompt returns chrome prompt for chrome-mcp provider."""
+ def test_get_active_prompts_chrome_mcp(self, tmp_path):
+ """_get_active_prompts returns chrome prompt for chrome-mcp provider."""
eng = self._make_engineer(tmp_path)
- prompt = eng._get_active_prompt()
- assert "Chrome DevTools MCP" in prompt
- assert "navigate_page" in prompt
+ sys_p, user_p = eng._get_active_prompts()
+ assert "Chrome DevTools MCP" in sys_p
+ assert "navigate_page" in user_p
- def test_get_active_prompt_auto(self, tmp_path):
- """_get_active_prompt returns auto prompt for auto provider."""
+ def test_get_active_prompts_auto(self, tmp_path):
+ """_get_active_prompts returns auto prompt for auto provider."""
eng = self._make_engineer(tmp_path, agent_provider="auto")
- prompt = eng._get_active_prompt()
- assert "browser_navigate" in prompt
+ sys_p, user_p = eng._get_active_prompts()
+ assert "browser_navigate" in user_p
class TestChromeMcpConfig:
@@ -305,15 +308,15 @@ class TestOpenCodeChromeMcpConfig:
def test_opencode_chrome_mcp_prompt(self, tmp_path):
"""OpenCode chrome-mcp uses Chrome DevTools prompt."""
eng = self._make_engineer(tmp_path, agent_provider="chrome-mcp")
- prompt = eng._get_active_prompt()
- assert "Chrome DevTools MCP" in prompt
- assert "navigate_page" in prompt
+ sys_p, user_p = eng._get_active_prompts()
+ assert "Chrome DevTools MCP" in sys_p
+ assert "navigate_page" in user_p
def test_opencode_auto_prompt(self, tmp_path):
"""OpenCode auto uses Playwright prompt."""
eng = self._make_engineer(tmp_path, agent_provider="auto")
- prompt = eng._get_active_prompt()
- assert "browser_navigate" in prompt
+ sys_p, user_p = eng._get_active_prompts()
+ assert "browser_navigate" in user_p
class TestClaudeAutoEngineerAnalyze:
@@ -636,8 +639,8 @@ class TestOpenCodeAutoEngineerInit:
assert eng.mcp_run_id == "test123"
assert eng.mcp_name is None
- def test_build_auto_prompt_reuses_claude_prompt(self, tmp_path):
- """OpenCode auto prompt reuses ClaudeAutoEngineer prompt."""
+ def test_get_active_prompts_reuses_claude_prompts(self, tmp_path):
+ """OpenCode auto prompts reuse ClaudeAutoEngineer prompt builder."""
with patch("reverse_api.auto_engineer.get_har_dir", return_value=tmp_path / "har"):
with patch("reverse_api.base_engineer.get_scripts_dir", return_value=tmp_path / "scripts"):
with patch("reverse_api.base_engineer.MessageStore"):
@@ -649,9 +652,9 @@ class TestOpenCodeAutoEngineerInit:
opencode_provider="anthropic",
opencode_model="claude-opus-4-6",
)
- prompt = eng._build_auto_prompt()
- assert "browser_navigate" in prompt
- assert "Python" in prompt
+ sys_p, user_p = eng._get_active_prompts()
+ assert "browser_navigate" in user_p
+ assert "Python" in sys_p
class TestOpenCodeAutoEngineerAnalyze:
diff --git a/tests/test_base_engineer.py b/tests/test_base_engineer.py
index 7327b3a..e08ff65 100644
--- a/tests/test_base_engineer.py
+++ b/tests/test_base_engineer.py
@@ -251,57 +251,57 @@ class TestBaseEngineerBuildPrompt:
def test_python_prompt(self, tmp_path):
"""Python prompt includes Python-specific instructions."""
eng = self._make_engineer(tmp_path, output_language="python")
- prompt = eng._build_analysis_prompt()
- assert "Python script" in prompt
- assert "requests" in prompt
+ system_prompt, user_message = eng._build_prompts()
+ assert "Python script" in system_prompt
+ assert "requests" in system_prompt
def test_javascript_prompt(self, tmp_path):
"""JavaScript prompt includes JS-specific instructions."""
eng = self._make_engineer(tmp_path, output_language="javascript")
- prompt = eng._build_analysis_prompt()
- assert "JavaScript module" in prompt
- assert "fetch" in prompt
+ system_prompt, user_message = eng._build_prompts()
+ assert "JavaScript module" in system_prompt
+ assert "fetch" in system_prompt
def test_typescript_prompt(self, tmp_path):
"""TypeScript prompt includes TS-specific instructions."""
eng = self._make_engineer(tmp_path, output_language="typescript")
- prompt = eng._build_analysis_prompt()
- assert "TypeScript module" in prompt
- assert "interfaces" in prompt
+ system_prompt, user_message = eng._build_prompts()
+ assert "TypeScript module" in system_prompt
+ assert "interfaces" in system_prompt
def test_docs_prompt(self, tmp_path):
"""Docs mode prompt includes OpenAPI instructions."""
eng = self._make_engineer(tmp_path, output_mode="docs")
- prompt = eng._build_analysis_prompt()
- assert "OpenAPI" in prompt
+ system_prompt, user_message = eng._build_prompts()
+ assert "OpenAPI" in system_prompt
def test_prompt_includes_har_path(self, tmp_path):
- """Prompt includes HAR file path."""
+ """User message includes HAR file path."""
eng = self._make_engineer(tmp_path)
- prompt = eng._build_analysis_prompt()
- assert str(eng.har_path) in prompt
+ system_prompt, user_message = eng._build_prompts()
+ assert str(eng.har_path) in user_message
def test_prompt_includes_user_prompt(self, tmp_path):
- """Prompt includes user's original prompt."""
+ """User message includes user's original prompt."""
eng = self._make_engineer(tmp_path, prompt="capture spotify api")
- prompt = eng._build_analysis_prompt()
- assert "capture spotify api" in prompt
+ system_prompt, user_message = eng._build_prompts()
+ assert "capture spotify api" in user_message
def test_prompt_includes_additional_instructions(self, tmp_path):
- """Additional instructions are appended."""
+ """Additional instructions are in user message."""
eng = self._make_engineer(tmp_path, additional_instructions="Focus on auth")
- prompt = eng._build_analysis_prompt()
- assert "Focus on auth" in prompt
+ system_prompt, user_message = eng._build_prompts()
+ assert "Focus on auth" in user_message
def test_prompt_includes_tag_context(self, tmp_path):
- """Prompt includes tag-based workflow context."""
+ """User message includes tag-based workflow context."""
eng = self._make_engineer(tmp_path)
- prompt = eng._build_analysis_prompt()
- assert "Tag-Based Workflows" in prompt
- assert eng.run_id in prompt
+ system_prompt, user_message = eng._build_prompts()
+ assert "Tag-Based Workflows" in user_message
+ assert eng.run_id in user_message
def test_prompt_includes_existing_client_guidance(self, tmp_path):
- """Prompt tells the agent to keep editing the existing client language."""
+ """User message tells the agent to keep editing the existing client language."""
har_path = tmp_path / "test.har"
har_path.touch()
scripts_dir = tmp_path / "scripts"
@@ -323,10 +323,10 @@ class TestBaseEngineerBuildPrompt:
output_dir=str(tmp_path),
)
- prompt = eng._build_analysis_prompt()
- assert str(client_path) in prompt
- assert "iterative edit" in prompt
- assert "JavaScript" in prompt
+ system_prompt, user_message = eng._build_prompts()
+ assert str(client_path) in user_message
+ assert "iterative edit" in user_message
+ assert "JavaScript" in user_message
class TestBaseEngineerSync:
diff --git a/tests/test_collector.py b/tests/test_collector.py
index cca5d93..0eb95e8 100644
--- a/tests/test_collector.py
+++ b/tests/test_collector.py
@@ -43,8 +43,8 @@ class TestCollectorInit:
class TestCollectorBuildPrompt:
"""Test prompt building."""
- def test_build_collector_prompt(self):
- """Build collector prompt includes mission."""
+ def test_build_prompts(self):
+ """Build collector prompts includes mission in user message."""
with patch("reverse_api.collector.MessageStore"):
with patch("reverse_api.collector.CollectorUI"):
collector = Collector(
@@ -54,10 +54,11 @@ class TestCollectorBuildPrompt:
)
collector._collected_dir = Path("/tmp/test")
collector.items_path = Path("/tmp/test/items.jsonl")
- prompt = collector._build_collector_prompt()
- assert "Y Combinator startups" in prompt
- assert "items.jsonl" in prompt
- assert "JSONL" in prompt
+ system_prompt, user_message = collector._build_prompts()
+ assert "Y Combinator startups" in user_message
+ assert "items.jsonl" in user_message
+ assert "JSONL" in user_message
+ assert "web data collection agent" in system_prompt
class TestCollectorRun:
@@ -154,6 +155,8 @@ class TestCollectorAgentLoop:
model="claude-sonnet-4-6",
)
collector._collected_dir = tmp_path
+ collector._system_prompt = "system"
+ collector._user_message = "user"
with patch("reverse_api.collector.ClaudeSDKClient") as mock_sdk:
mock_sdk.return_value.__aenter__ = AsyncMock(side_effect=Exception("SDK error"))
@@ -178,6 +181,8 @@ class TestCollectorAgentLoop:
)
collector._collected_dir = tmp_path
collector.items_path = tmp_path / "items.jsonl"
+ collector._system_prompt = "system"
+ collector._user_message = "user"
from claude_agent_sdk import ResultMessage
mock_result = MagicMock(spec=ResultMessage)
@@ -215,6 +220,8 @@ class TestCollectorAgentLoop:
)
collector._collected_dir = tmp_path
collector.items_path = tmp_path / "items.jsonl"
+ collector._system_prompt = "system"
+ collector._user_message = "user"
from claude_agent_sdk import ResultMessage
mock_result = MagicMock(spec=ResultMessage)
@@ -251,6 +258,8 @@ class TestCollectorAgentLoop:
)
collector._collected_dir = tmp_path
collector.items_path = tmp_path / "items.jsonl"
+ collector._system_prompt = "system"
+ collector._user_message = "user"
from claude_agent_sdk import (
AssistantMessage,
@@ -314,6 +323,8 @@ class TestCollectorAgentLoop:
)
collector._collected_dir = tmp_path
collector.items_path = tmp_path / "items.jsonl"
+ collector._system_prompt = "system"
+ collector._user_message = "user"
from claude_agent_sdk import AssistantMessage, ResultMessage, ToolUseBlock
@@ -363,6 +374,8 @@ class TestCollectorAgentLoop:
)
collector._collected_dir = tmp_path
collector.items_path = tmp_path / "items.jsonl"
+ collector._system_prompt = "system"
+ collector._user_message = "user"
from claude_agent_sdk import AssistantMessage, ResultMessage
@@ -411,6 +424,8 @@ class TestCollectorAgentLoop:
)
collector._collected_dir = tmp_path
collector.items_path = tmp_path / "items.jsonl"
+ collector._system_prompt = "system"
+ collector._user_message = "user"
mock_client = AsyncMock()
mock_client.query = AsyncMock()
diff --git a/tests/test_prompts.py b/tests/test_prompts.py
new file mode 100644
index 0000000..42dcb63
--- /dev/null
+++ b/tests/test_prompts.py
@@ -0,0 +1,159 @@
+"""Tests for the prompts template loader."""
+
+import pytest
+
+from reverse_api.prompts import FOLDER_NAME_PROMPT, load, load_language_partial
+
+
+class TestLoad:
+ """Test the load() template function."""
+
+ def test_load_collector_system(self):
+ text = load("collector/system")
+ assert "web data collection agent" in text
+ assert "JSON object" in text
+
+ def test_load_collector_user_with_placeholders(self):
+ text = load(
+ "collector/user",
+ prompt="collect Y Combinator startups",
+ items_path="/tmp/items.jsonl",
+ )
+ assert "Y Combinator startups" in text
+ assert "/tmp/items.jsonl" in text
+
+ def test_load_chat_system(self):
+ text = load(
+ "chat/system",
+ har_path="/tmp/recording.har",
+ scripts_dir="/tmp/scripts",
+ )
+ assert "reverse engineering APIs" in text
+ assert "/tmp/recording.har" in text
+ assert "/tmp/scripts" in text
+
+ def test_load_nonexistent_raises(self):
+ with pytest.raises(FileNotFoundError):
+ load("nonexistent_template")
+
+
+class TestLoadLanguagePartial:
+ """Test language-specific partials."""
+
+ def test_python_partial(self):
+ text = load_language_partial(
+ "python",
+ scripts_dir="/tmp/scripts",
+ client_filename="api_client.py",
+ run_command="python api_client.py",
+ )
+ assert "Python script" in text
+ assert "requests" in text
+ assert "/tmp/scripts/api_client.py" in text
+
+ def test_javascript_partial(self):
+ text = load_language_partial(
+ "javascript",
+ scripts_dir="/tmp/scripts",
+ client_filename="api_client.js",
+ run_command="node api_client.js",
+ )
+ assert "JavaScript module" in text
+ assert "fetch" in text
+
+ def test_typescript_partial(self):
+ text = load_language_partial(
+ "typescript",
+ scripts_dir="/tmp/scripts",
+ client_filename="api_client.ts",
+ run_command="npx tsx api_client.ts",
+ )
+ assert "TypeScript module" in text
+ assert "interfaces" in text
+
+
+class TestEngineerTemplates:
+ """Test engineer system/user templates."""
+
+ def test_engineer_system_loads(self):
+ text = load(
+ "engineer/system",
+ mode_description="reverse engineer API calls",
+ task_description="Python API client",
+ codegen_instructions="Generate Python code.",
+ scratchpad_extra="",
+ attempt_log_section="",
+ after_verb="testing",
+ quality_check="Whether the implementation works",
+ output_type="code",
+ )
+ assert "HAR" in text
+ assert "AskUserQuestion" in text
+ assert "scratchpad" in text
+
+ def test_engineer_user_loads(self):
+ text = load(
+ "engineer/user",
+ har_path="/tmp/test.har",
+ prompt="capture api calls",
+ scripts_dir="/tmp/scripts",
+ existing_client_guidance="",
+ additional_instructions="",
+ tag_extra="",
+ tag_mode_label="Re-engineer",
+ run_id="test123",
+ har_parent="/tmp",
+ existing_label="scripts",
+ messages_path="/tmp/messages",
+ is_fresh="false",
+ existing_artifact="script",
+ )
+ assert "/tmp/test.har" in text
+ assert "capture api calls" in text
+ assert "test123" in text
+
+
+class TestAutoTemplates:
+ """Test auto mode templates."""
+
+ def test_auto_system_loads(self):
+ text = load(
+ "auto/system",
+ browser_tool_label="MCP",
+ language_name="Python",
+ codegen_instructions="Generate Python code.",
+ output_files="1. api_client.py",
+ )
+ assert "autonomous AI agent" in text
+ assert "Python" in text
+
+ def test_auto_user_playwright_loads(self):
+ text = load(
+ "auto/user_playwright",
+ prompt="browse example.com",
+ scripts_dir="/tmp/scripts",
+ har_path="/tmp/recording.har",
+ )
+ assert "browse example.com" in text
+ assert "browser_navigate" in text
+ assert "browser_close" in text
+
+ def test_auto_user_chrome_mcp_loads(self):
+ text = load(
+ "auto/user_chrome_mcp",
+ prompt="browse example.com",
+ scripts_dir="/tmp/scripts",
+ )
+ assert "browse example.com" in text
+ assert "navigate_page" in text
+ assert "There is no HAR file" in text
+ assert "REAL Chrome browser" in text
+
+
+class TestFolderNamePrompt:
+ """Test folder name prompt constant."""
+
+ def test_format(self):
+ result = FOLDER_NAME_PROMPT.format(prompt="scrape apple jobs")
+ assert "scrape apple jobs" in result
+ assert "folder name" in result
diff --git a/uv.lock b/uv.lock
index 6c20d16..59741df 100644
--- a/uv.lock
+++ b/uv.lock
@@ -2082,7 +2082,7 @@ wheels = [
[[package]]
name = "reverse-api-engineer"
-version = "0.6.0"
+version = "0.7.1"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },