### Quick start: setup and run with debug

Source: https://github.com/zaxx-q/aipromptbridge/blob/main/docs/LINUX.md

Sets up a virtual environment, installs dependencies, and runs the app with debug logging. Use from the project root.

```bash
cd /path/to/AIPromptBridge
uv venv && source .venv/bin/activate   # if needed
uv pip install -r requirements.txt
uv run main.py --debug
```

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

### Example niri keybindings for triggers

Source: https://github.com/zaxx-q/aipromptbridge/blob/main/docs/LINUX.md

KDL configuration for niri window manager binds. Shows compiled PATH install and source checkout variants. The textedit-clipboard bind is safe for terminal apps.

```kdl
binds {
    // Compiled PATH install:
    Mod+Shift+T { spawn-sh "AIPromptBridge --trigger textedit"; }
    // Explicitly process regular clipboard text; safe for terminal apps.
    Mod+Shift+C { spawn-sh "AIPromptBridge --trigger textedit-clipboard"; }
    Mod+Shift+S { spawn-sh "AIPromptBridge --trigger snip"; }
    Mod+Shift+A { spawn-sh "AIPromptBridge --trigger audio"; }
    // Source: spawn-sh "python3 /path/to/AIPromptBridge/scripts/aipb_trigger.py snip";
}
```

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

### Optional PATH install with symlink

Source: https://github.com/zaxx-q/aipromptbridge/blob/main/docs/LINUX.md

Symlink only the outer launcher to ~/.local/bin while keeping the full tree together. Do not copy only the launcher without bin/ beside it.

```bash
# e.g. extract/move package to ~/.local/AIPromptBridge/
ln -sf ~/.local/AIPromptBridge/AIPromptBridge ~/.local/bin/AIPromptBridge
AIPromptBridge --debug
```

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

### Job Request JSON Example

Source: https://github.com/zaxx-q/aipromptbridge/blob/main/docs/FILE_PROCESSOR_API.md

Example of a complete job request JSON object. It includes required fields (input_path, prompt_name, profile_name, output) and optional settings (recursive, file_types, delay, use_batch, include_filename, custom_instructions, per_file_instructions, large_file_mode). Paths expand ~ and environment variables. use_batch and files_api require a Google profile.

```json
{
  "input_path": "/recordings/interview.m4a",
  "recursive": false,
  "file_types": ["audio"],
  "prompt_name": "Transcribe (Native Verbatim)",
  "profile_name": "Transcription",
  "output": {
    "mode": "individual",
    "path": "/recordings/output",
    "naming": "{filename}_transcript",
    "extension": ".md",
    "overwrite": false
  },
  "delay": 1.0,
  "use_batch": false,
  "include_filename": true,
  "custom_instructions": "Speakers are Alice and Bob.",
  "per_file_instructions": { "/recordings/other.m4a": "This file is Spanish." },
  "large_file_mode": "files_api"
}
```

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

### Development dependencies for aipromptbridge

Source: https://github.com/zaxx-q/aipromptbridge/blob/main/requirements-dev.txt

Install with `uv pip install -r requirements-dev.txt`. Includes base requirements, pytest for testing, and ruff for linting and formatting.

```text
-r requirements.txt

# Testing
pytest>=8.0

# Linting & Formatting
ruff>=0.8.0
```

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

### Trigger commands for compiled and source installs

Source: https://github.com/zaxx-q/aipromptbridge/blob/main/docs/LINUX.md

Shows various ways to trigger tools via IPC. The compiled install uses the outer launcher, while source checkout uses the stdlib-only script. The last command is slower but works after lazy imports.

```bash
# Compiled install (outer launcher → aipb_trigger.py + system python3):
AIPromptBridge --trigger textedit

# Source checkout (stdlib only — best for binds):
python3 scripts/aipb_trigger.py snip
python -m src.platform.ipc audio

# Also works after lazy imports, but slower than the scripts above:
uv run main.py --trigger chat

# Triggers: snip, textedit, textedit-clipboard, audio, tts, chat, browser, settings, prompts
```

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

### Optional PATH install via symlink

Source: https://github.com/zaxx-q/aipromptbridge/blob/main/scripts/README-linux.txt

Create a directory for the package, move or extract the full package there, and symlink only the outer launcher into ~/.local/bin. Keep bin/ next to the launcher. Then run AIPromptBridge --debug.

```bash
mkdir -p ~/.local/AIPromptBridge
# move/extract the full package into ~/.local/AIPromptBridge/
ln -sf ~/.local/AIPromptBridge/AIPromptBridge ~/.local/bin/AIPromptBridge
# Then: AIPromptBridge --debug
```

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

### Use theme system in Python

Source: https://github.com/zaxx-q/aipromptbridge/blob/main/docs/ARCHITECTURE.md

Shows how to get current theme colors, retrieve a specific theme variant, and check system dark mode using the ThemeRegistry.

```python
from src.gui.themes import get_colors, ThemeRegistry

# Get current theme colors
colors = get_colors()
print(colors.bg, colors.fg, colors.accent)

# Get specific theme
dark_nord = ThemeRegistry.get_theme("nord", "dark")

# Check system dark mode
is_dark = ThemeRegistry.is_dark_mode()
```

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

### Clone and run AIPromptBridge from source

Source: https://github.com/zaxx-q/aipromptbridge/blob/main/README.md

Commands to clone the repository, install dependencies with uv or pip, and run the application in debug mode. Python 3.13.x is recommended. On Linux Wayland, use the --trigger flag from compositor binds.

```bash
git clone https://github.com/zaxx-q/AIPromptBridge.git
cd AIPromptBridge
# Python 3.13.x recommended (see .python-version)
uv pip install -r requirements.txt   # or: pip install -r requirements.txt
uv run main.py --debug               # or: python main.py
```

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

### Example config.ini for non-connection settings

Source: https://github.com/zaxx-q/aipromptbridge/blob/main/docs/ARCHITECTURE.md

Shows a sample config.ini file that holds only non-connection settings. Connection settings are managed via Connection Profiles (profiles.json), and API keys are stored in keys.json. Includes comments and settings for max_retries and retry_delay.

```ini
[config]
# Connection settings (provider, model, streaming, thinking) are
# managed via Connection Profiles — see profiles.json.
# config.ini only holds non-connection settings:

max_retries = 3
retry_delay = 5

# [google] — API keys now in keys.json (KeyStore)
# [ai_params] — Now in Connection Profiles (profiles.json)

```

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

### niri autostart: spawn-at-startup with uv run main.py

Source: https://github.com/zaxx-q/aipromptbridge/blob/main/docs/LINUX.md

For pure niri sessions that do not process XDG autostart, add this line to the niri configuration to launch the app at startup. Adjust the path to your project directory.

```kdl
spawn-at-startup "sh" "-c" "cd /path/to/AIPromptBridge && uv run main.py"
```

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

### Recreate venv on distro Python 3.13 with tkinter (Fedora)

Source: https://github.com/zaxx-q/aipromptbridge/blob/main/docs/LINUX.md

Install python3.13 and python3.13-tkinter, then recreate the venv using /usr/bin/python3.13 and install requirements. The final command verifies that many font families are available, not just 'fixed'.

```bash
sudo dnf install python3.13 python3.13-tkinter
cd /path/to/AIPromptBridge
uv venv --python /usr/bin/python3.13
uv pip install -r requirements.txt

# Expect many families and a real sans face, not only "fixed":
uv run python -c "import tkinter as tk; r=tk.Tk(); r.withdraw(); print(len(r.tk.call('font','families')), r.tk.call('font','actual','TkDefaultFont')); r.destroy()"
```

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

### Linux shell launcher script (scripts/linux_launcher.sh)

Source: https://github.com/zaxx-q/aipromptbridge/blob/main/docs/BUILD_PROCESS.md

The outer launcher for Linux, installed as AIPromptBridge at the package root. It resolves symlinks to find the install root, then either execs aipb_trigger.py for the --trigger fast path or wraps the internal binary in a tmux session. --launched-mode=console is required to ensure CWD/config resolve to the deploy root.

```bash
_LAUNCHER="$(readlink -f "${BASH_SOURCE[0]}")"   # resolve PATH symlinks
ROOT="$(cd "$(dirname "${_LAUNCHER}")" && pwd)"
# --trigger → system python3 + aipb_trigger.py (stdlib IPC, ~tens of ms)
# else     → conditional tmux wrapper (tmux new-session [-d] -A -s aipromptbridge …)
#            wrapping "$ROOT/bin/AIPromptBridge_Internal" --launched-mode=console "$@"

```

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

### Open Settings and Prompt Editor Windows from Any Thread

Source: https://github.com/zaxx-q/aipromptbridge/blob/main/docs/ARCHITECTURE.md

Shows how to import and call the window-opening functions. Both windows are accessible from the system tray menu. The ConnectionProfileManager can be opened independently.

```python
# From any thread
from src.gui.settings_window import show_settings_window
from src.gui.windows.prompt_editor import show_prompt_editor

show_settings_window()  # Opens Settings window
show_prompt_editor()  # Opens Prompt Editor

# ConnectionProfileManager can be opened independently
from src.gui.core import show_connection_manager

show_connection_manager()
```

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

### GET /file-processor/jobs/<job_id>

Source: https://github.com/zaxx-q/aipromptbridge/blob/main/docs/FILE_PROCESSOR_API.md

Retrieves the details of a retained failed job, including errors, metadata, checkpoint, and any outputs already written. This is used to inspect or resume a previously failed job.

```APIDOC
## GET /file-processor/jobs/<job_id>

### Description
Retrieves a retained failed job, including its errors, metadata, checkpoint, and any outputs already written.

### Method
GET

### Endpoint
/file-processor/jobs/<job_id>

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The unique identifier of the failed job.

### Response
#### Success Response (200)
- **job_id** (string) - The job identifier.
- **status** (string) - Job status, typically "failed".
- **errors** (array) - List of error messages.
- **metadata** (object) - Job metadata.
- **checkpoint** (object) - Checkpoint information for resuming.
- **outputs** (object) - Any outputs already written.

#### Response Example
{
  "job_id": "abc123",
  "status": "failed",
  "errors": ["Error message"],
  "metadata": {},
  "checkpoint": {},
  "outputs": {}
}
```

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

### GET /file-processor/capabilities

Source: https://github.com/zaxx-q/aipromptbridge/blob/main/docs/FILE_PROCESSOR_API.md

Retrieves the capability information for the File Processor API, including prompt names, enabled profile names, supported file/audio options, and busy status. This endpoint does not return any profile or key secrets.

```APIDOC
## GET /file-processor/capabilities

### Description
Retrieves the capability information for the File Processor API, including prompt names, enabled profile names, supported file/audio options, and busy status. This endpoint does not return any profile or key secrets.

### Method
GET

### Endpoint
/file-processor/capabilities

### Response
#### Success Response (200)
- **prompt_names** (array of string) - List of available prompt names.
- **profile_names** (array of string) - List of enabled profile names.
- **file_options** (array) - Supported file options.
- **audio_options** (array) - Supported audio options.
- **busy** (boolean) - Indicates whether a job is currently running.

#### Response Example
{
  "prompt_names": ["summarize", "extract"],
  "profile_names": ["default", "fast"],
  "file_options": ["pdf", "txt"],
  "audio_options": ["mp3", "wav"],
  "busy": false
}
```