Gold Price Notifier

Stop staring at charts like a peasant. Let the machines do the heavy lifting.

GoldStrike is a high-performance, asynchronous Kotlin bot that relentlessly tracks the price of Gold (XAU) and strikes your Telegram DMs the exact second your target price is breached. Now also available as a Gemini CLI Extension!

🔥 Why It's Badass

• Relentless Monitoring: Powered by Kotlin 2.3.0 Coroutines to track prices asynchronously without blocking the main thread.
• Modern Networking: Engineered with Ktor 3.1.0 CIO client, precise HTTP timeouts, and graceful JVM shutdowns.
• Zero-Bullshit Alerts: Only alerts you when the price crosses your aggressively defined thresholds. No spam, no false alarms.
• Gemini CLI Extension: Install it directly into your Gemini CLI for instant gold price queries during your workflow.
• MCP Integration: Acts as a Model Context Protocol (MCP) server, allowing AI agents to query real-time gold prices directly.
• Battle-Tested: High-precision unit testing using MockK ensuring every strike is calculated and verified.

🚀 Instant Deployment (Gemini CLI)

The easiest way to use GoldStrike is as a Gemini CLI extension.

# 1. Install the extension
gemini extensions install https://github.com/goldyonwar/gold-price-notifier

# 2. Ask Gemini for the gold price
gemini "What is the current gold price?"

Requires Java 17+ installed locally.

⚙️ Configuration (The Arsenal)

If you are running the Telegram Watcher Bot, you need to arm it with environment variables. Create a .env file in the root directory:

Intel Gathering (Pre-requisites):

• Bot Token: Talk to @BotFather on Telegram to create your bot and get the token.
• Chat ID: Forward a message from your target chat to @userinfobot or use https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates to find your precise Chat ID.

# Your Telegram Bot Token from @BotFather
TELEGRAM_BOT_TOKEN=your_bot_token_here

# Your personal Telegram Chat ID
TELEGRAM_CHAT_ID=your_chat_id_here

# The Strike Zones (Alert Triggers)
TARGET_HIGH_PRICE=5100.0
TARGET_LOW_PRICE=5080.0

# Polling frequency in milliseconds (e.g., 60000 = 1 minute)
CHECK_INTERVAL=60000

🛠 Mode 1: The Watcher Bot (Standard)

This is the default mode that monitors prices and sends Telegram alerts.

Option A: Docker (Recommended)

# 1. Build the image
docker build -t gold-watcher-bot .

# 2. Run the container
docker run -d --name my_gold_bot --env-file .env gold-watcher-bot

Option B: Gradle

./gradlew run

---

🛠 Mode 2: MCP Server (AI Agent Integration)

Run GoldStrike as a standalone MCP server to expose gold price tracking to your AI tools (Claude, etc.).

# Run with the --mcp flag
./gradlew run --args="--mcp"

Building the Artifact

To use GoldStrike as a standalone JAR (required for some MCP clients), build the fat JAR first:

./gradlew shadowJar

This produces the artifact at build/libs/gold-price-notifier-all.jar.

Exposed Tools:

• get_gold_price: Fetches the real-time gold price in USD (XAU).

MCP Client Configuration (e.g., Claude Desktop)

{
  "mcpServers": {
    "gold-watcher": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/gold-price-notifier-all.jar",
        "--mcp"
      ]
    }
  }
}

🧪 Testing (Verifying the Strike)

Run the automated test suite to ensure the tracker and MCP logic are working as expected:

./gradlew test

🛡️ License

This project is licensed under the MIT License - see the LICENSE file for details.