### Clone and install dependencies

Source: https://www.faster-fixes.com/docs/self-hosting

Initial commands to clone the repository and install required packages.

```bash
git clone https://github.com/manucoffin/faster-fixes.git
cd faster-fixes
pnpm install
```

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

### Install Faster Fixes Core

Source: https://www.faster-fixes.com/docs/widget/other-frameworks

Install the core package using your preferred package manager.

```bash
npm install @fasterfixes/core
```

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

### Install Faster Fixes React package

Source: https://www.faster-fixes.com/docs/getting-started/quickstart

Install the required dependency using npm.

```bash
npm install @fasterfixes/react
```

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

### Submit feedback response

Source: https://www.faster-fixes.com/docs/api-reference/feedback-api

Example JSON response returned after successfully submitting feedback.

```json
{
  "id": "uuid",
  "status": "new",
  "comment": "The button color should be blue",
  "pageUrl": "https://myapp.com/dashboard",
  "selector": "[data-testid=\"save-btn\"]",
  "clickX": 450,
  "clickY": 320,
  "screenshotUrl": "https://...",
  "metadata": {},
  "reviewer": { "id": "uuid", "name": "Sarah" },
  "createdAt": "2025-01-15T10:30:00Z"
}
```

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

### Install fix-feedback skill

Source: https://www.faster-fixes.com/docs/mcp/skill

Use this command to add the fix-feedback skill to your AI agent via npx.

```bash
npx skills add manucoffin/faster-fixes --skill fix-feedback
```

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

### GET /feedback

Source: https://www.faster-fixes.com/docs/api-reference/feedback-api

Retrieve a list of all feedback items for the project, with optional filtering by URL.

```APIDOC
## GET /feedback

### Description
Returns all feedback for the project. Optionally filter by page URL.

### Method
GET

### Endpoint
/feedback

### Parameters
#### Query Parameters
- **url** (string) - Optional - Filter by page URL

### Response
#### Success Response (200)
- **feedback** (array) - List of feedback objects
```

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

### Update feedback response

Source: https://www.faster-fixes.com/docs/api-reference/feedback-api

Example JSON response returned after updating a feedback item.

```json
{
  "id": "uuid",
  "comment": "Updated comment text",
  "updatedAt": "2025-01-15T11:00:00Z"
}
```

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

### Install MCP server with Claude Code

Source: https://www.faster-fixes.com/docs/mcp/setup

Use this command to add the Faster Fixes MCP server to Claude Code with the required environment variables.

```bash
claude mcp add faster-fixes -s project \
  --env FASTER_FIXES_TOKEN=ff_agent_xxx \
  --env FASTER_FIXES_PROJECT=proj_xxx \
  -- npx -y @fasterfixes/mcp
```

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

### GET /feedbacks

Source: https://www.faster-fixes.com/docs/api-reference/agent-api

Retrieves a list of feedback items for a specific project, with optional filtering by status, page URL, and response format.

```APIDOC
## GET /feedbacks

### Description
Retrieves a list of feedback items for a specific project.

### Method
GET

### Endpoint
/feedbacks

### Parameters
#### Query Parameters
- **project** (string) - Required - Project ID (prefix: proj_)
- **status** (string) - Optional - Filter: new, in_progress, resolved, closed
- **page_url** (string) - Optional - Filter by page URL
- **format** (string) - Optional - json (default) or markdown

### Response
#### Success Response (200)
- **feedbacks** (array) - List of feedback objects
- **count** (integer) - Total number of feedback items
```

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

### Run database migrations

Source: https://www.faster-fixes.com/docs/self-hosting

Command to apply Prisma migrations and generate the client from the repository root.

```bash
pnpm --filter @workspace/db migrate:dev
```

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

### Configure MCP for VS Code (GitHub Copilot)

Source: https://www.faster-fixes.com/docs/mcp/setup

Create a .vscode/mcp.json file. Note that VS Code uses the 'servers' key instead of 'mcpServers'.

```json
{
  "servers": {
    "faster-fixes": {
      "command": "npx",
      "args": ["-y", "@fasterfixes/mcp"],
      "env": {
        "FASTER_FIXES_TOKEN": "ff_agent_xxx",
        "FASTER_FIXES_PROJECT": "proj_xxx"
      }
    }
  }
}
```

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

### Basic useFeedback implementation

Source: https://www.faster-fixes.com/docs/widget/use-feedback-hook

Demonstrates initializing the hook and triggering annotation mode.

```typescript
import { useFeedback } from "@fasterfixes/react";

function CustomFeedbackButton() {
  const { show, hide, isVisible, startAnnotation } = useFeedback();

  return (
    <button onClick={() => startAnnotation()}>
      Report an issue
    </button>
  );
}
```

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

### Configure MCP for Codex

Source: https://www.faster-fixes.com/docs/mcp/setup

Add the server configuration to your .codex/config.toml file.

```toml
[mcp_servers.faster-fixes]
command = "npx"
args = ["-y", "@fasterfixes/mcp"]

[mcp_servers.faster-fixes.env]
FASTER_FIXES_TOKEN = "ff_agent_xxx"
FASTER_FIXES_PROJECT = "proj_xxx"
```

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

### Configure environment variables

Source: https://www.faster-fixes.com/docs/self-hosting

Required environment variables for a self-hosted production deployment.

```bash
# Core
DOMAIN_NAME="your-domain.com"
BASE_URL="https://your-domain.com"
DATABASE_URL="postgresql://user:password@host:5432/db?schema=public"

# Auth
BETTER_AUTH_SECRET="<generate with: openssl rand -base64 32>"
BETTER_AUTH_URL="https://your-domain.com"

# Storage (Cloudflare R2)
STORAGE_REGION="auto"
STORAGE_BUCKET_NAME="your-bucket"
NEXT_PUBLIC_STORAGE_BASE_URL="https://<account-id>.r2.cloudflarestorage.com/your-bucket"
R2_ACCOUNT_ID="..."
R2_ACCESS_KEY_ID="..."
R2_SECRET_ACCESS_KEY="..."

# Inngest (required in production)
INNGEST_EVENT_KEY="..."
INNGEST_SIGNING_KEY="..."

# Transactional email — required for sign-up confirmations and password resets.
# Use either Resend or Plunk.
RESEND_API_KEY="re_..."
# PLUNK_SECRET_KEY="sk_..."

# Widget API (points clients' widgets at your instance)
NEXT_PUBLIC_FF_API_ORIGIN="https://your-domain.com"

# Self-hosted flag (keep false to skip marketing pages)
NEXT_PUBLIC_IS_CLOUD="false"
```

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

### Configure MCP for Zed

Source: https://www.faster-fixes.com/docs/mcp/setup

Add the server configuration to your Zed settings.json file.

```json
{
  "context_servers": {
    "faster-fixes": {
      "command": {
        "path": "npx",
        "args": ["-y", "@fasterfixes/mcp"],
        "env": {
          "FASTER_FIXES_TOKEN": "ff_agent_xxx",
          "FASTER_FIXES_PROJECT": "proj_xxx"
        }
      }
    }
  }
}
```

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

### Initialize Faster Fixes Client

Source: https://www.faster-fixes.com/docs/widget/other-frameworks

Instantiate the FasterFixesClient with your API key and optional API origin.

```javascript
import { FasterFixesClient } from "@fasterfixes/core";

const client = new FasterFixesClient({
  apiKey: "your-api-key",
  apiOrigin: "https://www.faster-fixes.com", // optional
});
```

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

### Configure FeedbackProvider in React

Source: https://www.faster-fixes.com/docs/getting-started/quickstart

Wrap the root layout with FeedbackProvider and provide the project ID. Version 0.0.9 or later is required.

```tsx
import { FeedbackProvider } from "@fasterfixes/react";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html>
      <body>
        <FeedbackProvider projectId="proj_your_project_id">{children}</FeedbackProvider>
      </body>
    </html>
  );
}
```

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

### Configure MCP server for AI agent

Source: https://www.faster-fixes.com/docs/getting-started/quickstart

Define the MCP server configuration in a .mcp.json file to enable AI agent integration.

```json
{
  "mcpServers": {
    "faster-fixes": {
      "command": "npx",
      "args": ["-y", "@fasterfixes/mcp"],
      "env": {
        "FASTER_FIXES_TOKEN": "ff_agent_xxx",
        "FASTER_FIXES_PROJECT": "proj_xxx"
      }
    }
  }
}
```

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

### POST /feedback

Source: https://www.faster-fixes.com/docs/api-reference/feedback-api

Submit new feedback including a comment and optional screenshot.

```APIDOC
## POST /feedback

### Description
Submit new feedback to the project.

### Method
POST

### Endpoint
/feedback

### Request Body
- **data** (JSON string) - Required - Feedback data
- **screenshot** (File) - Optional - PNG, JPEG, or WebP screenshot (max 5MB)

### Response
#### Success Response (200)
- **id** (uuid) - Feedback ID
- **status** (string) - Feedback status
- **comment** (string) - Feedback comment
- **pageUrl** (string) - Page URL
- **selector** (string) - DOM selector
- **clickX** (number) - Click X coordinate
- **clickY** (number) - Click Y coordinate
- **screenshotUrl** (string) - URL to the uploaded screenshot
- **metadata** (object) - Custom metadata
- **reviewer** (object) - Reviewer details
- **createdAt** (string) - Creation timestamp
```

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

### List Feedbacks Endpoint

Source: https://www.faster-fixes.com/docs/api-reference/agent-api

Retrieve a list of feedback items for a specific project.

```http
GET /feedbacks?project=proj_xxx
```

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

### Submit feedback request

Source: https://www.faster-fixes.com/docs/api-reference/feedback-api

Endpoint for creating new feedback entries using multipart/form-data.

```http
POST /feedback
Content-Type: multipart/form-data
```

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

### list_feedbacks

Source: https://www.faster-fixes.com/docs/mcp/tools

Lists feedback items for your project with optional filtering capabilities.

```APIDOC
## list_feedbacks

### Description
Lists feedback items for your project with optional filtering.

### Parameters
- **status** (string) - Optional - Filter by status: `new`, `in_progress`, `resolved`, or `closed`
- **page_url** (string) - Optional - Filter by page URL where feedback was submitted
- **format** (string) - Optional - Output format: `markdown` (default) or `json`
```

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

### FeedbackProvider Customization

Source: https://www.faster-fixes.com/docs/widget/customization

The FeedbackProvider component allows for styling overrides via the classNames prop and text label overrides via the labels prop.

```APIDOC
## FeedbackProvider Component

### Description
Use the `FeedbackProvider` to wrap your application and customize the widget's appearance and text content.

### Props
- **projectId** (string) - Required - The unique identifier for your project.
- **classNames** (object) - Optional - An object mapping component keys to custom CSS class strings.
- **labels** (object) - Optional - An object mapping label keys to custom text strings.

### Available `classNames` keys
- `button`: The floating action button
- `popover`: The comment popover container
- `textarea`: The feedback text input
- `pin`: Feedback pins on the page
- `overlay`: The annotation overlay
- `successState`: Success message after submission
- `errorState`: Error message on failure
- `feedbackList`: The feedback list panel
- `feedbackListItem`: Individual items in the feedback list

### Available `labels` keys
- `submitButton`: Default "Submit"
- `cancelButton`: Default "Cancel"
- `textareaPlaceholder`: Default "Describe the issue..."
- `successMessage`: Default "Feedback sent"
- `closeButton`: Default "Close"
- `retryButton`: Default "Retry"
- `errorMessage`: Default "Something went wrong"
- `deleteConfirm`: Default "Delete this feedback?"
- `deleteButton`: Default "Delete"
- `editButton`: Default "Edit"
- `saveButton`: Default "Save"
- `showResolved`: Default "Show resolved"
- `hideResolved`: Default "Hide resolved"
- `feedbackListTitle`: Default "Feedback"
- `emptyList`: Default "No feedback on this page"
```

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

### FeedbackProvider

Source: https://www.faster-fixes.com/docs/widget/react

The FeedbackProvider component wraps your React application to enable the Faster Fixes widget functionality.

```APIDOC
## FeedbackProvider

### Description
Wraps the application to provide the Faster Fixes widget context. Requires a project ID to initialize.

### Props
- **projectId** (string) - Required - Your Faster Fixes Project ID.
- **apiKey** (string) - Optional - Deprecated alias for projectId.
- **apiOrigin** (string) - Optional - API base URL. Defaults to https://www.faster-fixes.com.
- **color** (string) - Optional - Accent color. Accepts any CSS color value. Defaults to #02527E.
- **position** (WidgetPosition) - Optional - Floating button placement. Defaults to bottom-right.
- **classNames** (object) - Optional - CSS class overrides for widget elements.
- **labels** (object) - Optional - Custom text labels for the widget UI.

### Usage Example
```tsx
import { FeedbackProvider } from "@fasterfixes/react";

export default function RootLayout({ children }) {
  return (
    <FeedbackProvider projectId="proj_your_project_id">
      {children}
    </FeedbackProvider>
  );
}
```
```

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

### Override widget text with labels

Source: https://www.faster-fixes.com/docs/widget/customization

Use the labels prop to provide partial overrides for default text strings within the widget.

```jsx
<FeedbackProvider
  projectId="proj_your_project_id"
  labels={{
    submitButton: "Send feedback",
    cancelButton: "Cancel",
    textareaPlaceholder: "Describe the issue...",
    successMessage: "Feedback submitted",
  }}
>
  {children}
</FeedbackProvider>
```

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

### Toggle feedback pins

Source: https://www.faster-fixes.com/docs/widget/use-feedback-hook

Provides a control to toggle the visibility of feedback pins on the page.

```typescript
import { useFeedback } from "@fasterfixes/react";

function PinToggle() {
  const { togglePins, showPins } = useFeedback();

  return (
    <button onClick={togglePins}>
      {showPins ? "Hide" : "Show"} feedback pins
    </button>
  );
}
```

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

### JSON Feedback Response

Source: https://www.faster-fixes.com/docs/api-reference/agent-api

The structure of the feedback list response in JSON format.

```json
{
  "feedbacks": [
    {
      "id": "uuid",
      "status": "new",
      "comment": "The spacing between these buttons is too large",
      "pageUrl": "https://myapp.com/settings",
      "selector": "[data-testid=\"save-btn\"]",
      "clickX": 450,
      "clickY": 320,
      "viewportWidth": 1920,
      "viewportHeight": 1080,
      "browserName": "Chrome",
      "browserVersion": "120",
      "os": "macOS",
      "screenshotUrl": "https://...",
      "metadata": {},
      "diagnosticTrail": {
        "console": [
          { "level": "error", "message": "Uncaught TypeError: x is undefined", "timestamp": 1736937000000 }
        ],
        "network": [
          { "method": "GET", "url": "https://api.myapp.com/user", "status": 500, "duration": 142, "timestamp": 1736937000000 }
        ]
      },
      "reviewerName": "Sarah",
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "count": 1
}
```

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

### Set Authorization Header

Source: https://www.faster-fixes.com/docs/api-reference/agent-api

Include this header in all API requests to authenticate with a Bearer token.

```http
Authorization: Bearer ff_agent_xxx
```

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

### Update Status Response

Source: https://www.faster-fixes.com/docs/api-reference/agent-api

The response returned after successfully updating a feedback status.

```json
{
  "id": "uuid",
  "status": "resolved",
  "updatedAt": "2025-01-15T11:00:00Z"
}
```

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

### useFeedback Hook API

Source: https://www.faster-fixes.com/docs/widget/use-feedback-hook

The useFeedback hook provides methods and state properties to interact with the widget. It must be used within a component wrapped by the FeedbackProvider.

```APIDOC
## useFeedback()

### Description
Provides programmatic control over the widget from any component inside the `FeedbackProvider`.

### Return Values
- **show** (() => void) - Show the widget
- **hide** (() => void) - Hide the widget
- **isVisible** (boolean) - Whether the widget is currently visible
- **startAnnotation** (() => void) - Enter annotation mode (user can click elements)
- **feedbackItems** (FeedbackItem[]) - All feedback items for the current project
- **togglePins** (() => void) - Toggle visibility of feedback pins on the page
- **showPins** (boolean) - Whether pins are currently visible

### Usage Example
```javascript
import { useFeedback } from "@fasterfixes/react";

function CustomFeedbackButton() {
  const { show, hide, isVisible, startAnnotation } = useFeedback();

  return (
    <button onClick={() => startAnnotation()}>
      Report an issue
    </button>
  );
}
```
```

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

### Customize Widget Color

Source: https://www.faster-fixes.com/docs/widget/react

Apply custom colors using standard CSS values or CSS variables via the color prop.

```tsx
<FeedbackProvider projectId="proj_your_project_id" color="var(--color-blue-500)">
```

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

### Override widget styles with classNames

Source: https://www.faster-fixes.com/docs/widget/customization

Use the classNames prop on the FeedbackProvider to apply custom CSS classes to specific widget elements.

```jsx
<FeedbackProvider
  projectId="proj_your_project_id"
  classNames={{
    button: "my-custom-button",
    popover: "my-custom-popover",
    textarea: "my-custom-textarea",
  }}
>
  {children}
</FeedbackProvider>
```

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

### Custom trigger button

Source: https://www.faster-fixes.com/docs/widget/use-feedback-hook

Replaces the default floating button with a custom UI that displays the current feedback count.

```typescript
import { useFeedback } from "@fasterfixes/react";

function FeedbackTrigger() {
  const { startAnnotation, feedbackItems } = useFeedback();

  return (
    <div>
      <button onClick={() => startAnnotation()}>
        Leave feedback ({feedbackItems.length})
      </button>
    </div>
  );
}
```

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

### POST /feedbacks/:id/status

Source: https://www.faster-fixes.com/docs/api-reference/agent-api

Updates the status of a specific feedback item.

```APIDOC
## POST /feedbacks/:id/status

### Description
Updates the status of a feedback item. If a GitHub issue is linked, the status change is automatically synced.

### Method
POST

### Endpoint
/feedbacks/:id/status

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the feedback item

#### Request Body
- **status** (string) - Required - new, in_progress, resolved, or closed

### Request Example
{
  "status": "resolved"
}

### Response
#### Success Response (200)
- **id** (string) - Feedback ID
- **status** (string) - Updated status
- **updatedAt** (string) - Timestamp of the update
```

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

### Update feedback request

Source: https://www.faster-fixes.com/docs/api-reference/feedback-api

Endpoint for updating the comment of an existing feedback item.

```http
PUT /feedback/:id
Content-Type: application/json
```

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

### DELETE /feedback/:id

Source: https://www.faster-fixes.com/docs/api-reference/feedback-api

Permanently delete a feedback item.

```APIDOC
## DELETE /feedback/:id

### Description
Permanently deletes the feedback item.

### Method
DELETE

### Endpoint
/feedback/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The feedback ID

### Response
#### Success Response (204)
- No Content
```

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

### PUT /feedback/:id

Source: https://www.faster-fixes.com/docs/api-reference/feedback-api

Update the comment of an existing feedback item.

```APIDOC
## PUT /feedback/:id

### Description
Updates the comment for a specific feedback item.

### Method
PUT

### Endpoint
/feedback/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The feedback ID

### Request Body
- **comment** (string) - Required - Updated comment

### Response
#### Success Response (200)
- **id** (uuid) - Feedback ID
- **comment** (string) - Updated comment text
- **updatedAt** (string) - Update timestamp
```

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

### Update Status Request Body

Source: https://www.faster-fixes.com/docs/api-reference/agent-api

The JSON body required to update the feedback status.

```json
{
  "status": "resolved"
}
```

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

### Update Feedback Status Endpoint

Source: https://www.faster-fixes.com/docs/api-reference/agent-api

Update the status of a specific feedback item using a POST request.

```http
POST /feedbacks/:id/status
Content-Type: application/json
```

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

### Delete feedback request

Source: https://www.faster-fixes.com/docs/api-reference/feedback-api

Endpoint for permanently removing a feedback item.

```http
DELETE /feedback/:id
```

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

### update_feedback_status

Source: https://www.faster-fixes.com/docs/mcp/tools

Updates the status of a specific feedback item.

```APIDOC
## update_feedback_status

### Description
Updates the status of a feedback item.

### Parameters
- **feedback_id** (string) - Required - The feedback ID (UUID) to update
- **status** (string) - Required - New status: `new`, `in_progress`, `resolved`, or `closed`
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.