# timesfm-forecasting

> Zero-shot time series forecasting with Google's TimesFM foundation model — for any univariate time series (sales, sensors, energy, vitals, weather) without training a custom model, with CSV/DataFrame/array inputs, point forecasts, and prediction intervals.

**Use case**: Zero-shot time series forecasting without model training

**Canonical URL**: https://agentcookbooks.com/skills/timesfm-forecasting/

**Topics**: claude-code, skills, science, data-science

**Trigger phrases**: "forecast this time series", "predict future values", "TimesFM forecast", "zero-shot forecasting", "time series prediction"

**Source**: [K-Dense AI](https://github.com/K-Dense-AI/scientific-agent-skills/tree/main/scientific-skills/timesfm-forecasting)

**License**: Apache-2.0

---

## What it does

`timesfm-forecasting` is a Claude Code skill from K-Dense AI's [scientific-agent-skills repo](https://github.com/K-Dense-AI/scientific-agent-skills). It turns Claude into a TimesFM deployment guide for zero-shot time series forecasting using Google's TimesFM foundation model — no model training required. It accepts CSV files, pandas DataFrames, or NumPy arrays as input and produces point forecasts with prediction intervals for any univariate time series.

A session produces forecasts ready for plotting or downstream use, plus a preflight system check that verifies RAM and GPU availability before running TimesFM — since the foundation model has non-trivial hardware requirements.

The skill was authored by Clayton Young / Superior Byte Works, LLC and distributed through the K-Dense AI collection.

## When to use it

Reach for it when:

- You need a quick, reasonable forecast on a new time series without the overhead of training an ARIMA, Prophet, or custom neural model
- You want to benchmark a custom model against a strong zero-shot baseline before investing in training
- You're forecasting multiple time series of the same type (e.g., sensor readings across 100 devices) and want to run them through a single pre-trained model

When *not* to reach for it:

- Multivariate time series where cross-variable dependencies matter — TimesFM is univariate
- Time series where you have strong domain knowledge to incorporate through explicit model structure — `statsmodels` ARIMA or Prophet allows that

## Install

Copy the `SKILL.md` from K-Dense AI's [timesfm-forecasting folder](https://github.com/K-Dense-AI/scientific-agent-skills/tree/main/scientific-skills/timesfm-forecasting) into `.claude/skills/timesfm-forecasting/` in your project. Run the preflight checker script first to confirm your environment has sufficient RAM and GPU for TimesFM.

Trigger phrases: "forecast this time series", "predict future values", "TimesFM forecast", "zero-shot forecasting".

## What a session looks like

A typical session has three phases:

1. **Preflight check.** Claude runs the included system checker script to verify RAM and GPU availability before loading the TimesFM model weights, which can be several GB.
2. **Data ingestion.** Provide the time series as a CSV file, DataFrame, or array with timestamps. Claude handles frequency detection and any required resampling.
3. **Forecast generation.** TimesFM runs inference and returns point forecasts and prediction intervals for the specified horizon. Results are plotted with the historical series and forecast overlaid.

## Receipts

**Where it works well:**
- Quick baseline forecasts for business time series (sales, demand, energy consumption) where the zero-shot performance is competitive with traditional statistical methods without any tuning
- Batch forecasting across many similar series — the skill's preflight and inference pipeline handles this cleanly

**Where it backfires:**
- Highly irregular or sparse time series where the foundation model's training distribution doesn't cover the pattern
- Environments with limited RAM or no GPU — the preflight checker will catch this, but TimesFM is not suitable for lightweight inference

**Pattern that works:** run the preflight check first every time, not just on first use — model weights and environment configurations change, and the checker saves frustration from mid-run failures.

## Source and attribution

Skill authored by Clayton Young / Superior Byte Works, LLC (@borealBytes). The canonical SKILL.md lives in the [`timesfm-forecasting` folder](https://github.com/K-Dense-AI/scientific-agent-skills/tree/main/scientific-skills/timesfm-forecasting) of K-Dense AI's scientific-agent-skills repository.

License: Apache-2.0. Install, adapt, and redistribute with attribution preserved.

This page documents the skill from a practitioner's perspective. For the formal spec and any updates, defer to the source repo.