GitHub - apvcode/PromptShark: Stop burning tokens on infinite loops. An interactive proxy and debugger for AI agents with Time-Travel capabilities (built with Go & C++).

What is PromptShark?

PromptShark is a transparent local proxy that sits between your AI agent and the OpenAI API. It captures, logs, and visualizes every single request/response pair in a beautiful real-time dashboard — and automatically detects when your agent gets stuck in an infinite tool-calling loop.

One line to integrate. Zero code changes to your agent.
Just swap base_url → http://localhost:8080/v1

At a Glance

Feature Matrix

Installation

There are three ways to run PromptShark:

Option A: Docker (Recommended)

Option B: Pre-compiled Binaries

Download the latest .zip or .tar.gz for your OS (Windows, macOS, Linux) from the GitHub Releases page. Extract and run agent_supervisor (or agent_supervisor.exe).

Option C: Build from Source

1 · Build the C++ Core

mkdir -p build && cd build
cmake .. && make

2 · Run the Proxy

cd proxy
go build -o ../build/agent_supervisor .
../build/agent_supervisor

You will see:

    ____                       __  _____ __               __  
   / __ \_________  ____ ___  / /_/ ___// /_  ____ ______/ /__
  / /_/ / ___/ __ \/ __ '__ \/ __ \__ \/ __ \/ __ '/ ___/ //_/
 / ____/ /  / /_/ / / / / / / /_/ /__/ / / / / /_/ / /  / ,<   
/_/   /_/   \____/_/ /_/ /_/ .___/____/_/ /_/\__,_/_/  /_/|_|  
                          /_/                                   
  ──────────────────────────────────────────────────
  🦈 Version     : 0.1.0
  🌐 Dashboard   : http://localhost:8080
  📦 Database    : ../db/promptshark.db
  🎯 Target API  : https://api.openai.com
  🔗 Proxy URL   : http://localhost:8080/v1
  ──────────────────────────────────────────────────

  Point your OpenAI SDK base_url to the Proxy URL above.
  Press Ctrl+C to stop.

Open http://localhost:8080 — the dashboard is ready.

3 · Point your Agent

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="sk-..."  # forwarded transparently to OpenAI
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True
)

const OpenAI = require("openai");
const client = new OpenAI({
  baseURL: "http://localhost:8080/v1",
  apiKey: "sk-..."
});

const stream = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
  stream: true,
});

Loop Detector Config

Edit loop_config.txt in the project root:

# Consecutive identical calls before triggering alert
THRESHOLD=3

# Ignore arguments — match function name only
IGNORE_ARGS=false

⚙️ CLI Options

Environment variables PORT and DB_PATH are also supported (flags take priority).

The server handles graceful shutdown: press Ctrl+C and it will finish in-flight requests, close the database, and exit cleanly.

Tech Stack

Roadmap

• Configurable loop rules via YAML (regex patterns, token budgets)
• Ollama / Anthropic Claude API support
• Multi-agent message flow visualizer (network graph)

Что такое PromptShark?

PromptShark — это прозрачный локальный прокси, который встает между вашим ИИ-агентом и API OpenAI. Он перехватывает, логирует и визуализирует каждую пару запрос/ответ в красивом дашборде в реальном времени — и автоматически обнаруживает, если агент попал в бесконечный цикл вызова инструментов.

Одна строка для интеграции. Ноль изменений в коде агента.
Просто замените base_url → http://localhost:8080/v1

Обзор возможностей

Матрица возможностей

Установка

Есть три способа запустить PromptShark:

Вариант А: Docker (Рекомендуется)

Вариант Б: Готовые бинарники

Скачайте актуальный .zip или .tar.gz для вашей ОС (Windows, macOS, Linux) со страницы GitHub Releases. Распакуйте и запустите agent_supervisor (или agent_supervisor.exe).

Вариант В: Сборка из исходников

1 · Сборка C++ ядра

mkdir -p build && cd build
cmake .. && make

2 · Запуск прокси

cd proxy
go build -o ../build/agent_supervisor .
../build/agent_supervisor

Вы увидите:

    ____                       __  _____ __               __  
   / __ \_________  ____ ___  / /_/ ___// /_  ____ ______/ /__
  / /_/ / ___/ __ \/ __ '__ \/ __ \__ \/ __ \/ __ '/ ___/ //_/
 / ____/ /  / /_/ / / / / / / /_/ /__/ / / / / /_/ / /  / ,<   
/_/   /_/   \____/_/ /_/ /_/ .___/____/_/ /_/\__,_/_/  /_/|_|  
                          /_/                                   
  ──────────────────────────────────────────────────
  🦈 Version     : 0.1.0
  🌐 Dashboard   : http://localhost:8080
  📦 Database    : ../db/promptshark.db
  🎯 Target API  : https://api.openai.com
  🔗 Proxy URL   : http://localhost:8080/v1
  ──────────────────────────────────────────────────

  Point your OpenAI SDK base_url to the Proxy URL above.
  Press Ctrl+C to stop.

Откройте http://localhost:8080 — дашборд готов к работе.

3 · Подключите агента

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="sk-..."  # прозрачно перенаправляется в OpenAI
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Привет!"}],
    stream=True
)

const OpenAI = require("openai");
const client = new OpenAI({
  baseURL: "http://localhost:8080/v1",
  apiKey: "sk-..."
});

const stream = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Привет!" }],
  stream: true,
});

Настройка детектора циклов

Отредактируйте loop_config.txt в корне проекта:

# Количество идентичных вызовов подряд до срабатывания тревоги
THRESHOLD=3

# Игнорировать аргументы — сравнивать только имя функции
IGNORE_ARGS=false

⚙️ Параметры CLI

Также поддерживаются переменные окружения PORT и DB_PATH (флаги имеют приоритет).

Сервер поддерживает Graceful Shutdown: нажмите Ctrl+C, и он корректно завершит текущие запросы, закроет базу данных и выведет ✅ Goodbye!.

Технологический стек

Дорожная карта

• Конфигурация правил детектора через YAML (regex паттерны, бюджеты токенов)
• Поддержка Ollama / Anthropic Claude API
• Визуализатор потоков мультиагентных систем (граф сети)

_{[MIT License](LICENSE) — use it, fork it, ship it.}