🐙 Smart Octopus · 聪明的章鱼

The open-source, self-hosted AI equity desk — your local Claude CLI is the brain, your repo is the body.

Eight arms across every market · 八臂触达，洞察全市场

English · 简体中文

🚀 Quick Start · 🐙 Why Smart Octopus · 📸 Product Tour · 🧠 The Claude Harness

---

🧠 Your local claude CLI is the analysis engine. Type a ticker and the agent runs a multi-lens skill, refutes its own thesis, and writes a research report. No model API keys to manage — it runs on your Claude subscription.

⚡ Self-hosted & private. Data never leaves your machine. Schedule the astock-* routines on your own cron, or fall back to the legacy GitHub Actions pipeline for headless / CI environments.

What is Smart Octopus?

Smart Octopus is a self-hosted research desk for the stock market that you run from your own repo — no SaaS, no per-seat pricing, no data leaving your machine. It pulls multi-market data and news, hands the hard reasoning to an LLM agent, and ships a structured decision dashboard (score, trend, entry/exit, risk, catalysts, an action checklist) to WeCom, Feishu, Telegram, Discord, Slack, or email.

What makes it different from the dozens of "ChatGPT-reads-a-stock" scripts:

• 🧠 Claude CLI is the brain. The web app drives your local claude CLI as a real agent harness — skills, strategy YAML, and deterministic tools are the tentacles. Type a ticker; the agent runs the multi-lens astock-analyze skill and produces a report.
• ⚡ No model keys, self-hosted. The web workstation and scheduled astock-* routines run on your local Claude CLI — no per-call API bill, data stays local. A legacy LLM-provider pipeline (GitHub Actions / Docker / CI) remains for headless environments without an interactive claude login.
• 🌏 Five markets, six channels. A-shares, HK, US, plus JP/KR — quotes, K-lines, technicals, fund flow, chips, news, fundamentals — delivered to six push channels out of the box.
• 🔍 InkSift 墨筛 screening engine. A built-in catalyst / price-action screener sifts the whole market for candidates, then the agent enriches the top names with quotes, fundamentals, and news.

The default brain is your local Claude CLI — install Claude Code and log in (claude) once, and no model API keys are needed.

Option 1 — Local Claude workstation (recommended · no model keys)

# Prereq: install the Claude CLI (Claude Code) and run `claude` to log in.
git clone https://github.com/CortexReach/smart_octopus.git && cd smart_octopus
pip install -r requirements.txt
cp .env.example .env             # data-source keys only — no model keys required

python main.py --serve-only      # open http://127.0.0.1:8000, then type a ticker

The Home / Ask / Portfolio / AI-signals pages drive your local claude as the brain through the astock-* skills — manual analysis, task progress, history, Markdown reports, backtest, paper portfolio, strategy editor, light / dark themes. The only optional key here is TICKFLOW_API_KEY (A-share index & market-breadth data). Details → harness guide · A-share usage.

Option 2 — Scheduled Claude routines (your own cron / launchd)

scripts/astock/run_routine.sh premarket   # or: intraday | review | screen | analyze

Trading-day-gated; runs the matching astock-* skill headless via claude -p and logs to reports/astock/_cron/. Wire it to cron / launchd on a machine where claude is logged in — this is the Claude-native replacement for a daily scheduler.

Option 3 — Legacy LLM-provider pipeline (headless / CI · GitHub Actions)

For environments without an interactive claude login (GitHub Actions, Docker, plain CI), the original provider-based daily pipeline still ships. It needs one model API key + a push channel instead of the Claude CLI:

python main.py --stocks 600519,hk00700,AAPL   # provider pipeline, needs a model key in .env

Fork → add Secrets (one model key such as GEMINI_API_KEY / AIHUBMIX_KEY / any OPENAI_API_KEY-compatible service, one push channel, and STOCK_LIST) → enable Actions. Runs every trading day at 18:00 Beijing (cron: 0 10 * * 1-5). All model/provider and channel keys are documented inline in .env.example.

🐙 Why Smart Octopus

	🐙 Smart Octopus	Closed AI-stock SaaS	A plain "LLM reads a stock" script
Open-source (MIT)	✅	❌	usually ✅
Self-hosted, data stays local	✅	❌	✅
Zero-cost via GitHub Actions	✅	❌	❌
Local Claude-CLI agent harness	✅	❌	❌
No model API keys (Claude subscription)	✅	❌	❌
5 markets (A / HK / US / JP / KR)	✅	partial	partial
6 push channels built-in	✅	partial	❌
Built-in market screener	✅ InkSift	partial	❌
Editable strategy YAML (16 built-in)	✅	❌	❌
Web + desktop workstation	✅	varies	❌

📸 Product Tour

Home · Claude harness — type a ticker; the local claude brain runs a multi-lens analysis.	InkSift 墨筛 · Screening — catalyst / price-action strategies sift the whole market.
Strategies — 16 editable, declarative strategies the agent reads (built-in + custom YAML).	Copilot — paper portfolio, floating P&L, and prediction-accuracy calibration.

🌗 Prefer a light theme? There's a 宣纸 (rice-paper) mode too.

🧠 The Claude Harness

Smart Octopus treats your local Claude CLI as the analysis engine and the repo as its harness:

• Skills (.claude/skills/astock-*) — pre-open watchlist, single-stock deep dive, intraday watch, post-close review, market screen, and strategy learning.
• Strategy YAML (strategies/*.yaml) — 16 declarative, editable strategies (MA cross, Chan theory, Elliott wave, trend, sentiment cycle, event-driven, growth, re-rating, hotspot, …) the agent reads at analysis time.
• Tools (scripts/astock/*) — quotes, market breadth, news, paper-trading, journaling, push — each a deterministic JSON-in / JSON-out command the agent calls.

The web pages (Home / Ask / Screening / Copilot) are thin front-ends over this harness, so the same brain answers from the CLI, the API, the web, and scheduled agents. Details → Claude harness guide.

🌏 Markets & Channels

	Coverage
Markets	🇨🇳 A-shares · 🇭🇰 Hong Kong · 🇺🇸 US · 🇯🇵 Japan · 🇰🇷 Korea
Data	quotes · K-lines · technicals · fund flow · chip distribution · fundamentals · news
Sources	TickFlow · AkShare · Tushare · Tencent · efinance · Baostock · Yahoo Finance — priority + graceful fallback, field normalization
Push	WeCom · Feishu · Telegram · Discord · Slack · Email (+ PushPlus / ServerChan)

A single data source failing degrades gracefully instead of taking down the whole analysis.

🏗️ Architecture

            ┌──────────────────────────────────────────────────────┐
 Markets ──▶│  Data providers  TickFlow · AkShare · Tushare · YF …  │
 News    ──▶│  (priority + graceful fallback, field normalization)  │
            └───────────────────────────┬──────────────────────────┘
                                        ▼
            ┌──────────────────────────────────────────────────────┐
 InkSift ──▶│        Claude CLI harness  (skills · strategies)      │──▶ Decision dashboard
 screen     │   multi-lens analysis · risk gates · action checklist │
            └───────────────────────────┬──────────────────────────┘
                                        ▼
   Web · Desktop · API  ◀───────────────┴───────────▶  WeCom · Feishu · Telegram · Discord · Slack · Email

🗺️ Status

Shipped and running today:

• ✅ Claude-CLI harness is the default brain — web workstation + scheduled astock-* routines, no model keys
• ✅ Five markets · seven data sources with priority fallback
• ✅ Six push channels (WeCom / Feishu / Telegram / Discord / Slack / Email)
• ✅ Web + Electron desktop workstation (analysis, backtest, paper portfolio, alerts, config)
• ✅ Legacy LLM-provider pipeline retained for headless / CI (GitHub Actions zero-cost daily flow)
• 🧪 InkSift 墨筛 market screener — experimental, improving
• 🔭 Exploring: richer JP/KR calibration, broader catalyst taxonomy

🤝 Contributing

Issues and PRs are welcome. Keep changes focused, tested, and consistent with the existing contracts. If a change touches the report format or the web UI, attach before / after screenshots in the PR description. The contributor rules live in AGENTS.md.

⭐ Star us

If Smart Octopus saved you an afternoon of wiring data sources and prompts together, give it a star — it's the signal that keeps the project moving and helps others find it.

📄 License

MIT License © 2026 chenjiyong. Attribution to this repository in derivative work is appreciated.

⚠️ Disclaimer

For learning and research only. Nothing here is investment advice. Markets carry risk; the authors are not liable for any losses incurred from using this project.

_{Questions or collaboration · cjy416940585@gmail.com · Issues}