Markov Hedge Fund Method: A Regime Detection Skill for Claude Code

What the Markov Hedge Fund Method skill actually computes

The repository is the companion to video 1 of a Quant Series, titled How To Use The Hedge Fund Method To Win Every Single Trade. The framework comes from Roan (@RohOnChain); the plugin, installer and animations come from Lewis Jackson. That framing matters, because the README positions the project as a skill rather than a library or a service.

The question it answers is narrow and stated plainly: what regime are we in, how sticky is it, and what does that imply for risk and direction? The README lists the outputs: each day is labelled Bull, Bear or Sideways by a rolling-return rule with a 20-day default and plus or minus 5 percent thresholds; a 3x3 transition matrix is estimated from the asset's own history by maximum likelihood; n-step forecasts come from raising that matrix to powers, which the README attributes to Chapman-Kolmogorov; a long-run stationary distribution gives the baseline regime mix; and a signed signal is emitted as bull_prob minus bear_prob, which the README reads as direction plus conviction.

Who is this for? The README names three composition roles: a confirmation layer inside a trading agent you already run, a standalone signal, or a tail-risk filter. It also invites a question that is really a screening test: what's the long-run regime mix of AAPL, is it too tail-heavy to trade? That is the audience. Someone who wants a second opinion on an existing strategy rather than a strategy handed to them.

Regime labels, transition matrices and the walk-forward backtest

The mechanism is a chain of steps, and each one is inspectable.

First, labelling. A rolling return over the lookback window is compared against the two thresholds. Above plus 5 percent is Bull, below minus 5 percent is Bear, everything else is Sideways. This is a rule, not a fit, so the labels are deterministic given the window and thresholds. Change the window to 10 and the same price series produces a different regime history. The README does not claim the defaults are optimal for any asset.

Second, the transition matrix. Count how often each label follows each other label in the history and normalise, and you have a 3x3 maximum-likelihood estimate of the chain. Third, forecasting: raising that matrix to the n-th power gives the n-step-ahead distribution, the Chapman-Kolmogorov step the README names. Fourth, the stationary distribution, which is the long-run regime mix and the number that answers the tail-heavy question.

Fifth, the signal. Subtracting the bear probability from the bull probability collapses the distribution into one signed number. It is a clean reduction and also a lossy one: a 50/50 bull/bear split and a flat sideways forecast can both land near zero, and the README's JSON contract in skills/regime/SKILL.md is where the composition patterns live if you need to distinguish them.

Sixth, validation. The README states the skill runs a walk-forward backtest with no lookahead and reports Sharpe plus max drawdown. That is the claim to check hardest, because walk-forward correctness depends on where the refit boundary sits, and the README describes the property rather than the implementation.

Installing the Claude Code plugin and running a first regime check

The headline install path is two commands inside Claude Code. The README gives them exactly as follows.

/plugin marketplace add jackson-video-resources/markov-hedge-fund-method
/plugin install markov-hedge-fund-method@markov-hedge-fund-method

After those two lines the skill is registered. The README states there are no API keys, no accounts and no sudo, and that dependencies are resolved on first run by uv through PEP 723 inline metadata, so there is nothing to pip-install by hand.

Invoke it explicitly with the namespaced command, or in plain English and let Claude fire the skill.

/markov-hedge-fund-method:regime

A first real use is a ticker pull. The README documents --ticker with yfinance as the fetch path and --csv as the alternative.

/markov-hedge-fund-method:regime --ticker BTC-USD

What you should see is the regime label for the current day, the transition matrix, the stationary distribution and the signed signal. The second path takes your own data: a CSV with a date column and a close column, passed as --csv my_prices.csv. That is the one to use if the asset is not on Yahoo, and it is also the one to use if you want to know exactly which prices produced the matrix.

If you would rather not install from a marketplace, the README points at markov-hedge-fund-method.md, the original one-shot onboarding prompt built live on camera. Pasting it into Claude Code in agent mode makes the agent detect your OS, install uv, write every file and run a sanity check, so you can read each line as it is written. The README calls this the zero-trust path and says most people should use the two-command install instead.

The Pine Script indicator is a separate artifact with its own limits

pine-script/markov-hedge-fund-method.pine is a TradingView v5 indicator, not a port of the Python skill. The README describes what it paints on the chart: a regime ribbon, a live 3x3 transition matrix in the corner, a stationary-distribution table and a current-regime banner. Its inputs are the lookback window (default 20), the Bull and Bear thresholds (default plus or minus 5 percent) and table toggles.

The install is manual and browser-bound: open TradingView, open the Pine Editor, paste the .pine file, save, add to chart. There is no package manager step and no CLI.

The limitation is structural. The indicator recomputes on chart data inside TradingView, so it does not share code with the Python skill, and the README does not claim the two produce identical numbers on the same series. If you want the walk-forward Sharpe and max drawdown, the Pine script is the wrong artifact; those are described as Python-side outputs. If you want a visual read of the regime ribbon and the matrix while you look at a chart, the Pine script is the faster route. Treat them as two views of the same framework, and check that they agree on your asset before you rely on either.

Where the Markov Hedge Fund Method breaks down

The first limitation is the labelling rule itself. A 20-day rolling return with plus or minus 5 percent thresholds is a convention. On a low-volatility instrument the Bear bucket may almost never trigger, and on a high-volatility one the Sideways bucket can collapse to near zero. The transition matrix inherits that distortion, and the stationary distribution then reports a regime mix that is partly an artifact of the threshold choice. The README exposes the inputs but does not claim they are calibrated per asset.

The second is the Hidden Markov Model option. The README states the skill can optionally fit one via hmmlearn and that it degrades gracefully if the library cannot compile. Graceful degradation is the right design for an install that must not fail, but it also means you can believe you are running an HMM when you are running the rolling-return rule. Check which path executed before you compare results across machines.

The third is scope. This is a skill for an agent, tied to Claude Code as the runtime. If your stack is a Python service, a notebook pipeline or a scheduled job, the plugin is not the integration point; you would be reimplementing the logic or calling the agent, and the README does not document a library API for that. The README also does not document rollback, version pinning or an upgrade path for the plugin, so a change on the marketplace side is not something you can pin against.

Finally, the framing. The video title promises winning every single trade. The artifact delivers a regime label and a backtest. Read the second, not the first.

How this compares with hmmlearn and statsmodels directly

The honest alternative is to skip the plugin and use the libraries underneath. hmmlearn gives you Gaussian or categorical hidden Markov models with Baum-Welch fitting and Viterbi decoding, so the hidden state is inferred rather than thresholded, and you choose the number of states instead of being fixed at three. statsmodels offers Markov regression and Markov switching models where the transition probabilities can depend on exogenous variables, which is a genuinely different model class from a fixed matrix raised to powers.

The difference in approach is where the regime boundary comes from. This project defines regimes by a rule you can read in one line and then estimates the transition dynamics on top. hmmlearn and statsmodels infer the states from the data, which removes the threshold arbitrariness and adds a fitting problem: initialisation, local optima, and the need to pick a state count. The plugin's README acknowledges the trade by offering the HMM as an optional upgrade rather than the default.

What you give up by going direct is the packaging. No plugin install, no agent integration, no Pine indicator, no JSON contract for composing the output into another strategy. What you gain is control over the model, the ability to run it in any Python process, and no dependency on a marketplace. If you already have a research environment, the direct route is more work up front and less work later. If you are exploring inside Claude Code, the plugin is the shorter path to a number.

Maintenance, licensing and what the repository does not pin down

The last push to the default branch was on 2026-05-20. That is four months before today, so the repository is not archived but it is also not something to describe as actively developed. Treat it as a finished teaching artifact that may receive occasional updates, and plan accordingly: if you depend on it, fork it or vendor the skill files rather than assuming the marketplace entry stays stable.

The README says the project is MIT and points at an umbrella LICENSE one directory up. The repository metadata reports the licence as NOASSERTION, which means the licence could not be automatically identified. Those two statements do not agree, and the README itself references a LICENSE file outside this repository. Before you redistribute the skill or ship anything derived from it, read the actual licence text that applies to this repository and confirm which file governs. That is a factual check, not a legal opinion.

Upgrade cost is low in one sense and unclear in another. The skill resolves dependencies on first run via uv and PEP 723 inline metadata, so there is no requirements file to maintain and no virtualenv to rebuild. But the README does not document a version number, a changelog or a pinning mechanism for the plugin, so you cannot state which revision you installed. If reproducibility matters for your backtest, record the commit you installed from.

Editorial conclusion

Adopt it if you already work inside Claude Code and want a regime label, a transition matrix and a walk-forward backtest on a ticker or your own CSV without writing the plumbing yourself. Do not adopt it as a standalone trading system or as a substitute for your own validation: the README describes an educational companion to a video, the Hidden Markov Model path degrades when hmmlearn will not compile, and the default 20-day, plus or minus 5 percent labelling rule is a convention you have to justify for your own asset. Verify first that your date and close CSV parses cleanly, that the walk-forward Sharpe behaves sensibly when you change the lookback window, and that the repository's LICENSE situation matches the MIT claim in the README before you ship anything derived from it.

Frequently asked questions

Official sources

1. Issues
2. jackson-video-resources/markov-hedge-fund-method on GitHub
3. README