https://github.com/geostorm-ai/geostorm
Monitor how AI systems perceive and recommend your software across GPT, Claude, Gemini, and more.
https://github.com/geostorm-ai/geostorm
ai-monitoring ai-perception astro brand-monitoring developer-tools docker fastapi llm mcp openrouter opensource python self-hosted seo
Last synced: 4 months ago
JSON representation
Monitor how AI systems perceive and recommend your software across GPT, Claude, Gemini, and more.
- Host: GitHub
- URL: https://github.com/geostorm-ai/geostorm
- Owner: geostorm-ai
- License: mit
- Created: 2026-02-24T08:32:18.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-01T15:06:36.000Z (4 months ago)
- Last Synced: 2026-03-01T15:22:11.660Z (4 months ago)
- Topics: ai-monitoring, ai-perception, astro, brand-monitoring, developer-tools, docker, fastapi, llm, mcp, openrouter, opensource, python, self-hosted, seo
- Language: Python
- Homepage: http://geostorm.ai/
- Size: 1.1 MB
- Stars: 8
- Watchers: 0
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Support: SUPPORT.md
Awesome Lists containing this project
README
# GeoStorm
### AI Perception Monitoring for Software
**Monitor how AI systems perceive and recommend your software across GPT, Claude, Gemini, and more.**
---
**Developers increasingly discover software through AI** -- GPT, Claude, Gemini, Perplexity, and others. When someone asks "what's the best library for X?", the AI's answer shapes adoption. But you have no idea what these models are saying about your project.
**GeoStorm fixes this.** It monitors multiple AI models on a schedule, tracks how they perceive and recommend your software, and alerts you when things change -- a new competitor appears, your ranking drops, or a model stops mentioning you entirely.
One container. One command. Full visibility into your AI presence.
---
## Quick Start
```bash
docker run -d -p 8080:8080 -v geostorm-data:/app/data --name geostorm ghcr.io/geostorm-ai/geostorm
```
Open [http://localhost:8080](http://localhost:8080) -- the demo loads immediately.
**That's it.** No git clone, no build step, no API keys, no database setup. A demo project with 90 days of synthetic monitoring data is ready to explore.
Requirements
- [Docker](https://docs.docker.com/get-docker/)
- An [OpenRouter](https://openrouter.ai/) API key (for querying AI models)
---
## What You'll See
The demo project ships with realistic sample data so you can explore every feature immediately:
| Feature | Description |
|---------|-------------|
| **Signal Panel** | A unified feed of alerts, ranked by severity and recency |
| **Alerts Feed** | Critical and warning signals with full context on what changed |
| **Perception Chart** | Track your recommendation share and positioning across models over time |
The demo data covers multiple AI models, competitor tracking, and trend analysis so you can see exactly how GeoStorm works before connecting your own projects.
---
## Next Steps
To start monitoring your own software:
**1. Get an API key** at [OpenRouter](https://openrouter.ai/) -- one key gives you access to multiple AI models.
**2. Add your OpenRouter API key in the GeoStorm settings page:**
**3. Create a project** in the UI and GeoStorm starts monitoring on a schedule.
---
## Alert Types
GeoStorm detects and alerts on these signals:
| Alert | Severity | Description |
|-------|----------|-------------|
| `competitor_emergence` | Critical | A new competitor has appeared in AI recommendations for your category |
| `disappearance` | Critical | Your software has stopped being mentioned by one or more AI models |
| `recommendation_share_drop` | Warning | Your share of AI recommendations has declined significantly |
| `position_degradation` | Warning | Your software is being listed lower in AI recommendation rankings |
| `model_divergence` | Warning | Different AI models are giving substantially different recommendations about your software |
---
## Architecture
GeoStorm runs as a single Docker container with no external dependencies:
| Component | Technology |
|-----------|-----------|
| **Backend** | FastAPI serving the REST API and running scheduled monitoring jobs via APScheduler (in-process) |
| **Frontend** | Astro with React islands, styled with TailwindCSS, charts powered by Recharts |
| **Database** | SQLite, stored in a mounted volume (`./data/`) |
| **Scheduling** | APScheduler runs inside the FastAPI process -- no separate worker, no Redis, no message queue |
The entire stack is self-contained. One container, one port, one volume mount.
---
## Configuration
GeoStorm works out of the box with zero configuration. You can optionally configure notification channels via environment variables in a `.env` file:
| Channel | Description |
|---------|-------------|
| **Slack** | Set a webhook URL to receive alerts in a Slack channel |
| **Email** | Configure SMTP settings for email notifications |
| **Custom Webhook** | Point alerts at any HTTP endpoint |
All notification channels are optional. GeoStorm always displays alerts in the UI regardless of notification configuration.
---
## Contributing
GeoStorm is open-source and we welcome contributions.
### Ways to contribute:
- **Bug Report:** Found an issue? [Create a bug report](https://github.com/geostorm-ai/geostorm/issues/new)
- **Feature Request:** Have an idea? [Submit a feature request](https://github.com/geostorm-ai/geostorm/issues/new)
- **Pull Request:** PRs are welcome -- fork, branch, and open a PR
### Development Setup
```bash
# Run locally with a local build
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
# Backend checks
uv sync --frozen --all-extras
uv run ruff check .
uv run mypy src/ --strict
uv run pytest tests/ -v
# Frontend checks
cd web && pnpm install --frozen-lockfile
pnpm astro check
pnpm tsc --noEmit
```
#### Structured Logging (Optional)
GeoStorm uses [Logfire](https://logfire.pydantic.dev/) for structured logging. Console logs work out of the box with no extra setup. To also send telemetry to Logfire cloud during development, set `LOGFIRE_TOKEN` in your environment.
---
## FAQ
Why would I want this?
More and more developers discover tools by asking AI -- "what's the best library for X?" If an AI model stops recommending your project, or starts favoring a competitor, you'd never know unless you manually checked every model. GeoStorm automates that, runs on a schedule, and alerts you when something changes.
Why OpenRouter?
OpenRouter gives you access to GPT, Claude, Gemini, Llama, and dozens of other models through a single API key. Instead of managing separate keys for OpenAI, Anthropic, and Google, you sign up once and GeoStorm can query all of them. You can also use direct provider keys (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`) if you prefer.
Is there a hosted version?
Not yet. GeoStorm is self-hosted only for now. The Docker container is designed to be easy to run anywhere -- your laptop, a VPS, or a cloud VM. A hosted version is on the roadmap.
Why SQLite?
GeoStorm is a single-user monitoring tool, not a multi-tenant SaaS. SQLite keeps things simple -- no database server to run, no connection strings to configure, no separate container. Your data lives in a single file on a mounted volume. For the query patterns GeoStorm uses, SQLite is more than fast enough.
How much does it cost to run?
GeoStorm itself is free. The only cost is the AI API usage through OpenRouter. A typical monitoring run queries 3 models with a few prompts each -- roughly $0.01-0.05 per run depending on the models you choose. Running daily, that's about $1-2/month.
Couldn't I do this with OpenClaw?
You could wire up an OpenClaw agent with a cron job to query AI models daily and store the results somewhere. But then you're building GeoStorm from scratch -- prompt engineering for consistent structured responses, parsing and normalizing across models, calculating recommendation share and position rankings, detecting changes over time, generating alerts, and building a UI to make sense of it all.
GeoStorm does all of that out of the box. It's also cheaper and more predictable -- GeoStorm runs deterministic code on a fixed schedule, so you know exactly what queries run and what they cost. An AI agent deciding what to do each run can drift, retry unpredictably, or burn tokens on reasoning overhead. One container, no agent framework required.
---
### Ready to see what AI thinks about your software?
```bash
docker run -d -p 8080:8080 -v geostorm-data:/app/data --name geostorm ghcr.io/geostorm-ai/geostorm
```
---
**License:** MIT | **Python:** 3.11+ | **Homepage:** [github.com/geostorm-ai/geostorm](https://github.com/geostorm-ai/geostorm)