Free guide

Google's TimesFM forecasts your sales, leads and traffic in Claude Code

GitHub stars
35K
models to train
0
of RAM is enough
4 GB

I'm Aleksei. I find open-source AI tools that do real work and show how to run them. @alekseitalksai

I build AI agents & automations for businesses, and do 1:1 consulting calls Work with me

Google Research open-sourced TimesFM, an AI model that forecasts your numbers. You give it your history, for example weekly sales, new leads or website visits, and it shows what comes next. You train nothing: the model comes already trained. And you get more than one number: a range from a low case to a high case.

What it is

TimesFM is a forecasting model from Google Research. The code is open source under the Apache 2.0 license and has 35K stars on GitHub. It is pretrained, so it works zero-shot: you don't build or train a model of your own, you just give it your data.

For every step ahead you get the most likely value plus a range, from the 10th to the 90th percentile. In plain words: a low case, the likely case and a high case, so you see how sure the forecast is.

It can take into account what you already know about the future: holidays, promotions, prices, weather forecasts. You add them as extra columns next to your numbers, and TimesFM uses them in the forecast.

The repo ships a ready-made agent skill, timesfm-forecasting. It checks your computer's memory and disk before it loads the model, reads your file and returns the forecast with its range. The prompt below has Claude Code set it up for you.

Prefer a spreadsheet? Google Sheets can forecast with TimesFM too, through Connected Sheets for BigQuery: Advanced Analytics, then Create a Forecast.

Steps

  1. Step 1. Open Claude Code

    Create an empty folder, for example forecast, and open Claude Code in it.

  2. Step 2. Paste the prompt

    Claude checks your computer, installs TimesFM and its agent skill from a fixed, tested list and downloads the model, about 900 MB. Before every install or download it tells you what it is and waits for your yes. If something doesn't install, it tells you what to do.

  3. Step 3. Give it your numbers

    Save your sales, leads or traffic as a CSV file with a date column and a number column. Excel and Google Sheets can both save a sheet as CSV. No data at hand? Claude makes a sample file so you can see how it works.

  4. Step 4. Read the forecast

    Claude shows a chart with your history, the likely line and the range from low to high, plus a table you can open in Excel or Google Sheets. Then ask more, for example: "Forecast my weekly leads for the next 12 weeks" or "Add the holidays and my planned promotions and forecast again".

Copy this into Claude Code

Set up Google's TimesFM forecasting model on my computer with its official agent skill, pinned to exact versions, then forecast my numbers.

SETUP
Work only inside the current folder. Create a subfolder called forecast; if that name is taken, pick a new name, and never delete or overwrite files that were already here. First check that this computer has Python 3.12, at least 4 GB of RAM and 4 GB of free disk space; on Linux it needs 15 GB of free disk space, because PyTorch there also installs NVIDIA's CUDA libraries, about 3 GB to download. If Python 3.12 is missing, stop and tell me to install Python 3.12 from python.org with its normal installer, then wait for me. Never use sudo. Before each install or download, tell me in one line what it is and wait for my OK. Don't ask me to run commands.
1) Packages. Every package is pinned in a file I prepared and tested: https://blog.alekseimedia.com/assets/kits/forecast/requirements.txt. Download it into the project folder byte for byte, not through a tool that summarizes or rewrites pages, and check that its SHA-256 is 5277f8e9aa47ab0d29ac9b0870b88d56b5a5330da57c496485cbdf094598d058. If it doesn't match, stop and tell me. Make a Python 3.12 virtual environment inside the project folder and install only from this file: pip install --require-hashes --only-binary=:all: -r requirements.txt (TimesFM 3.0.2 with PyTorch, JAX and scikit-learn for holidays and prices, pandas and matplotlib; every file is checked by its hash). Don't add, update or remove a package.
2) Skill. The agent skill is 6 files from github.com/google-research/timesfm at commit e51928e27119cb17bebc005be2696b75e0a9e688, folder timesfm-forecasting. Download https://blog.alekseimedia.com/assets/kits/forecast/SHA256SUMS.txt byte for byte and check that its SHA-256 is b2a754656524111826b2b438b4cdde6bfa149996cd1c357a89c5502a56e8edea. If it doesn't match, stop and tell me. That file lists the 6 skill files and the SHA-256 of each. Download each file it names, and nothing else, from https://raw.githubusercontent.com/google-research/timesfm/e51928e27119cb17bebc005be2696b75e0a9e688/timesfm-forecasting/ followed by its name, into .claude/skills/timesfm-forecasting inside the project folder, keeping its subfolders, byte for byte. Check the SHA-256 of each file; if one doesn't match, stop and tell me. Read SKILL.md and follow it, with two exceptions: use the virtual environment above instead of the install commands in the skill, and never install anything else it suggests.
3) Model. Use TimesFM 2.5, whose weights are Apache 2.0 and fine for business use, not TimesFM 3.0, whose downloadable weights are for non-commercial use only. From google/timesfm-2.5-200m-pytorch on Hugging Face, download only config.json and model.safetensors at revision 1d952420fba87f3c6dee4f240de0f1a0fbc790e3 into models/timesfm-2.5-200m inside the project. Check that the SHA-256 of model.safetensors is 2f776efe6245e42b24bc4153ffdf61810140210e4bd3b01fb21f7aa779ab6ce8 and of config.json is cd3315b760d5cc7e278d7afdf41b897031ced888fc6c115bd9b3ac0ea2c47408; if one doesn't match, stop and tell me. Load the model from that local folder with HF_HUB_OFFLINE=1 set, so nothing else is downloaded: the skill's scripts load it by its Hugging Face name, so pass the local folder instead. These are the only downloads.
Then run the skill's system check, scripts/check_system.py, and tell me in plain words whether my computer is ready.

FORECAST
Ask me for my file: a CSV with a date column and the number I want to forecast, for example sales, leads, orders or website visits. If I don't have one yet, make a sample file with two years of weekly sales so I can see how it works. Look at the data first: tell me the columns, the date range and the step (daily, weekly or monthly), and handle gaps the way the skill's data guide says. Ask me how far ahead I want to see; if I don't say, use 12 steps.
Forecast with TimesFM and save into an out folder in the project: forecast.png (my history, the most likely line and the band from the 10th to the 90th percentile) and forecast.csv (date, low, likely, high), which I can open in Excel or Google Sheets. Open the chart for me, then explain the result in three plain sentences: where the numbers are heading, the low and the high case, and how wide the uncertainty is.
If I know things about the future, like holidays, promotions, price changes or weather forecasts, help me add them as columns that cover both the past and the forecast period, then forecast again with covariates as the skill describes and show me both forecasts side by side.
Last, write HOW-TO.md in the project: which file I replace with new data and what I say to you to get a fresh forecast.

I'm not a programmer: anything you can do yourself, do it yourself.
Work with me

Want this working for your business?

  • AI agents for your business
  • Automations for the work you repeat
  • 1:1 consulting calls
See prices and book

or message me on Instagram

Good to know

Many numbers at once

Forecast every product, store or channel in one run: the skill handles many series in a batch. Give Claude one file with a column for each, or one row per item and date.

Spot unusual days

A value that lands outside the range is unusual. Ask Claude to check last month against the forecast and show you the days that broke the pattern.

Forecasts in Google Sheets

If your data already lives in BigQuery, open it as a Connected Sheet, then Advanced Analytics, Create a Forecast. Sheets draws the chart for you.

The honest read

  • TimesFM finds patterns in your history. It doesn't know about a new competitor, a viral post or a price change unless you add it as a column. Treat the forecast as a starting point, not a promise.
  • Holidays, promotions, prices and weather are not built in: you add them as columns for the past and for the forecast period. TimesFM doesn't look them up by itself.
  • The code and the TimesFM 2.5 model in the prompt are Apache 2.0, so you can use them for your business. The newer TimesFM 3.0 weights are non-commercial when you download and run them yourself; for business use Google offers 3.0 through BigQuery. This open version is not an officially supported Google product.
  • The model runs on your computer, no graphics card needed, and TimesFM doesn't send your data anywhere. Claude Code still reads your file to work with it, like any file you show Claude, and the setup uses your Claude limits.
  • Every package comes from a fixed, tested list and is checked by its hash, so nothing changes under you. It still runs on your computer with your normal user access, like any app you install: the folder keeps the files tidy, it is not a sandbox.
  • The Google Sheets route needs your data in BigQuery, Google's cloud database, inside a Google Cloud project. BigQuery is a Google Cloud service with its own pricing.
Work with me

Want this built for your business?

I build AI agents and automations for businesses, and do 1:1 consulting calls. Message me on Instagram with what your business does, and I'll tell you what can be automated.

Message me on Instagram