### Development Environment Setup

Source: https://context7.com/automagik-dev/forge/llms.txt

Commands to clone the repository and start the development server with hot-reload.

```bash
# Clone the repository
git clone https://github.com/namastexlabs/automagik-forge.git
cd automagik-forge

# Copy environment example (optional - for custom ports)
cp .env.example .env

# Start development server (handles all dependencies automatically)
make dev

# Alternative: Manual command
pnpm install
pnpm run dev

# Start frontend and backend separately
npm run frontend:dev    # Frontend only (port 3000)
npm run backend:dev     # Backend only (auto-assigned port)
```

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

### Set Up Development Environment

Source: https://github.com/automagik-dev/forge/blob/main/README.md

Copy the example environment file to .env for custom port configuration. Then, start the development server using the make dev command.

```bash
# Copy environment example (optional - only needed for custom ports)
cp .env.example .env

# Start development server
make dev
```

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

### Manual Development Commands

Source: https://github.com/automagik-dev/forge/blob/main/DEVELOPER.md

Commands for installing dependencies and starting the frontend and backend servers manually.

```bash
# Install dependencies
pnpm install

# Start both servers
pnpm run dev

# Or start individually
npm run frontend:dev    # Frontend only (port 3000)
npm run backend:dev     # Backend only (port auto-assigned)
```

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

### Quick Systemd Service Installation

Source: https://github.com/automagik-dev/forge/blob/main/scripts/service/README.md

Recommended for production environments. This command automates the detection of your OS, prompts for a dedicated service account, installs the systemd service, enables auto-start, and starts the service.

```bash
# From project root
make service
```

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

### Troubleshooting Service Start Failures

Source: https://github.com/automagik-dev/forge/blob/main/scripts/service/README.md

Commands to help diagnose why the service might be failing to start. Includes checking logs, verifying binary existence, and testing manual start.

```bash
# Check logs
sudo journalctl -u automagik-forge -n 50

# Verify binary exists
which automagik-forge

# Test manual start
automagik-forge
```

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

### Install sqlx-cli

Source: https://github.com/automagik-dev/forge/blob/main/DEVELOPER.md

Install the SQLx command-line tool for database migrations with SQLite support.

```bash
cargo install sqlx-cli --no-default-features --features sqlite
```

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

### Dev-Core Branch Sync Example (Incorrect)

Source: https://github.com/automagik-dev/forge/blob/main/docs/DUAL_REPO_WORKFLOW.md

This example demonstrates an incorrect dev-core setup where the branches for automagik-forge and forge-core do not match, which will be blocked by the Makefile.

```bash
# In automagik-forge on branch: feat/ui-improvements
make dev-core BRANCH=dev
# ERROR: Branch mismatch!
```

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

### Quick Start Development Environment

Source: https://github.com/automagik-dev/forge/blob/main/DEVELOPER.md

Clone the repository and initialize the development environment using the provided Makefile.

```bash
# 1. Clone the repository
git clone https://github.com/namastexlabs/automagik-forge.git
cd automagik-forge

# 2. (Optional) Copy .env.example to .env for custom port configuration
cp .env.example .env

# 3. Start development environment
make dev
```

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

### Install and Initialize Automagik Genie

Source: https://github.com/automagik-dev/forge/blob/main/README.md

Install the automagik-genie package globally and initialize it within your project directory to enable AI-assisted planning and agent management.

```bash
npm install -g automagik-genie
cd your-project
genie init
```

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

### MCP Genie Tool Syntax Examples

Source: https://github.com/automagik-dev/forge/blob/main/AGENTS.md

Examples of how to invoke various MCP Genie tools with their respective arguments. Use these for discovering agents, managing tasks, and loading workspace information.

```bash
mcp__genie__list_agents - No arguments
```

```bash
mcp__genie__read_spell - Argument: spell_path="know-yourself"
```

```bash
mcp__genie__task - Arguments: agent="code", prompt="Task description"
```

```bash
mcp__genie__continue_task - Arguments: task_id="attempt-id", prompt="Follow-up message"
```

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

### Install and Run Automagik Forge

Source: https://context7.com/automagik-dev/forge/llms.txt

Commands to run the platform via npx or install globally for persistent use.

```bash
# Run directly with npx (no installation required)
npx @automagik/forge

# Or install globally for persistent use
npm install -g @automagik/forge
automagik-forge

# Navigate to your project directory first
cd your-project
automagik-forge

# Customize port if needed
BACKEND_PORT=8888 npx @automagik/forge

# Run in MCP mode for AI tool integration
npx @automagik/forge --mcp
```

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

### Dev-Core Branch Sync Example (Correct)

Source: https://github.com/automagik-dev/forge/blob/main/docs/DUAL_REPO_WORKFLOW.md

When developing with dev-core mode, ensure the branch used for `make dev-core` in automagik-forge matches the branch checked out in forge-core. This example shows a correct setup.

```bash
# In automagik-forge on branch: feat/task-scheduling
make dev-core BRANCH=feat/task-scheduling
# forge-core checks out: feat/task-scheduling
```

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

### Start Development Server for Task Attempt

Source: https://context7.com/automagik-dev/forge/llms.txt

Start a development server associated with a specific task attempt. This is useful for running and testing code in a live environment.

```bash
# Start development server for an attempt
curl -X POST http://localhost:8887/api/task-attempts/{attempt_id}/start-dev-server
```

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

### Install Automagik Forge

Source: https://github.com/automagik-dev/forge/blob/main/README.md

Commands to install the Forge CLI globally or execute it via npx.

```bash
# Install globally
npm install -g @automagik/forge

# Or run directly with npx
npx @automagik/forge
```

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

### Start new agent task

Source: https://github.com/automagik-dev/forge/blob/main/AGENTS.md

Initializes a new task for a specific agent with a descriptive prompt.

```bash
mcp__genie__task(agent="code", prompt="Task description")
```

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

### Install and Configure LLD Linker

Source: https://github.com/automagik-dev/forge/blob/main/docs/RUNNER-OPTIMIZATION-REPORT.md

Commands to install the LLD linker and apply it via RUSTFLAGS.

```bash
# On the runner, install lld:
sudo apt-get install -y lld

# Then in workflow, add RUSTFLAGS:
RUSTFLAGS="-C link-arg=-fuse-ld=lld"
```

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

### Quick Start Development Workflow

Source: https://github.com/automagik-dev/forge/blob/main/docs/DUAL_REPO_WORKFLOW.md

Commands to initialize development mode, commit changes, and push updates across both repositories.

```bash
# 1. Enable dev-core mode (syncs both repos to same branch)
make dev-core BRANCH=feat/my-feature

# 2. Edit files in EITHER or BOTH repos
# Changes auto-rebuild via cargo-watch

# 3. Commit from automagik-forge ROOT ONLY
git add . && git commit -m "feat: your changes"
# → pre-commit hook stages forge-core changes
# → prepare-commit-msg hook commits forge-core with SAME message

# 4. Push - FULLY AUTOMATIC!
git push
# → pre-push hook pushes forge-core first
# → pre-push hook disables Cargo [patch]
# → pre-push hook amends commit with Cargo.lock
# → Push proceeds!

# 5. Create PRs for BOTH repos
make pr-both                # Creates PRs in both repos with RC label
```

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

### Install Automagik Forge via npm

Source: https://github.com/automagik-dev/forge/blob/main/android/README.md

Install the Automagik Forge CLI globally using npm and then run the command to launch the application. This is an alternative installation method for Termux users.

```bash
pkg install nodejs
npm install -g @automagik/forge
forge
```

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

### Install Genie MCP

Source: https://github.com/automagik-dev/forge/blob/main/README.md

Install the Genie MCP command-line tool globally using npm. This is the recommended AI assistant for planning and managing Forge tasks.

```bash
npm install -g automagik-genie
```

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

### Verify linker installation

Source: https://github.com/automagik-dev/forge/blob/main/docs/RUNNER-OPTIMIZATION-REPORT.md

Check if the lld linker is installed and accessible.

```bash
which lld
ld.lld --version
```

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

### Install Android Target for Rust

Source: https://github.com/automagik-dev/forge/blob/main/android/README.md

Commands to install the `aarch64-linux-android` Rust target. Use the `pkg` command on Termux and `rustup` on desktop environments.

```bash
# Termux
pkg install rust-std-aarch64-linux-android

# Desktop
rustup target add aarch64-linux-android
```

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

### Launch Automagik Forge

Source: https://github.com/automagik-dev/forge/blob/main/README.md

Commands to navigate to a project directory and start the Forge interface.

```bash
# Navigate to your project
cd your-project

# Launch Forge (browser opens automatically to http://localhost:8887)
automagik-forge
```

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

### Example Executor Profile Configuration

Source: https://context7.com/automagik-dev/forge/llms.txt

An example JSON structure for configuring executor profiles. This demonstrates settings for CLAUDE_CODE and GEMINI executors, including routing, planning, and model selection.

```json
# Example executor profile configuration:
{
  "CLAUDE_CODE": {
    "default": {
      "append_prompt": null,
      "claude_code_router": false,
      "plan": false,
      "approvals": true,
      "model": null,
      "dangerously_skip_permissions": false
    },
    "ROUTER": {
      "append_prompt": "Use your best judgment to route to appropriate models",
      "claude_code_router": true
    },
    "PLAN": {
      "append_prompt": "Create a detailed implementation plan before coding",
      "plan": true
    }
  },
  "GEMINI": {
    "default": {
      "append_prompt": null,
      "model": "default",
      "yolo": false
    },
    "flash": {
      "model": "flash",
      "yolo": true
    }
  }
}
```

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

### Manual Systemd Service Installation (Personal Account)

Source: https://github.com/automagik-dev/forge/blob/main/scripts/service/README.md

This option is suitable for development. It uses your current user account to run the service and sets up necessary directories under your home directory.

```bash
./scripts/service/install.sh
```

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

### Configure sccache for Distributed Caching

Source: https://github.com/automagik-dev/forge/blob/main/docs/RUNNER-OPTIMIZATION-REPORT.md

Setup instructions for sccache to enable persistent build caching.

```bash
cargo install sccache
export RUSTC_WRAPPER=sccache
export SCCACHE_DIR=/opt/sccache  # Persistent directory
```

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

### Install Rust and Node.js on Termux

Source: https://github.com/automagik-dev/forge/blob/main/android/README.md

These commands install the necessary Rust toolchain, OpenJDK, Node.js, and pnpm on Termux for building the Android application components.

```bash
pkg install rust rust-std-aarch64-linux-android openjdk-21 nodejs
npm install -g pnpm
```

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

### Build Production Package

Source: https://github.com/automagik-dev/forge/blob/main/scripts/service/README.md

Before installing the systemd service, build the production package. This step ensures the server is ready to be run as a service.

```bash
# 1. Build production package first
make prod

# 2. Verify it works
# (Server should start and be accessible)
```

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

### Manual Systemd Service Installation (Dedicated Account)

Source: https://github.com/automagik-dev/forge/blob/main/scripts/service/README.md

Use this option for production to set up a dedicated service account and secure directories. It creates a system user 'forge', hardened directories, a systemd service, and enables auto-start.

```bash
sudo ./scripts/service/setup.sh
```

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

### Launch Automagik Forge

Source: https://github.com/automagik-dev/forge/blob/main/npx-cli/README.md

Execute the application locally using npx without requiring a formal installation.

```bash
npx @automagik/forge
```

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

### Install Rust Target and Tools on Linux

Source: https://github.com/automagik-dev/forge/blob/main/android/README.md

On Linux desktops, install the Rust cross-compilation target for Android ARM64 and ensure JDK, Node.js, and pnpm are installed via your package manager. Android SDK and NDK are also required.

```bash
# Install Rust from https://rustup.rs
rustup target add aarch64-linux-android

# Install JDK 17, Node.js, pnpm from your package manager
# Install Android SDK and NDK (for cross-compilation)
```

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

### Initiate New Task Attempt

Source: https://github.com/automagik-dev/forge/blob/main/tests/e2e/USER-JOURNEYS.md

Locate and click the 'Start new attempt' button using its role and accessible name.

```javascript
getByRole('button', { name: 'Start new attempt' })
```

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

### Commit Message Examples

Source: https://github.com/automagik-dev/forge/blob/main/CONTRIBUTING.md

Follow these conventional commit message formats to maintain a clear project history.

```text
feat: add task filtering by executor
fix: resolve worktree cleanup race condition
docs: update MCP integration guide
refactor: simplify event streaming logic
```

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

### GET /api/filesystem/git-repos

Source: https://context7.com/automagik-dev/forge/llms.txt

Lists git repositories within a specified directory.

```APIDOC
## GET /api/filesystem/git-repos

### Description
Lists git repositories in a directory.

### Method
GET

### Endpoint
/api/filesystem/git-repos

### Parameters
#### Query Parameters
- **path** (string) - Required - The directory path to search for git repositories.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the list of entries and the current path.
```

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

### Get Workspace Information

Source: https://github.com/automagik-dev/forge/blob/main/AGENTS.md

Retrieve mission, tech stack, roadmap, and environment details using this command.

```javascript
mcp__genie__get_workspace_info
```

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

### Create and Start Task Immediately using cURL

Source: https://context7.com/automagik-dev/forge/llms.txt

This endpoint creates a task and initiates AI agent execution in a single call. It sets up an isolated git worktree for the execution.

```bash
curl -X POST http://localhost:8887/api/tasks/create-and-start \
  -H "Content-Type: application/json" \
  -d '{
    "task": {
      "project_id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Fix authentication bug",
      "description": "The login endpoint returns 500 when email contains special characters",
      "parent_task_attempt": null,
      "image_ids": []
    },
    "executor_profile_id": {
      "executor": "CLAUDE_CODE",
      "variant": null
    },
    "base_branch": "main",
    "use_worktree": true
  }'
```

```json
{
  "success": true,
  "data": {
    "id": "task-uuid",
    "project_id": "project-uuid",
    "title": "Fix authentication bug",
    "status": "inprogress",
    "has_in_progress_attempt": true,
    "executor": "CLAUDE_CODE",
    "attempt_count": 1,
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

```bash
curl -X POST http://localhost:8887/api/tasks/create-and-start \
  -H "Content-Type: application/json" \
  -d '{
    "task": {
      "project_id": "project-uuid",
      "title": "Refactor database queries",
      "description": "Optimize slow queries in the user service"
    },
    "executor_profile_id": {
      "executor": "CLAUDE_CODE",
      "variant": "ROUTER"
    },
    "base_branch": "develop"
  }'
```

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

### Configuration API

Source: https://context7.com/automagik-dev/forge/llms.txt

Get and update application configuration including editor settings, notifications, and theme.

```APIDOC
## GET /api/info

### Description
Retrieves the current application configuration and system information.

### Method
GET

### Endpoint
/api/info

### Request Body
None

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains configuration and system details.
  - **config** (object) - Application configuration settings.
    - **config_version** (string) - The version of the configuration.
    - **theme** (string) - The application theme (e.g., "DARK", "LIGHT").
    - **executor_profile** (object) - Settings for the code executor.
      - **executor** (string) - The type of executor (e.g., "CLAUDE_CODE").
      - **variant** (string|null) - The specific variant of the executor.
    - **notifications** (object) - Notification settings.
      - **sound_enabled** (boolean) - Whether sound notifications are enabled.
      - **push_enabled** (boolean) - Whether push notifications are enabled.
      - **sound_file** (string) - The name of the sound file for notifications.
    - **editor** (object) - Editor settings.
      - **editor_type** (string) - The type of editor (e.g., "VS_CODE", "CURSOR").
      - **custom_command** (string|null) - A custom command for the editor.
    - **language** (string) - The application language (e.g., "EN", "JA").
    - **git_branch_prefix** (string) - The prefix for Git branches.
  - **analytics_user_id** (string) - A unique identifier for analytics.
  - **environment** (object) - System environment details.
    - **os_type** (string) - The operating system type.
    - **os_version** (string) - The operating system version.
    - **os_architecture** (string) - The operating system architecture.
  - **executors** (object) - Available executors and their configurations.
  - **capabilities** (object) - Capabilities of different executors.

### Response Example
```json
{
  "success": true,
  "data": {
    "config": {
      "config_version": "1.0",
      "theme": "DARK",
      "executor_profile": {
        "executor": "CLAUDE_CODE",
        "variant": null
      },
      "notifications": {
        "sound_enabled": true,
        "push_enabled": false,
        "sound_file": "GENIE_NOTIFY1"
      },
      "editor": {
        "editor_type": "VS_CODE",
        "custom_command": null
      },
      "language": "EN",
      "git_branch_prefix": "forge"
    },
    "analytics_user_id": "anon-uuid",
    "environment": {
      "os_type": "linux",
      "os_version": "5.15.0",
      "os_architecture": "x86_64"
    },
    "executors": {
      "CLAUDE_CODE": {...},
      "GEMINI": {...}
    },
    "capabilities": {
      "CLAUDE_CODE": ["SESSION_FORK", "SETUP_HELPER"]
    }
  }
}
```

## PUT /api/config

### Description
Updates the application configuration.

### Method
PUT

### Endpoint
/api/config

### Parameters
#### Request Body
- **theme** (string) - Optional - The application theme (e.g., "LIGHT", "DARK", "SYSTEM").
- **notifications** (object) - Optional - Notification settings.
  - **sound_enabled** (boolean) - Whether sound notifications are enabled.
  - **push_enabled** (boolean) - Whether push notifications are enabled.
  - **sound_file** (string) - The name of the sound file for notifications.
- **editor** (object) - Optional - Editor settings.
  - **editor_type** (string) - The type of editor (e.g., "VS_CODE", "CURSOR", "WINDSURF", "INTELLI_J", "ZED", "XCODE", "CUSTOM").
  - **custom_command** (string|null) - A custom command for the editor.
- **language** (string) - Optional - The application language (e.g., "BROWSER", "EN", "JA", "ES", "KO").

### Request Example
```json
{
  "theme": "LIGHT",
  "notifications": {
    "sound_enabled": false,
    "push_enabled": true,
    "sound_file": "ABSTRACT_SOUND1"
  },
  "editor": {
    "editor_type": "CURSOR",
    "custom_command": null
  },
  "language": "EN"
}
```

### Response
#### Success Response (200)
Returns the updated configuration.

### Response Example
```json
{
  "success": true,
  "data": {
    "config_version": "1.0",
    "theme": "LIGHT",
    "executor_profile": {
      "executor": "CLAUDE_CODE",
      "variant": null
    },
    "notifications": {
      "sound_enabled": false,
      "push_enabled": true,
      "sound_file": "ABSTRACT_SOUND1"
    },
    "editor": {
      "editor_type": "CURSOR",
      "custom_command": null
    },
    "language": "EN",
    "git_branch_prefix": "forge"
  }
}
```
```

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

### Configure Cargo Cache Paths

Source: https://github.com/automagik-dev/forge/blob/main/docs/RUNNER-OPTIMIZATION-REPORT.md

Example of a relative path configuration for cargo cache that may cause cache misses.

```yaml
path: |
  ~/.cargo/registry
  ~/.cargo/git
  target
```

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

### Get All Executor Profiles

Source: https://context7.com/automagik-dev/forge/llms.txt

Retrieve all available executor profiles. These profiles define how different AI models or executors should behave.

```bash
# Get all executor profiles
curl http://localhost:8887/api/profiles
```

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

### Clone Automagik Forge Repository

Source: https://github.com/automagik-dev/forge/blob/main/README.md

Clone the Automagik Forge repository from GitHub to start development. This command downloads the project's source code.

```bash
# Clone the repository
git clone https://github.com/namastexlabs/automagik-forge.git
cd automagik-forge
```

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

### Example Forge-Core Pre-Release Tag Format

Source: https://github.com/automagik-dev/forge/blob/main/docs/DUAL_REPO_WORKFLOW.md

Pre-release tags generated by the CI follow the format 'vX.Y.Z-YYYYMMDD-HHMMSS'. This format includes the version number, date, and time of creation.

```text
v0.8.5-20251201-143022
```

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

### Configure Genie MCP Server

Source: https://github.com/automagik-dev/forge/blob/main/README.md

Configure the Genie MCP server in Claude Desktop. This setup allows Genie to be recognized as an MCP server for interacting with Forge.

```json
{
  "mcpServers": {
    "genie": {
      "command": "genie",
      "args": ["mcp"]
    }
  }
}
```

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

### POST /api/tasks/create-and-start

Source: https://context7.com/automagik-dev/forge/llms.txt

Creates a task and immediately triggers AI agent execution.

```APIDOC
## POST /api/tasks/create-and-start

### Description
Creates a task and starts execution in an isolated git worktree.

### Method
POST

### Endpoint
/api/tasks/create-and-start

### Request Body
- **task** (object) - Required - Task details.
- **executor_profile_id** (object) - Required - Executor configuration (executor, variant).
- **base_branch** (string) - Required - The git branch to base the worktree on.
- **use_worktree** (boolean) - Required - Whether to use a git worktree.

### Request Example
{
  "task": {
    "project_id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Fix authentication bug",
    "description": "The login endpoint returns 500",
    "parent_task_attempt": null,
    "image_ids": []
  },
  "executor_profile_id": {
    "executor": "CLAUDE_CODE",
    "variant": null
  },
  "base_branch": "main",
  "use_worktree": true
}
```

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

### Manage Application Configuration

Source: https://context7.com/automagik-dev/forge/llms.txt

Retrieve system information and update user preferences like theme and editor settings.

```bash
# Get current configuration and system info
curl http://localhost:8887/api/info

# Response:
{
  "success": true,
  "data": {
    "config": {
      "config_version": "1.0",
      "theme": "DARK",
      "executor_profile": {
        "executor": "CLAUDE_CODE",
        "variant": null
      },
      "notifications": {
        "sound_enabled": true,
        "push_enabled": false,
        "sound_file": "GENIE_NOTIFY1"
      },
      "editor": {
        "editor_type": "VS_CODE",
        "custom_command": null
      },
      "language": "EN",
      "git_branch_prefix": "forge"
    },
    "analytics_user_id": "anon-uuid",
    "environment": {
      "os_type": "linux",
      "os_version": "5.15.0",
      "os_architecture": "x86_64"
    },
    "executors": {
      "CLAUDE_CODE": {...},
      "GEMINI": {...}
    },
    "capabilities": {
      "CLAUDE_CODE": ["SESSION_FORK", "SETUP_HELPER"]
    }
  }
}

# Update configuration
curl -X PUT http://localhost:8887/api/config \
  -H "Content-Type: application/json" \
  -d '{
    "theme": "LIGHT",
    "notifications": {
      "sound_enabled": false,
      "push_enabled": true,
      "sound_file": "ABSTRACT_SOUND1"
    },
    "editor": {
      "editor_type": "CURSOR",
      "custom_command": null
    },
    "language": "EN"
  }'

# Editor types: VS_CODE, CURSOR, WINDSURF, INTELLI_J, ZED, XCODE, CUSTOM
# Themes: LIGHT, DARK, SYSTEM
# Languages: BROWSER, EN, JA, ES, KO
```

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

### Build Android APK Options

Source: https://github.com/automagik-dev/forge/blob/main/android/README.md

These commands demonstrate different build options for the Android APK, including debug builds, release builds, and builds with verification. Use --help for a full list of options.

```bash
# Debug build (faster, larger APK)
./scripts/build-android.sh

# Release build (optimized)
./scripts/build-android.sh --release

# With verification (checks APK contents)
./scripts/build-android.sh --release --verify

# Help
./scripts/build-android.sh --help
```

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

### Enable dev-core Mode

Source: https://github.com/automagik-dev/forge/blob/main/docs/DUAL_REPO_WORKFLOW.md

Initializes the development environment by cloning forge-core and configuring local path overrides.

```bash
# Match branches automatically (RECOMMENDED)
make dev-core BRANCH=feat/my-feature

# This will:
# - Clone forge-core if not present
# - Checkout the specified branch in forge-core
# - Verify both repos are on matching branches
# - Enable Cargo [patch] to use local forge-core
# - Install pre-push safety hook
# - Start dev server with hot reload
```

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

### Send Follow-up Instructions to Task Attempt

Source: https://context7.com/automagik-dev/forge/llms.txt

Use this endpoint to send follow-up instructions for a specific task attempt. Ensure the Content-Type is set to application/json.

```bash
curl -X POST http://localhost:8887/api/task-attempts/{attempt_id}/follow-up \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Please also add unit tests for the authentication endpoints",
    "variant": null,
    "image_ids": [],
    "retry_process_id": null,
    "force_when_dirty": false,
    "perform_git_reset": false
  }'
```

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

### GET /api/profiles

Source: https://context7.com/automagik-dev/forge/llms.txt

Retrieves all executor profiles.

```APIDOC
## GET /api/profiles

### Description
Get all executor profiles.

### Method
GET

### Endpoint
/api/profiles
```

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

### GET /api/mcp-config

Source: https://context7.com/automagik-dev/forge/llms.txt

Retrieves the MCP server configuration for a specific executor.

```APIDOC
## GET /api/mcp-config

### Description
Get MCP server configuration for an executor.

### Method
GET

### Endpoint
/api/mcp-config

### Parameters
#### Query Parameters
- **executor** (string) - Required - The name of the executor (e.g., CLAUDE_CODE).
```

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

### Branch Mismatch Error

Source: https://github.com/automagik-dev/forge/blob/main/docs/DUAL_REPO_WORKFLOW.md

Example of the error message displayed when repository branches are not synchronized.

```text
❌ Branch mismatch detected:
  automagik-forge: feat/ui-improvements
  forge-core:      dev

💡 To fix: make dev-core BRANCH=feat/ui-improvements
```

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

### GET /api/task-attempts/{attempt_id}/branch-status

Source: https://context7.com/automagik-dev/forge/llms.txt

Retrieves the git status of a specific task attempt.

```APIDOC
## GET /api/task-attempts/{attempt_id}/branch-status

### Description
Returns information about commits behind/ahead and uncommitted changes for a specific attempt.

### Method
GET

### Endpoint
/api/task-attempts/{attempt_id}/branch-status

### Parameters
#### Path Parameters
- **attempt_id** (string) - Required - The UUID of the attempt.

### Response
#### Success Response (200)
- **commits_behind** (integer) - Number of commits behind target branch.
- **commits_ahead** (integer) - Number of commits ahead of target branch.
- **has_uncommitted_changes** (boolean) - Whether there are uncommitted changes.
- **head_oid** (string) - Current head OID.
- **target_branch_name** (string) - Name of the target branch.
```

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

### Build Commands

Source: https://github.com/automagik-dev/forge/blob/main/DEVELOPER.md

Commands for building the Rust workspace, frontend, and production packages.

```bash
# Build Rust workspace
cargo build --workspace

# Build frontend
cd frontend && pnpm build
```

```bash
./build-npm-package.sh
```

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

### Get Task by ID using cURL

Source: https://context7.com/automagik-dev/forge/llms.txt

Retrieve a specific task by its unique ID.

```bash
curl http://localhost:8887/api/tasks/{task_id}
```

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

### Build Android APK (Release)

Source: https://github.com/automagik-dev/forge/blob/main/android/README.md

Use this command from the repository root to build a release version of the Android APK. It compiles the frontend, Rust library, and packages everything into an APK.

```bash
# From repository root
./scripts/build-android.sh --release
```

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

### Prompt LLMs for test generation

Source: https://github.com/automagik-dev/forge/blob/main/tests/e2e/README.md

Examples of effective prompts for generating or debugging Playwright tests.

```text
Write a Playwright test that verifies the task archive functionality.
Use getByRole for buttons, getByTestId for custom components.
Follow the Given/When/Then pattern.
```

```text
Write a test for archiving tasks
```

```text
This test is failing: [paste error]
Screenshot shows: [describe what you see]
The test is trying to: [describe expected behavior]
```

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

### Backend Testing Commands

Source: https://github.com/automagik-dev/forge/blob/main/DEVELOPER.md

Commands for running Rust tests, formatting, and linting with Clippy.

```bash
# Run all Rust tests
cargo test --workspace

# Test specific crate
cargo test -p forge-server

# Run specific test
cargo test test_name

# Check Rust formatting
cargo fmt --all -- --check

# Run Clippy linter
cargo clippy --all --all-targets --all-features -- -D warnings
```

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

### Database Migration Commands

Source: https://github.com/automagik-dev/forge/blob/main/DEVELOPER.md

SQLx commands for managing database schema migrations.

```bash
# Apply all pending migrations
sqlx migrate run

# Create new migration
sqlx migrate add <migration_name>

# Revert last migration
sqlx migrate revert
```

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

### Initialize and Use TypeScript API Client

Source: https://context7.com/automagik-dev/forge/llms.txt

Import and utilize various API modules for managing projects, tasks, attempts, and configuration. Ensure all necessary API modules are imported before use.

```typescript
import {
  projectsApi,
  tasksApi,
  attemptsApi,
  executionProcessesApi,
  configApi,
  githubAuthApi,
  imagesApi,
  tagsApi,
} from './lib/api';

// Project management
const projects = await projectsApi.getAll();
const project = await projectsApi.create({
  name: 'my-project',
  git_repo_path: '/path/to/repo',
  use_existing_repo: true,
  setup_script: 'npm install',
  dev_script: 'npm run dev',
  cleanup_script: null,
  copy_files: null,
});

// Task management
const tasks = await tasksApi.getAll(project.id);
const task = await tasksApi.create({
  project_id: project.id,
  title: 'Implement feature',
  description: 'Add new authentication feature',
  parent_task_attempt: null,
  image_ids: [],
});

// Create and start task with AI agent
const runningTask = await tasksApi.createAndStart({
  task: {
    project_id: project.id,
    title: 'Fix bug',
    description: 'Fix the login issue',
  },
  executor_profile_id: {
    executor: 'CLAUDE_CODE',
    variant: null,
  },
  base_branch: 'main',
  use_worktree: true,
});

// Manage attempts
const attempts = await attemptsApi.getAll(task.id);
const attempt = await attemptsApi.create({
  task_id: task.id,
  executor_profile_id: { executor: 'GEMINI', variant: null },
  base_branch: 'main',
  use_worktree: true,
});

// Follow-up on attempt
await attemptsApi.followUp(attempt.id, {
  prompt: 'Also add unit tests',
  variant: null,
  image_ids: [],
  retry_process_id: null,
  force_when_dirty: false,
  perform_git_reset: false,
});

// Git operations
const branchStatus = await attemptsApi.getBranchStatus(attempt.id);
await attemptsApi.merge(attempt.id);
await attemptsApi.push(attempt.id);

// Create PR
const prResult = await attemptsApi.createPR(attempt.id, {
  title: 'feat: Add authentication',
  body: '## Summary\nAdded JWT auth',
  target_branch: 'main',
});

// Process monitoring
const processes = await executionProcessesApi.getExecutionProcesses(attempt.id);
await executionProcessesApi.stopExecutionProcess(processes[0].id);

// Configuration
const systemInfo = await configApi.getConfig();
await configApi.saveConfig({ ...systemInfo.config, theme: 'DARK' });
```

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

### Get Details of a Specific Execution Process

Source: https://context7.com/automagik-dev/forge/llms.txt

Fetches detailed information for a single execution process, identified by its process ID.

```bash
curl http://localhost:8887/api/execution-processes/{process_id}
```

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

### Configure Cargo build settings

Source: https://github.com/automagik-dev/forge/blob/main/docs/RUNNER-OPTIMIZATION-REPORT.md

Set build jobs and linker flags in the Cargo configuration file.

```toml
[build]
jobs = 64  # Or appropriate number

[target.x86_64-unknown-linux-gnu]
linker = "clang"
rustflags = ["-C", "link-arg=-fuse-ld=lld"]
```

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

### Get Commit Information

Source: https://context7.com/automagik-dev/forge/llms.txt

Retrieves information about a specific commit using its SHA hash. The SHA is passed as a query parameter.

```bash
curl "http://localhost:8887/api/task-attempts/{attempt_id}/commit-info?sha=abc123"
```

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

### Get Draft for Follow-up

Source: https://context7.com/automagik-dev/forge/llms.txt

Retrieve a saved but not yet executed draft for a follow-up task. The type parameter should be set to 'follow_up'.

```bash
curl "http://localhost:8887/api/task-attempts/{attempt_id}/draft?type=follow_up"
```

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

### Verify Runner CPU Configuration

Source: https://github.com/automagik-dev/forge/blob/main/docs/RUNNER-OPTIMIZATION-REPORT.md

Commands to inspect CPU availability and container limits on the runner.

```bash
# Check available CPUs
nproc
cat /proc/cpuinfo | grep processor | wc -l

# If in Docker, check limits:
cat /sys/fs/cgroup/cpu/cpu.cfs_quota_us
cat /sys/fs/cgroup/cpu/cpu.cfs_period_us
```

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

### Build with CI Profile

Source: https://github.com/automagik-dev/forge/blob/main/docs/RUNNER-OPTIMIZATION-REPORT.md

Command to trigger a build using the custom CI profile.

```bash
cargo build --profile ci --bin forge-app
```

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

### Get Child Tasks of an Attempt using cURL

Source: https://context7.com/automagik-dev/forge/llms.txt

List any child tasks that were created as a result of a specific task attempt.

```bash
curl http://localhost:8887/api/task-attempts/{attempt_id}/children
```

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

### View Cargo configuration

Source: https://github.com/automagik-dev/forge/blob/main/docs/RUNNER-OPTIMIZATION-REPORT.md

Display the current Cargo configuration file.

```bash
cat ~/.cargo/config.toml
```

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

### Get Task Attempt by ID using cURL

Source: https://context7.com/automagik-dev/forge/llms.txt

Retrieve details for a specific task attempt using its unique identifier.

```bash
curl http://localhost:8887/api/task-attempts/{attempt_id}
```

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

### Browse Filesystem

Source: https://context7.com/automagik-dev/forge/llms.txt

List contents of directories within the local filesystem.

```bash
# List directory contents
curl "http://localhost:8887/api/filesystem/directory?path=/home/user/projects"
```

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

### Resolve Port Conflicts

Source: https://github.com/automagik-dev/forge/blob/main/DEVELOPER.md

Commands to identify and terminate processes occupying port 3000 or to start the development server on an alternative port.

```bash
# Find and kill process using port 3000
lsof -ti:3000 | xargs kill -9

# Or use a different port
PORT=3001 pnpm run dev
```

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

### List Git Repositories

Source: https://context7.com/automagik-dev/forge/llms.txt

Use this endpoint to list all Git repositories within a specified directory path.

```bash
curl "http://localhost:8887/api/filesystem/git-repos?path=/home/user/projects"
```

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

### Create Feature Branch

Source: https://github.com/automagik-dev/forge/blob/main/CONTRIBUTING.md

Start from the 'dev' branch, pull the latest changes, and then create a new branch for your feature or bug fix.

```bash
git checkout dev
git pull origin dev

# Create feature branch
git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description
```

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

### Select Appropriate Data Fetching Methods

Source: https://github.com/automagik-dev/forge/blob/main/frontend/docs/DATA_FETCHING.md

Use WebSockets for real-time updates and smart polling for slow-changing data to optimize network traffic.

```javascript
// GOOD - WebSocket for real-time, polling for slow-changing
const { tasks } = useProjectTasks(projectId);        // WebSocket
const { data } = useBranchStatus(attemptId);         // Smart polling
```

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

### Get Project-Specific Executor Profiles

Source: https://context7.com/automagik-dev/forge/llms.txt

Fetch executor profiles tailored for a specific project. This allows for project-level customization of AI behavior.

```bash
# Get project-specific profiles
curl http://localhost:8887/api/forge/projects/{project_id}/profiles
```

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

### Filesystem API

Source: https://context7.com/automagik-dev/forge/llms.txt

Browse the local filesystem for git repositories.

```APIDOC
## GET /api/filesystem/directory

### Description
Lists the contents of a specified directory on the local filesystem.

### Method
GET

### Endpoint
/api/filesystem/directory

### Parameters
#### Query Parameters
- **path** (string) - Required - The absolute path to the directory to list.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (array) - A list of file and directory names within the specified path.

### Response Example
```json
{
  "success": true,
  "data": [
    "file1.txt",
    "subdir",
    "image.png"
  ]
}
```
```

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

### Get Pending Approvals

Source: https://context7.com/automagik-dev/forge/llms.txt

Retrieve a list of all pending approval requests that require a response. This is useful for monitoring and managing AI agent actions.

```bash
# Get pending approvals
curl http://localhost:8887/api/approvals/pending
```

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

### Fix SQLx Compilation Errors

Source: https://github.com/automagik-dev/forge/blob/main/DEVELOPER.md

Commands to ensure the database is initialized and SQLx offline data is prepared for compilation.

```bash
# Ensure database is created and migrated
sqlx database create
sqlx migrate run

# Prepare SQLx offline data
cargo sqlx prepare --workspace
```

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

### Get MCP Server Configuration

Source: https://context7.com/automagik-dev/forge/llms.txt

Retrieve the MCP server configuration for a specific executor. This is useful for understanding how an executor is set up to interact with the MCP server.

```bash
# Get MCP server configuration for an executor
curl "http://localhost:8887/api/mcp-config?executor=CLAUDE_CODE"
```

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

### Open Task Attempt in Default Editor

Source: https://context7.com/automagik-dev/forge/llms.txt

Open the worktree for a specific task attempt in your default code editor. This streamlines the process of starting development on a task.

```bash
# Open attempt in default editor
curl -X POST http://localhost:8887/api/task-attempts/{attempt_id}/open-editor
```

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

### Build Production Package

Source: https://github.com/automagik-dev/forge/blob/main/README.md

Build the production-ready package for Automagik Forge. This command compiles and prepares the project for deployment.

```bash
make prod
```

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

### Save a Draft Follow-up

Source: https://context7.com/automagik-dev/forge/llms.txt

Save a draft of follow-up instructions. This endpoint requires the Content-Type to be application/json.

```bash
curl -X PUT "http://localhost:8887/api/task-attempts/{attempt_id}/draft?type=follow_up" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Draft: Add integration tests too",
    "variant": null,
    "image_ids": [],
    "version": 1
  }'
```