### Example Skill File Structure

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/agent/skills.mdx

This is an example of a skill file, including the required frontmatter metadata and content.

```markdown
---
name: kotlin-test-writer
title: Kotlin Test Writer
description: Write focused unit tests for Kotlin services and tools.
---

# Kotlin Test Writer

When writing tests:
- Prefer existing `IntegrationTest` patterns in this repo.
- Cover behavior + edge cases.
- Keep assertions explicit and deterministic.

```

--------------------------------

### Provider Headers Example

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/enterprise/remote-settings.mdx

Configure HTTP headers for provider connections. Use the `$CUSTOM_SERVICE_API_KEY` placeholder for the user's API key.

```json
{ "Authorization": "Bearer $CUSTOM_SERVICE_API_KEY", ... }
```

--------------------------------

### Example Permission Configuration

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/configuration/permissions.mdx

This JSON object demonstrates how to configure 'allow' and 'deny' rules for Bash commands and Read operations. Use 'allow' for permitted actions and 'deny' for blocked actions.

```json
{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)",
      "Bash(git * main)",
      "Bash(* --version)",
      "Read(./src/**)"
    ],
    "deny": [
      "Bash(git push *)",
      "Read(./.env)"
    ]
  }
}
```

--------------------------------

### Initial Render and Setup

Source: https://github.com/carlrobertoh/proxyai/blob/master/src/main/resources/templates/mermaid-response-panel.html

Disables controls, renders the diagram, and then re-enables controls upon completion or error. Requires `setControlsEnabled`, `renderDiagram`, and `fitToViewport` to be defined.

```javascript
setControlsEnabled(false);
renderDiagram();
```

--------------------------------

### Custom OpenAI Request Body Example

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/providers/cloud/custom.mdx

This JSON structure demonstrates how placeholders like $PROMPT, $OPENAI_MESSAGES, and $CUSTOM_SERVICE_API_KEY are used within a nested request body for custom OpenAI configurations. It shows recursive replacement within objects and arrays.

```json
{
  "model": "my-model",
  "payload": {
    "prompt_alias": "$PROMPT",
    "messages_alias": "$OPENAI_MESSAGES",
    "auth": "Bearer $CUSTOM_SERVICE_API_KEY",
    "items": [
      {
        "kind": "prompt",
        "value": "$PROMPT"
      },
      {
        "kind": "messages",
        "value": "$OPENAI_MESSAGES"
      }
    ]
  }
}
```

--------------------------------

### PreToolUse Event Input Payload Example

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/agent/hooks.mdx

This JSON object represents the input payload for the 'beforeToolUse' hook event. It includes details about the tool being used, its input parameters, a unique tool use ID, the current working directory, and the event name.

```json
{
  "tool_name": "Bash",
  "tool_input": { "command": "pnpm install", "working_directory": "/project" },
  "tool_use_id": "abc123",
  "cwd": "/project",
  "hook_event_name": "beforeToolUse"
}
```

--------------------------------

### Provider Chat Completion Body Example

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/enterprise/remote-settings.mdx

Define the JSON body structure for chat completion API requests. Placeholders like `$OPENAI_MESSAGES` can be used for dynamic content.

```json
{ "model": "...", "messages": "$OPENAI_MESSAGES", ... }
```

--------------------------------

### Import Nextra Steps Component

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/providers/cloud/inception.mdx

This import statement is required to use the Steps component for guiding users through a multi-step process.

```javascript
import { Steps } from 'nextra/components'
```

--------------------------------

### Configure Multiple Hooks

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/agent/hooks.mdx

This JSON configuration demonstrates setting up multiple hooks for different events, including preToolUse, subagentStart, and beforeShellExecution, each with specific commands and matchers.

```json
{
  "ignore": [],
  "permissions": { "allow": [] },
  "hooks": {
    "preToolUse": [
      {
        "command": ".proxyai/hooks/validate-shell.sh",
        "matcher": "Shell"
      }
    ],
    "subagentStart": [
      {
        "command": ".proxyai/hooks/validate-explore.sh",
        "matcher": "explore|shell"
      }
    ],
    "beforeShellExecution": [
      {
        "command": ".proxyai/hooks/approve-network.sh",
        "matcher": "curl|wget|nc "
      }
    ]
  }
}
```

--------------------------------

### Initialize Diagram Variables and DOM References

Source: https://github.com/carlrobertoh/proxyai/blob/master/src/main/resources/templates/mermaid-response-panel.html

Sets up initial variables and references to DOM elements for diagram rendering and interaction. Includes constants for timeouts and zoom limits.

```javascript
const source = __MERMAID_SOURCE__; const diagramTypeLabel = __DIAGRAM_TYPE_LABEL_; const nodeTargets = __NODE_TARGETS_JSON_; const viewport = document.getElementById('viewport'); const diagramTypeBadge = document.getElementById('diagramTypeBadge'); const diagram = document.getElementById('diagram'); const error = document.getElementById('error'); const status = document.getElementById('status'); const statusMessage = document.getElementById('statusMessage'); const statusSpinner = document.getElementById('statusSpinner'); const retryRender = document.getElementById('retryRender'); const zoomIn = document.getElementById('zoomIn'); const zoomOut = document.getElementById('zoomOut'); const zoomReset = document.getElementById('zoomReset'); const zoomValue = document.getElementById('zoomValue'); const MERMAID_SCRIPT_URL = __MERMAID_SCRIPT_URL_; const MERMAID_LOAD_TIMEOUT_MS = 8000; const RENDER_TIMEOUT_MS = 12000; let zoom = 1; let panX = 0; let panY = 0; let currentSvg = null; let baseWidth = 1; let baseHeight = 1; let dragging = false; let dragStartX = 0; let dragStartY = 0; let dragStartPanX = 0; let dragStartPanY = 0; let dragMoved = false; let suppressClick = false; const DRAG_THRESHOLD = 6; const MIN_ZOOM = 0.15; const MAX_ZOOM = 4.5;
```

--------------------------------

### ProxyAI Mistral Configuration Steps

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/providers/cloud/mistral.mdx

Follow these steps to configure ProxyAI with your Mistral API key. Ensure you have an account and an API key from Mistral Console.

```markdown
import { Steps } from 'nextra/components'

<Steps>
  ### Create Your Account

  If you don’t already have one, create an account at the [Mistral Console](https://console.mistral.ai/).

  ### Get Your API Key

  From the Mistral Console, create an API key and copy it to your clipboard.

  ### Apply Your API Key

  Configure the ProxyAI plugin to use Mistral:

  - Go to **File > Settings/Preferences > Tools > ProxyAI > Providers > Mistral**.
  - Paste your API key into the designated field.
  - Click `Apply` or `OK` to save your changes.
  <br/>

  ### Choose a Model

  - For general chat: select a Mistral chat model (e.g., `mistral-large-latest`).
  - For code tasks and autocomplete: select `codestral`.
</Steps>
```

--------------------------------

### Task

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/agent/tools.mdx

Launches a subagent with specified parameters.

```APIDOC
## Task

### Description
Launches a subagent.

### Input

#### Request Body
- **description** (string) - Required - Short label.
- **prompt** (string) - Required - Full instruction for the subagent.
- **subagent_type** (string) - Required - Built-in type or custom subagent title.
- **model** (string | null) - Optional - Optional model override.
- **project_path** (string | null) - Optional - Optional working directory override.

### Output

#### Response Body
- **agentType** (string) - The subagent type used.
- **description** (string) - Echoes description.
- **prompt** (string) - Echoes prompt.
- **output** (string) - Subagent output text.
- **executionTime** (number) - Duration in ms.
- **totalTokens** (number) - Token usage (when available).
```

--------------------------------

### Run ProxyAI Locally on Windows ARM64

Source: https://github.com/carlrobertoh/proxyai/blob/master/README.md

Execute this command to run the IDE locally on Windows ARM64 systems. Ensure you are in the project directory.

```shell
./gradlew runIde -Penv=win-arm64
```

--------------------------------

### Clone and Run ProxyAI Locally on Linux/macOS

Source: https://github.com/carlrobertoh/proxyai/blob/master/README.md

Use these commands to clone the repository, update submodules, and run the IDE locally on Linux or macOS systems.

```shell
git clone https://github.com/carlrobertoh/ProxyAI.git
cd ProxyAI
git submodule update
./gradlew runIde
```

--------------------------------

### C/C++ Navigation Links

Source: https://github.com/carlrobertoh/proxyai/blob/master/src/main/resources/prompts/persona/psi-navigation-guidelines.txt

Employ the file:// protocol for linking functions, constants, and variables in C/C++ source files. Specify the file path and symbol name.

```cpp
Call [logError](file://src/utils/logger.cpp#logError) function.
The [MAX_SIZE](file://include/constants.h#MAX_SIZE) constant is defined.
Implement [processData](file://src/processor.h#processData) in header.
```

--------------------------------

### GetLibraryDocs - Fetch Library Documentation

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/agent/tools.mdx

Fetches documentation for a specific library ID from Context7.

```APIDOC
## GetLibraryDocs - Fetch Library Documentation

### Description
Fetches docs from Context7 for a specific library ID.

### Method
POST

### Endpoint
/carlrobertoh/proxyai/get_library_docs

### Parameters
#### Request Body
- **context7CompatibleLibraryID** (string) - Required - `/org/project[/version]`.
- **mode** (string) - Optional - `code` (default) or `info`.
- **topic** (string | null) - Optional - Topic filter.
- **page** (number) - Optional - Page number (1-10).

### Response
#### Success Response (200)
- **libraryId** (string) - Echoes the library id.
- **documentation** (string) - Plain text docs (truncated).
- **docMode** (string) - `code` or `info`.
- **page** (number) - Page number returned.

#### Response Example (Success)
```json
{
  "libraryId": "nextjs/nextjs",
  "documentation": "This is the documentation for Next.js...",
  "docMode": "code",
  "page": 1
}
```

#### Error Response (400)
- **error** (string) - Error message.

#### Response Example (Error)
```json
{
  "error": "Invalid library ID."
}
```
```

--------------------------------

### File Navigation Links

Source: https://github.com/carlrobertoh/proxyai/blob/master/src/main/resources/prompts/persona/psi-navigation-guidelines.txt

Use the file:// protocol to link directly to files. This is useful for referencing entire source or header files.

```plaintext
Edit the [main.cpp](file://src/main.cpp) file.
Check [UserService.java](file://src/service/UserService.java).
```

--------------------------------

### Configure beforeShellExecution Hook with Matcher

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/agent/hooks.mdx

This JSON configuration sets up a hook to run before shell execution, specifically for commands matching the provided regex pattern.

```json
{
  "hooks": {
    "beforeShellExecution": [
      {
        "command": ".proxyai/hooks/approve-network.sh",
        "timeout": 30,
        "matcher": "curl|wget|nc"
      }
    ]
  }
}
```

--------------------------------

### Python Navigation Links

Source: https://github.com/carlrobertoh/proxyai/blob/master/src/main/resources/prompts/persona/psi-navigation-guidelines.txt

Utilize the file:// protocol for linking functions and settings in Python files. Specify the file path and the symbol name.

```python
Use [parse_json](file://utils/parser.py#parse_json) function.
The [DATABASE_URL](file://settings.py#DATABASE_URL) setting.
```

--------------------------------

### JavaScript Navigation Links

Source: https://github.com/carlrobertoh/proxyai/blob/master/src/main/resources/prompts/persona/psi-navigation-guidelines.txt

Use the file:// protocol for linking event handlers and exported constants/variables in JavaScript files. Include the file path and symbol name.

```javascript
The [handleClick](file://src/components/Button.js#handleClick) event handler.
Export [API_BASE_URL](file://src/config.js#API_BASE_URL) from config.
```

--------------------------------

### TodoWrite

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/agent/tools.mdx

Creates or updates a todo list rendered in the UI.

```APIDOC
## TodoWrite

### Description
Creates/updates a todo list rendered in the UI.

### Input

#### Request Body
- **title** (string) - Required - Short title (max 4 words).
- **todos** (array) - Required - Todo items: `content`, `status`, `activeForm`.

### Output

Returns a formatted string summary (used to render the UI todo widget).
```

--------------------------------

### Java/Kotlin Navigation Links

Source: https://github.com/carlrobertoh/proxyai/blob/master/src/main/resources/prompts/persona/psi-navigation-guidelines.txt

Use psi_element:// protocol for linking classes, methods, fields, and constants in Java/Kotlin files. Ensure fully qualified class names are used.

```java
The [System](psi_element://java.lang.System) class has [out](psi_element://java.lang.System#out) field.
Use [UserRepository](psi_element://com.example.repository.UserRepository) with [findById](psi_element://com.example.repository.UserRepository#findById).
The [name](psi_element://com.example.model.User#name) field in [User](psi_element://com.example.model.User) class.
```

--------------------------------

### Run Ollama Model Locally

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/providers/local/ollama.mdx

Use this command in your terminal to download and run an Ollama model. Ensure the model is downloaded before integrating with other tools.

```bash
ollama run codellama
```

--------------------------------

### Tail ProxyAI Build Logs

Source: https://github.com/carlrobertoh/proxyai/blob/master/README.md

Monitor the ProxyAI build logs in real-time using the tail -f command. This is useful for debugging.

```shell
tail -f build/idea-sandbox/IU-2026.1/log/idea.log
```

--------------------------------

### subagentStart Hook Output

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/agent/hooks.mdx

Optional output for the subagentStart hook, allowing decisions to allow or deny subagent creation.

```json
{
  "decision": "allow",
  "reason": "Reason if denied"
}
```

--------------------------------

### LoadSkill

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/agent/tools.mdx

Loads a configured skill and injects it back into the run as a new user message. Skills are discovered from `.proxyai/skills/**/SKILL.md`. Requires an 'ask/approve' flow.

```APIDOC
## LoadSkill

### Description
Loads a configured skill and injects it back into the run as a new user message. Skills are discovered from `.proxyai/skills/**/SKILL.md`.

**Approval required** (generic ask/approve flow).

### Input

#### Request Body
- **skill_name** (string) - Required - Exact skill title from the available skills list in the system prompt.

### Output (success)

#### Response Body
- **title** (string) - Loaded skill title.
- **description** (string) - Loaded skill description.
- **queued** (boolean) - Whether the user-message injection was queued.

### Output (error)

#### Response Body
- **message** (string) - Error message with available skills when possible.
```

--------------------------------

### Write Tool

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/agent/tools.mdx

Creates a new file or overwrites an existing file with specified content. Requires user approval.

```APIDOC
## Write Tool

### Description
Creates a file or overwrites an existing file.

### Approval Required
Yes

### Method
Not applicable (Tool definition)

### Endpoint
Not applicable (Tool definition)

### Parameters
#### Input Parameters
- **file_path** (string) - Required - Absolute path to the file.
- **content** (string) - Required - Full file contents.

### Response
#### Success Response
- **filePath** (string) - Written file path.
- **bytesWritten** (number) - UTF-8 byte count.
- **isNewFile** (boolean) - Whether the file was created.
- **message** (string) - Human-readable message.

#### Error Response
- **filePath** (string) - Requested file path.
- **error** (string) - Error message.

### Response Example (Success)
{
  "filePath": "/path/to/new_file.txt",
  "bytesWritten": 123,
  "isNewFile": true,
  "message": "File created successfully."
}

### Response Example (Error)
{
  "filePath": "/path/to/new_file.txt",
  "error": "Permission denied."
}
```

--------------------------------

### Zoom and Pan Event Handlers

Source: https://github.com/carlrobertoh/proxyai/blob/master/src/main/resources/templates/mermaid-response-panel.html

Handles mouse wheel events for zooming and mouse down/move/up events for panning the diagram. Requires `viewport`, `setZoomAt`, `applyTransform`, `panX`, `panY`, `dragStartX`, `dragStartY`, `dragStartPanX`, `dragStartPanY`, `dragging`, `dragMoved`, `suppressClick`, and `DRAG_THRESHOLD` to be defined.

```javascript
const rect = viewport.getBoundingClientRect();
const anchorX = e.clientX - rect.left;
const anchorY = e.clientY - rect.top;
const factor = Math.exp(-e.deltaY * 0.0015);
setZoomAt(zoom * factor, anchorX, anchorY);
```

```javascript
zoomIn.addEventListener('click', () => {
  setZoomAt(zoom * 1.15, viewport.clientWidth / 2, viewport.clientHeight / 2);
});
```

```javascript
zoomOut.addEventListener('click', () => {
  setZoomAt(zoom / 1.15, viewport.clientWidth / 2, viewport.clientHeight / 2);
});
```

```javascript
zoomReset.addEventListener('click', () => {
  fitToViewport();
});
```

```javascript
retryRender.addEventListener('click', () => {
  renderDiagram();
});
```

```javascript
viewport.addEventListener('mousedown', (e) => {
  if (!currentSvg) return;
  if (e.button !== 0) return;
  dragging = true;
  dragMoved = false;
  suppressClick = false;
  viewport.classList.add('dragging');
  dragStartX = e.pageX;
  dragStartY = e.pageY;
  dragStartPanX = panX;
  dragStartPanY = panY;
});
```

```javascript
window.addEventListener('mousemove', (e) => {
  if (!dragging) return;
  const dx = e.pageX - dragStartX;
  const dy = e.pageY - dragStartY;
  if (!dragMoved && Math.abs(dx) < DRAG_THRESHOLD && Math.abs(dy) < DRAG_THRESHOLD) {
    return;
  }
  dragMoved = true;
  e.preventDefault();
  panX = dragStartPanX + dx;
  panY = dragStartPanY + dy;
  applyTransform();
});
```

```javascript
window.addEventListener('mouseup', () => {
  if (dragMoved) {
    suppressClick = true;
  }
  dragging = false;
  dragMoved = false;
  viewport.classList.remove('dragging');
});
```

```javascript
viewport.addEventListener('click', (e) => {
  if (!suppressClick) return;
  e.preventDefault();
  e.stopPropagation();
  suppressClick = false;
}, true);
```

--------------------------------

### subagentStart Hook Input

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/agent/hooks.mdx

Input for the subagentStart hook, used to control the spawning of subagents.

```json
{
  "subagent_type": "generalPurpose",
  "description": "Explore auth flow",
  "prompt": "Explore the authentication flow",
  "hook_event_name": "subagentStart"
}
```

--------------------------------

### Read Tool

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/agent/tools.mdx

Reads a file from disk and returns its content, optionally with line offsets and limits.

```APIDOC
## Read Tool

### Description
Reads a file from disk and returns it in numbered `cat -n` format.

### Method
Not applicable (Tool definition)

### Endpoint
Not applicable (Tool definition)

### Parameters
#### Input Parameters
- **file_path** (string) - Required - Must be an absolute path.
- **offset** (number) - Optional - 1-indexed line offset.
- **limit** (number) - Optional - Number of lines to read.

### Response
#### Success Response
- **filePath** (string) - Echoes the path requested.
- **content** (string) - Numbered content (lines truncated to 2000 chars each).
- **lineCount** (number) - Lines returned (not total lines).
- **truncated** (boolean) - True when the file/selection exceeds the read limit.
- **fileType** (string | null) - IntelliJ file type name.
- **startLine** (number | null) - First line returned (when offset is used).
- **endLine** (number | null) - Last line returned (when limit truncates).

### Response Example
{
  "filePath": "/path/to/file.txt",
  "content": "1  Line one\n2  Line two",
  "lineCount": 2,
  "truncated": false,
  "fileType": "PLAIN_TEXT",
  "startLine": 1,
  "endLine": 2
}
```

--------------------------------

### Basic Ignore Rule Configuration

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/configuration/ignore-rules.mdx

Defines a list of file and folder patterns to be ignored by AI-facing features. Use this to exclude sensitive files or large directories.

```json
{
  "ignore": [
    ".env",
    ".env.*",
    ".git/",
    "node_modules/",
    "build/",
    "dist/",
    "*.pem",
    "secrets/**",
    "app/src/main/"
  ]
}
```

--------------------------------

### ProxyAI Configuration for Network Command Hook

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/agent/hooks.mdx

This JSON configuration snippet defines a hook named 'network-deny.sh' that triggers on 'beforeShellExecution' events. It uses a matcher to specifically target commands like curl, wget, and nc, ensuring the associated script is executed for these commands.

```json
{
  "hooks": {
    "beforeShellExecution": [
      {
        "command": ".proxyai/hooks/network-deny.sh",
        "matcher": "curl|wget|nc"
      }
    ]
  }
}
```

--------------------------------

### ProxyAI Configuration for Generic Command Blocking Hook

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/agent/hooks.mdx

This JSON configuration sets up a hook to block specific high-risk shell commands. The 'block-command.sh' script is executed before any shell command matching the 'matcher' pattern, effectively denying execution and providing a reason.

```json
{
  "hooks": {
    "beforeShellExecution": [
      {
        "command": ".proxyai/hooks/block-command.sh",
        "matcher": "rm -rf|terraform apply|docker system prune"
      }
    ]
  }
}
```

--------------------------------

### Configure afterToolUse Hook

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/agent/hooks.mdx

This JSON configuration sets up a hook to run after any tool use. It specifies the command to execute and a timeout.

```json
{
  "ignore": [],
  "permissions": { "allow": [] },
  "hooks": {
    "afterToolUse": [
      {
        "command": ".proxyai/hooks/tool-audit.sh",
        "timeout": 10
      }
    ]
  }
}
```

--------------------------------

### subagentStart Hook

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/agent/hooks.mdx

This hook is called before a subagent is spawned. It can be used to allow or deny the creation of the subagent.

```APIDOC
## subagentStart Hook

### Description
Called before spawning a subagent (Task tool). Can allow or deny subagent creation.

### Input Parameters

| Field | Type | Description |
| --- | --- | --- |
| `subagent_type` | string | Type of subagent: "generalPurpose", "explore", "shell", etc. |
| `description` | string | Short description of the subagent task |
| `prompt` | string | Full prompt given to the subagent |
| `hook_event_name` | string | The hook event name ("subagentStart") |

### Output (optional)

```json
{
  "decision": "allow",
  "reason": "Reason if denied"
}
```

### Output Parameters

| Field | Type | Description |
| --- | --- | --- |
| `decision` | string | "deny" to block, "allow" to proceed |
| `reason` | string (optional) | Explanation shown if denied |
```

--------------------------------

### No Context Navigation Links

Source: https://github.com/carlrobertoh/proxyai/blob/master/src/main/resources/prompts/persona/psi-navigation-guidelines.txt

Use backticks for symbols when no file context or reference is possible. This is for general programming concepts or symbols without a clear location.

```plaintext
Use the `printf` function for formatting.
The `malloc` function allocates memory.
Consider using `async/await` pattern.
```

--------------------------------

### WebFetch - Fetch URL Content

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/agent/tools.mdx

Fetches content from a specific URL and converts it to Markdown. Supports CSS selectors and timeouts.

```APIDOC
## WebFetch - Fetch URL Content

### Description
Fetches a specific URL and converts HTML content to Markdown.

### Method
POST

### Endpoint
/carlrobertoh/proxyai/web_fetch

### Parameters
#### Request Body
- **url** (string) - Required - Full `http://` or `https://` URL.
- **selector** (string | null) - Optional - CSS selector to scope extraction (e.g., `main`, `article`).
- **timeout_ms** (number) - Optional - Request timeout in milliseconds (default `10000`).

### Response
#### Success Response (200)
- **url** (string) - Source URL requested.
- **final_url** (string | null) - Final URL after redirects.
- **title** (string | null) - Page title, when available.
- **markdown** (string) - Converted Markdown content.
- **content_type** (string | null) - Response content type.
- **status_code** (number | null) - HTTP status code.
- **used_selector** (string | null) - Echoes selector if provided.
- **error** (string | null) - Error message on failure.

#### Response Example
```json
{
  "url": "https://example.com",
  "final_url": "https://example.com",
  "title": "Example Domain",
  "markdown": "# Example Domain\n\nThis domain is used for illustrative examples.",
  "content_type": "text/html",
  "status_code": 200,
  "used_selector": null,
  "error": null
}
```
```

--------------------------------

### Prompts Configuration Structure

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/enterprise/remote-settings.mdx

Use this JSON structure to override default prompts or add custom chat actions and personas. Placeholders like {SELECTION} can be used within prompt strings.

```json
// Structure example for prompts
{
  "prompts": {
    "coreActions": {
      "generateCommitMessages": "Branch: {BRANCH_NAME}..."
    },
    "chatActions": [
      {
        "name": "Explain Selection",
        "instructions": "Explain: {SELECTION}"
      }
    ],
    "personas": [
      {
        "name": "Code Reviewer",
        "instructions": "Review the code..."
      }
    ]
  }
}
```

--------------------------------

### beforeShellExecution Hook Input

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/agent/hooks.mdx

Input for the beforeShellExecution hook, containing details about the command to be executed.

```json
{
  "command": "pnpm lint",
  "cwd": "/project",
  "timeout": 30,
  "hook_event_name": "beforeShellExecution"
}
```

--------------------------------

### AskUserQuestion

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/agent/tools.mdx

Asks the user a structured question in the UI. Supports a maximum of 1-4 questions.

```APIDOC
## AskUserQuestion

### Description
Asks the user a structured question in the UI.

### Input

#### Request Body
- **questions** (array) - Required - Max 1-4 questions. Each question includes `header`, `question`, `options`, and `multiSelect`.
- **answers** (object | null) - Optional - Prefill answers (rare).

### Output (success)

#### Response Body
- **answers** (object) - Map of header -> selected value(s).

### Output (error)

#### Response Body
- **message** (string) - Error message.
```

--------------------------------

### Edit Tool

Source: https://github.com/carlrobertoh/proxyai/blob/master/docs/pages/agent/tools.mdx

Performs exact string replacement within a specified file. Requires user approval.

```APIDOC
## Edit Tool

### Description
Exact string replacement in a file.

### Approval Required
Yes

### Method
Not applicable (Tool definition)

### Endpoint
Not applicable (Tool definition)

### Parameters
#### Input Parameters
- **file_path** (string) - Required - Must be an absolute path.
- **old_string** (string) - Required - Must match exactly (including whitespace).
- **new_string** (string) - Required - Replacement text; can be empty.
- **short_description** (string) - Required - Shown in UI/logs.
- **replace_all** (boolean) - Optional - Defaults to false.

### Response
#### Success Response
- **filePath** (string) - Edited file path.
- **replacementsMade** (number) - Count of replacements.
- **message** (string) - Human-readable message.
- **oldStringPreview** (string | null) - Preview (up to ~200 chars).
- **newStringPreview** (string | null) - Preview (up to ~200 chars).
- **editLocations** (array) - Line/column + small context for each replacement.

#### Error Response
- **filePath** (string) - Requested file path.
- **error** (string) - Error message.

### Response Example (Success)
{
  "filePath": "/path/to/file.txt",
  "replacementsMade": 1,
  "message": "Successfully replaced string.",
  "oldStringPreview": "old value",
  "newStringPreview": "new value",
  "editLocations": [
    {
      "filePath": "/path/to/file.txt",
      "line": 5,
      "column": 10,
      "oldString": "old value",
      "newString": "new value"
    }
  ]
}

### Response Example (Error)
{
  "filePath": "/path/to/file.txt",
  "error": "String not found."
}
```