WyckoffAgent: A Natural Language Wyckoff Screener for A-Shares With an Approval Gate

What Problem It Solves and Who It Is For

WyckoffAgent targets traders who already believe in Wyckoff's accumulation and distribution phases but lack a systematic way to scan thousands of stocks for those patterns. The README describes a pipeline that takes natural language commands and turns them into daily A-share quotes, Wyckoff structure recognition, AI research reports, position risk checks, and pattern reviews. The intended user is not a casual investor; it is someone who wants a machine to apply a specific technical methodology consistently across the whole market. The project explicitly supports A-shares, Hong Kong, and US stocks, with separate funnel workflows for each market. It is for a trader who is comfortable with CLI tools, can manage API keys for Gemini, Claude, or OpenAI, and is willing to let an agent read the market on their behalf. The risk disclosure at the top of the README makes clear that it is for educational and research use, not investment advice.

Architecture: TickFlow Data, Supabase State, and a Cloudflare Queue

The system separates market data from user state. Daily quotes are pulled in real time from TickFlow; the README explicitly states there is no Supabase quote cache. Supabase stores user configuration, positions, pattern reviews, market signals, signal feedback, and task results. The web front end is a React app that calls a Hono Worker on Cloudflare. That Worker enforces request IDs, security headers, body size limits, Redis-based rate limiting, and a whitelist sandbox for tasks. Heavy research calculations require user confirmation before entering a single-concurrency Cloudflare Queue, then a signed Node execution bridge runs them in a Vercel Sandbox with no network access and auto-destruction. Each user gets one simultaneous task, with daily caps on creation count and CPU usage. This design is notable for its explicit cost model; the README links to docs/COST_MODEL.md to show that the shared cloud service runs on paid infrastructure. The architecture is a hybrid: local CLI and daemon for personal automation, plus a cloud backend for the web app. That split is a deliberate trade-off between responsiveness and centralized control.

Installation and First Run: CLI, Homebrew, pip, and the Dashboard

The README gives three installation routes. The one-liner is: curl -fsSL https://raw.githubusercontent.com/YoungCan-Wang/WyckoffTradingAgent/main/install.sh | bash. Homebrew users can run brew tap YoungCan-Wang/wyckoff && brew install wyckoff. Python users with uv can run uv pip install youngcan-wyckoff-analysis. After installation, the command wyckoff starts an agent conversation, and wyckoff dashboard launches a local visualization panel. On first start, you select a model via /model (Gemini, Claude, or OpenAI) and enter an API key. For scheduled tasks, the README describes a daemon for macOS launchd: scripts/daemon_install.sh installs it, wyckoff daemon --status checks it, and scripts/daemon_uninstall.sh removes it. The daemon only runs set_stop_loss unattended; everything else goes to a pending approval queue. You can also run a single manual pass without entering the TUI: wyckoff run "盘前风控检查" (pre-market risk check). The CLI is the primary interface, and the dashboard is a local web view for reviewing patterns, signals, positions, and logs.

The Approval Gate: How It Prevents Unattended Trading Mistakes

The most concrete safety mechanism is the approval queue for write operations. When the daemon or wyckoff run executes unattended, it first restores the locally saved CLI login state; otherwise automatic stop-loss writes go to a local USER_LIVE:local position instead of the cloud portfolio. The daemon is restricted to set_stop_loss, which only changes the stop price and cannot move positions or spend money. All other write actions enter a pending queue bound to the account that created them. The commands wyckoff approve list, wyckoff approve ok <id>, and wyckoff approve no <id> manage the queue. Approve list shows masked full parameters, and approve ok executes the exact saved parameters immediately. Failed approvals do not retry, to avoid duplicate fills. Pending items expire after 12 hours and become unapprovable, which means an overnight order would execute at the old price if you approve it the next morning. This design is a genuine safeguard against runaway automation, but it also imposes a discipline requirement on the user: you must check the queue within 12 hours or accept stale execution.

MCP Integration: Extending the Agent Without Loosening Control

WyckoffAgent can connect to external MCP servers, such as GitHub or a filesystem server, and their tools join the same session with the same approval gate. Installation requires the mcp extra: uv pip install -e '.[mcp]'. The command wyckoff mcp-add github --command npx --args -y @modelcontextprotocol/server-github --env GITHUB_TOKEN adds a server, reading the token from the environment to avoid putting it in shell history. Then wyckoff mcp-test github lists tools without entering a session, and wyckoff mcp-enable github activates it. New servers are disabled by default, and the model cannot add servers; only the user can write the config. The project's own mcp_server.py is rejected, because the tools are already built in. External tools get an mcp__<server>__ prefix and never override native tools. Write operations are identified by tool name and annotations heuristics, and anything unrecognized is treated as a write and goes to the approval queue. The daemon never executes external writes unattended. A failing server only disables itself; native tools keep working. Logs go to ~/.wyckoff/logs/mcp-<server>.log. This is a pragmatic way to extend functionality while keeping the blast radius small.

Screening Logic: Mainline Funnel, Confirmed Buy Zones, and AI Research Reports

The screening engine is a funnel that scans roughly 5000 A-share stocks daily to discover concept mainlines, eight-channel strength, candidate lanes, and buy-point confirmations. The README mentions a rule that NEUTRAL mainlines are preferred, and RISK_ON mainlines prohibit new positions. A cross-day mechanism links the daily funnel to the next day's open: the funnel sets candidates and environment, and after a confirmed signal the OMS provides the only allowed buy range. The opening price must fall within that range for execution. The report top includes a fixed '执行纪律' (execution discipline) section. AI research reports are generated by three independent LLM judgments: logic bankruptcy, reserve camp, and springboard. These are separate prompts, not a single model pass. There is also a signal feedback loop where the funnel records observations and post-market feedback aggregates health and registry data, supporting shadow strategy validation. This is not a simple screener; it is a multi-stage system that separates signal generation from execution, which reduces the risk of chasing a move outside the plan.

Limitations and Wrong Tool Cases

The most obvious limitation is the dependency on third-party services. Daily quotes come from TickFlow, and the web backend uses Cloudflare Workers, Supabase, Redis, and Vercel Sandbox. If any of those services changes its API, pricing, or availability, the tool breaks or becomes more expensive. The README is transparent about the cost model, but it still means you cannot run this as a fully offline system. The desktop app is unsigned on Windows and uses temporary signing on macOS, so users will see system warnings; that is a friction point for less technical users. The Streamlit MVP has been removed from the main branch, so anyone relying on that interface must switch to the CLI, web, or desktop. For a trader who does not follow Wyckoff or who wants a simple stock scanner, this is overkill. The natural language interface assumes you can articulate your intent; if you prefer a point-and-click screener, the CLI-first design will feel heavy. Also, the 12-hour approval expiry is a real operational risk for overnight decisions, and the daemon's restriction to set_stop_loss means you cannot automate any other trade action without manual approval.

Alternatives: CZSC and Generic LLM Trading Bots

The README credits CZSC (缠中说禅) as a top open-source trading project and acknowledges its author for guidance. CZSC is a different approach: it is a Python library for Chan theory (缠论), not a natural language agent. You write code to define and detect structural patterns, backtest them, and integrate them into your own pipeline. WyckoffAgent gives you a ready-made conversational layer and approval workflow; CZSC gives you a lower-level toolkit with no UI and no AI report generation. The trade-off is control versus convenience. With CZSC, you own the entire logic and can modify every rule, but you must build the screening loop, data fetching, and risk management yourself. With WyckoffAgent, you get a complete system but you accept the project's opinions on how Wyckoff phases should be identified and how execution should be gated. Another alternative is to use a generic LLM with a stock data API and write your own prompts, but that lacks the funnel logic, the OMS buy-zone rule, and the approval queue. WyckoffAgent is the only one that combines a specific technical methodology with an enforced execution discipline.

Maintenance, Upgrade Cost, and License Implications

The project is actively maintained, with a recent release v0.9.10 on PyPI and desktop versions v0.1.0 and v0.1.1. The README describes a PyPI release process with Trusted Publishing and a patch automation flow. Desktop releases are built only on manual candidates or via a desktop-release Skill, and manual candidates are kept for at most one day. This controlled release process reduces the risk of broken artifacts. The license is AGPL-3.0, which has real implications if you fork or embed the code. AGPL requires that if you modify the code and provide it over a network, you must make the source available to users of that network service. For a trading tool that may run as a web app, this is a significant constraint for commercial use. The README states the project remains open source and invites forks, but you should review the license text before building a proprietary product on top of it. Upgrade cost is moderate: the CLI is a single pip install, but the desktop app requires rebuilding the Electron package with a real Python runtime for each release, which is a non-trivial CI step. The daemon scripts are specific to macOS launchd, so Linux or Windows users must find their own scheduling mechanism.

Editorial conclusion

Adopt WyckoffAgent if you trade A-shares (or HK/US) with a Wyckoff methodology and want a natural language interface that enforces entry discipline via a confirmed-buy-zone rule and a human approval queue. Do not adopt it if you need a fully local, air-gapped tool, because daily quotes come from TickFlow and the web backend runs on Cloudflare Workers with Supabase storage. Before relying on it, verify the exact tick data license terms from TickFlow, test the approval queue with a small paper position, and confirm that the AGPL-3.0 license fits your distribution plans if you fork or embed the code. The daemon's set_stop_loss-only write policy is a concrete safety feature, but the 12-hour expiry on pending approvals means you must check the queue regularly or accept stale prices.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes