agentpit-io/hunter-community

What is HunterCode?

HunterCode is a self-hosted AI assistant for stock market research. You run it on your own computer or server, give it an API key for a large language model (LLM), and it can pull live market data, fetch news, analyze individual stocks, forecast price trends, and manage your watchlist and holdings. All your conversations and data stay in a local database on your machine — nothing is sent to a third-party service.

It's aimed at individual investors, private-fund researchers, and small quant teams who want control over their data and want to plug in their own data sources or analysis methods.

What does it actually do?

Think of it as a research assistant, not a trading bot. It does not connect to brokerages, doesn't make trades, and doesn't guarantee predictions. Instead, it organizes public data, analysis methodologies, and an LLM into a coherent research workflow.

Key capabilities:

• Market data: Real-time quotes, candlestick charts, financial reports, news, top shareholders, northbound/southbound capital flows for A-shares (China), Hong Kong, and US stocks.
• AI analysis: A "deep analysis" agent that produces multi-dimensional research reports (fundamentals, technicals, capital flows), an "investor panel" that simulates 9 different investing schools voting on a stock, a market-wide stock screener, and a price-forecast module (Kronos, based on a Tsinghua time-series model).
• Conversation: Chat with rich cards showing quotes, news, and predictions.
• SKILL system: You can write analysis methodologies as Markdown files (using the Anthropic Agent Skills standard format) and install skills from GitHub with one click. Six skills ship built-in, including a scam-detection skill that scans for pump-and-dump signals.
• Paper trading: A simulated trading ledger that runs a full order lifecycle (quote snapshot → risk check → matching → bookkeeping → report) without touching real money. It's deliberately isolated — the code refuses real-trade parameters, and the database role literally lacks permission to modify or delete ledger entries.
• Extensibility: Connect your own MCP (Model Context Protocol) tools, any OpenAI-compatible LLM gateway, or your own data sources.

How does it work under the hood?

HunterCode is a multi-service Docker Compose application:

• Web frontend (Next.js 15) — the browser interface
• API backend (FastAPI) — authentication, data access, model calls, skill loading
• Conversation engine (a customized OpenCode) — handles the LLM tool-calling loop
• Postgres + Redis — storage and caching
• llm-shim — a small proxy that cleans up tool schemas and strips "thinking" text that some reasoning models leak into responses
• Temporal — a workflow engine that drives the paper-trading schedule (only when you enable the optional fin profile)

You can bring your own LLM key (DeepSeek, Claude, Qwen, Gemini, etc.) or use HunterCode's built-in quota (a free key with a daily token allowance). Data can come from free open-source sources (AKShare, yfinance), your own MCP servers, or the project's platform data pipeline.

Notable design details

• Setup wizard: The first time you open it, a 5-step wizard checks that all six services are healthy, lets you pick a model, tests connectivity and tool-calling live (it won't let you save a config that fails), and configures the data source.
• Security: If the instance is exposed to the public internet, you can set a setup token so random visitors can't configure the LLM. JWT authentication with argon2id password hashing.
• Audit trail: A complete audit log (AUDIT.jsonl) records activity.
• Self-evolution (optional): A "personal deployment" mode lets the system learn from its own post-trade reviews and propose strategy changes — but changes go through shadow validation and require human confirmation before taking effect. Real trading is hard-disabled.

Bottom line

HunterCode is a substantial, genuinely functional open-source project: a self-hosted AI agent system for financial research, with real LLM tool-calling, MCP integration, a skill system, forecasting, and a carefully isolated paper-trading simulation. It's not a wrapper demo or a link collection — it's a deployable product with real engineering behind it.