GeoCatalyst

GeoCatalyst is a local-first Go terminal for tracking geopolitical catalysts against prediction markets.

The design target is not a generic newsreader. The terminal is meant to answer one operator question quickly: which upcoming official events are most likely to move which markets, and why.

What It Is

GeoCatalyst is a local-first operator terminal:

• live Polymarket markets and focused WS orderbooks
• official-calendar and feed-driven catalyst timelines
• WorldOSINT and RSS intake
• local PrediHermes / MiroFish simulation workbench
• both an interactive TUI and a JSON-first headless CLI

The design target is not a generic newsreader. The terminal is meant to answer one operator question quickly: which events can still move which markets before deadline, and why.

Principles

• local-first runtime
• Go owns orchestration, storage, normalization, and TUI rendering
• the local LLM is optional and bounded, not the system backbone
• no regex-driven intelligence layer
• official calendars, feeds, and market APIs should be parsed through typed adapters
• GPL-3.0-or-later for a copyleft core

GPL and hidden source do not coexist cleanly. If you need private operator logic later, keep it in external data packs, config, or services rather than trying to hide code inside the GPL repository.

Install

Local repo install:

cd /path/to/geocatalyst
npm install -g .

Published package install:

npm install -g geocatalyst

That one command already runs the portable setup hook:

• builds the Go binary into ~/.local/share/geocatalyst/bin/geocatalyst
• writes ~/.config/geocatalyst/config.json
• detects an existing local PrediHermes stack
• prepares companion dependencies when that stack is present on disk

The global wrapper exposes:

• geocatalyst
• predihermes-geocatalyst

Manual setup is still available as a repair or refresh path:

geocatalyst install
geocatalyst doctor

Quick Start

geocatalyst

Useful local targets:

make fmt
make test
make build
make install
make doctor

Run a live source health check:

geocatalyst -health -mode live

Run the headless JSON surface:

geocatalyst market desk --selector "US x Iran ceasefire by April 15?" --mode live
geocatalyst market timeline --selector "US x Iran ceasefire by April 15?" --mode live
geocatalyst market graph --selector "US x Iran ceasefire by April 15?" --mode live
geocatalyst feed desk --selector "US x Iran ceasefire by April 15?" --mode live

Companion stack helpers:

geocatalyst stack up
geocatalyst stack status
geocatalyst stack down

Local LLM Defaults

The repo assumes a small local model on a 16 GB Mac mini:

• OpenAI-compatible endpoint on http://127.0.0.1:11434/v1
• default model family: qwen2.5
• strict budgets for prompt size, response size, and timeout

The terminal should remain usable when the model is disabled.

Literate Layout

Read the project in this order:

1. docs/literate/00-vision.md
2. docs/literate/10-system.md
3. docs/literate/20-domain.md
4. docs/literate/30-local-llm.md
5. docs/literate/40-tui.md
6. docs/literate/90-headless-cli.md
7. docs/literate/100-packaging.md

Then read the package-level doc.go files under internal/.

Repository Map

• cmd/geocatalyst/: CLI entrypoint
• config/example/: local config template
• docs/literate/: narrative architecture
• internal/app/: bootstrap and lifecycle
• internal/config/: JSON config and defaults
• internal/domain/: canonical types
• internal/fixtures/: local demo data
• internal/pipeline/: live snapshot orchestration
• internal/linker/: event-to-market scoring helpers
• internal/llm/: local analyst contract
• internal/source/: source interfaces and adapters
• internal/store/: snapshot persistence boundary
• internal/tui/: Bubble Tea dashboard
• internal/version/: build metadata
• npm/: global wrapper, installer, and stack orchestration
• SKILL.md: condensed operator and automation guide

Packaging Rule

The Go binary is the product runtime. The npm layer is only a global installer, launcher, and stack wrapper so the tool feels like an app instead of a repo.