CastClaw Documentation
中文 Technical Report Back to Home

Quick Start

Installation & Environment

CastClaw's quick-start flow matches the homepage guide: install the CLI globally, verify the version, configure the LLM interactively, and then start forecasting from the dataset directory.

Prerequisites: Bun ≥ 1.3.11, Python ≥ 3.10, uv, and at least one LLM API key.

Dependency Version Purpose
Bun ≥ 1.3.11 Runtime and package manager
Python ≥ 3.10 ML backend for forecasting models
uv Latest Python dependency management
GPU (optional) CUDA 12.8 Deep learning acceleration

Install

# Global npm install (recommended)
npm install -g castclaw

Verify Installation

castclaw --version

Configure LLM

# Type castclaw in the terminal to enter interactive API key configuration
castclaw

# Or run /connect inside the CastClaw terminal to switch providers
/connect

Start Forecasting

# Enter the dataset directory and launch the CLI
cd /path/to/your/dataset
castclaw

After the CLI starts, enter the task description in the Planner tab (Ctrl+1):

# Example: initialize an energy consumption forecasting task
Initialize a forecasting session for data/etth1.csv. Target column: OT, time column: date,
forecast horizon: 96 steps, lookback length: 336. Use a 70/20/10 split and evaluate with MSE and MAE.
Recommendation

For your first run, connect only one provider you already know well. Prefer the interactive API key setup through castclaw; use /connect when you need to switch providers.

First Forecast Task (5-Minute Walkthrough)

We recommend starting with load.csv (fields: TIMESTAMP / LOAD, hourly frequency) to walk through the full workflow quickly. The goal is to understand the system rhythm, not to squeeze out the absolute best score on day one.

1

Prepare a clean working directory

Put load.csv in a dedicated experiment folder so it does not share .forecast/ state with other tasks.

2

Launch the CLI

Run castclaw inside that directory. On the first run, confirm the model and budget settings.

3

Enter the task in Planner

Specify the target column, time granularity, forecast horizon, and metrics. The more concrete the description, the better the Skill draft.

4

Review the Skill draft

Check whether the candidate experience has reasonable applicability conditions, evidence sources, and risk notes before continuing.

5

Watch iterations and the final report

Forecaster runs workflow adaptation, and Critic produces final-report.md. Watch for possible experience-review human-in-the-loop pauses.

mkdir my-run && cd my-run
# After placing load.csv in the current folder
castclaw
Sample Planner prompt

Please forecast the next 24 hours of power load using load.csv; the time column is TIMESTAMP, the target column is LOAD, the evaluation metrics are MAE and MAPE, and the experiment budget should stay within 20 runs.

Flexible Task Input

In addition to ratio-based splitting, CastClaw can parse two timestamp cut points from the task prompt to split train, validation, and test periods. Each cut timestamp is the last row in the preceding split that may serve as history or forecast-origin context; later evaluation windows may reuse earlier true history and start their evaluated target window only after forecast_gap.

Configurable stride

You can write stride = 24 or describe the stride in natural language. If omitted, the default stride is 1; when provided, it affects training, validation, and test window sampling.

Forecast gap

When there is a gap between the history window and the target window, set forecast_gap. The model internally predicts forecast_gap + pred_len, while evaluation and generative reasoning expose only the trailing pred_len target window.

Use timestamp splitting with 2025-06-30 09:30:00 and 2025-09-30 09:30:00.
lookback_window = 711
predicted_window = 96
forecast_gap = 57
stride = 96

Prediction Prior and Generative Prediction Reasoning

If you already have forecasts from an external model or operational system, you can submit them through the Prediction Prior workflow. The prior CSV must be a full aligned dataset with the same timestamp column, column names, column order, row count, frequency, and exogenous variables as the truth dataset. Training targets remain true values, while validation and test target values may be replaced by prior predictions.

UserPrior path

After validation, CastClaw enters the UserPrior path. It skips model-zoo search, hyperparameter tuning, and small-model training, then treats the submitted prior as the raw prediction.

Validation contract

Generative Prediction Reasoning designs candidate Skills only from the validation-front half, accepts or rejects them on the validation-back half, and applies locked Skills to test only at the final stage. Raw and adjusted outputs remain separate.

CLI Basics

The CLI is the command-line workspace where the three agents collaborate. The key is to know which stage you are in and which agent owns the next move.

Shortcut / Area Purpose What to watch
Ctrl+1 Switch to Planner Check whether task definition, analysis output, and Skill drafts are coherent.
Ctrl+2 Switch to Forecaster Watch whether the experience chain stalls, whether candidate rules are evidence-backed, and whether human-in-the-loop review is triggered.
Ctrl+3 Switch to Critic Verify that the report covers breakdowns, evidence, and concrete next steps.
Task status panel Inspect current stage and budget Confirm whether you are in Init, Analysis, Forecasting, or Report.
Common misunderstanding

The CLI is a stage-driven task workspace, not a one-shot chat box. The important question is always: which stage are we in, and who acts next?

Interaction Modes

CastClaw is not limited to a single usage pattern. Depending on task ambiguity and collaboration depth, you can use it in two modes: clarify the problem first, then move into co-driven execution. These two modes cover the core stages of task definition and collaborative forecasting.

Socratic Interaction

This mode fits tasks whose goals are still vague. CastClaw asks questions first so you can pin down the target, time granularity, exogenous variables, evaluation metrics, and resource budget before execution begins.

FocusDescription
Best forEarly-stage planning, problem framing, and requirement clarification.
Core actionIterative questioning, assumption cleanup, and forecast-plan freezing.
Your roleProvide domain context and confirm target column, timestamp, horizon, and metrics.
Recommendation

If you cannot yet explain what should be forecasted or how success will be judged, start here. It is the lowest-cost way to avoid wasting budget on the wrong task definition.

Cognitive Accompaniment

This mode fits experience review and correction while the workflow is running. The system surfaces phase transitions, Skill audits, candidate-experience conflicts, and key evidence so that you can intervene in experience accumulation.

FocusDescription
Best forExperience review, result explanation, and collaborative curation.
Core actionInspect intermediate evidence, review Skills, and intervene when experience conflicts or applicability boundaries are unclear.
Your roleAdd domain evidence, label abnormal cases, and confirm which conclusions should be accumulated as experience.
Typical trigger

Use this mode when candidate experience adds no new information, when explanations conflict with domain common sense, or when the applicability boundary of an experience is unclear.

CLI Reference

castclaw Launch Options

CommandPurpose
castclaw Launch CastClaw in the current directory and take over the forecasting task in this project context.
castclaw --model anthropic/claude-sonnet-4-6 Explicitly select the primary model at launch time and temporarily override the default configuration.
castclaw --version Print the current CLI version, useful when you are debugging environment mismatch.

Shortcut Cheat Sheet

ShortcutAction
Ctrl+1Switch to Planner
Ctrl+2Switch to Forecaster
Ctrl+3Switch to Critic

Once these three shortcuts become muscle memory, the workflow feels natural: define and review in Planner, observe convergence in Forecaster, and judge evidence in Critic.

forecast toolchain

forecast_state

  • forecast_state init: initialize the task and create the .forecast/ workspace.
  • Stage transitions are enforced. You should not skip them if you want the run to remain traceable.

forecast_task

  • Helper tool for task definition around task.json.
  • Useful during Init when you need to confirm target column, time column, forecast horizon, and metrics.

forecast_prediction_prior

  • Imports and validates a full user-submitted prediction-prior CSV.
  • After validation, creates UserPrior artifacts and enters the deep Generative Prediction Reasoning path.

forecast_adjustment_*

  • Freezes eligible source models, generates validation-front diagnostics, and writes candidate Skills.
  • Evaluates candidates on the validation-back half, locks accepted Skills, and lets Critic apply them on test.

Configuration

CAST.md Policy File

This is the project-level policy file automatically injected into every agent context. It should hold stable, long-lived rules that every stage should know.

FieldDescription
banned_modelsList of banned models or model families that should be excluded immediately.
max_experimentsMaximum number of experiments, which caps the Forecaster exploration budget.
no_improve_thresholdPause threshold for consecutive rounds with no new experience; reaching it triggers human-in-the-loop review.
eval_metricPreferred evaluation metric such as MAE, MAPE, or RMSE.
domain_notesDomain background injected into every agent context to keep judgments aligned with business reality.

castclaw.json Parameters

This is the task-level or project-level default configuration entry point. It is a good place to share baseline model and budget settings across a team.

{
  "model": "anthropic/claude-sonnet-4-6",
  "light_model": "anthropic/claude-haiku-4-5",
  "max_experiments": 20,
  "no_improve_threshold": 5
}
Configuration tip

Put your highest-quality model in the primary slot and a lighter model on the auxiliary analysis path to balance quality and speed.

Model Providers (LLM Configuration)

CastClaw follows a Vercel AI SDK style integration pattern, so you can connect multiple providers depending on network conditions, budget, and deployment constraints.

Global providers

Anthropic Claude, OpenAI GPT, and Google Gemini fit environments with stable international API access.

China-friendly providers

DeepSeek, Qwen, and GLM fit domestic network environments or teams that prefer locally accessible endpoints.

Deployment options

Direct APIs and self-hosted inference services fit the same orchestration model.

Core Concepts

Forecasting Workflow Learning Framework Overview

CastClaw is not only a tool for running one forecast. It is a framework for learning reusable forecasting workflows. The full loop contains four stages: task negotiation and value-aware interaction, offline rule learning and experience accumulation, online slow-thinking reasoning and workflow adaptation, and result evaluation and workflow release.

User Task
  ↓
Value-aware interaction (task specification / constraints / feedback)
  ↓
Rule-experience learning (forecasting rules / solving experience / workflow scoring)
  ↓
Online slow-thinking adaptation (context recognition / tool calls / reflection)
  ↓
Evaluation and release (metrics / case-level evidence / deployable workflow)
CastClaw forecasting workflow learning framework
StageResponsibilityWhen You Touch It
Value-aware interaction Clarifies objectives, freezes task specifications, and records constraints, preferences, and human feedback. When starting a task, filling missing requirements, or confirming high-impact decisions.
Rule-experience learning Learns forecasting rules from training data and accumulates tool routes, failure causes, and workflow scores from validation. During pre-forecast analysis, Skill review, experience reuse, and team asset curation.
Online adaptation Retrieves rules, experience, and feedback, instantiates candidate workflows, invokes tools, and reflects on results. During actual forecasting, abnormal results, or strategy adjustment.
Evaluation and release Evaluates forecast quality, validates workflow effectiveness, explains cases with evidence, and releases reusable workflows. When reading final reports, reviewing a project, or preparing reuse/deployment.

Execution Roles (Planner / Forecaster / Critic)

Planner, Forecaster, and Critic are the CLI execution roles that carry different stages of the workflow learning framework. Treat them as different roles, not interchangeable chat windows.

AgentCore ResponsibilityKey Behaviors
Planner Task specification, value preference recording, and rule induction. Runs qualitative and quantitative analysis in parallel, writes the pre-forecast report, and drafts candidate rules and Skills.
Forecaster Online workflow adaptation and experiment loops. Reads experience, selects configs, calls CastFeat and CastZoo, records reflections, and triggers Human in the Loop when needed.
Critic Result evaluation, evidence explanation, and workflow release. Compares performance, generates visualizations and case-level explanations, and produces final-report.md.

Forecasting Workflow Learning Path

CastClaw turns forecasting into a reviewable learning chain: clarify the value target, learn rules and experience offline, adapt the workflow online, then evaluate, explain, and release reusable workflows. Internally, phase transitions and file protocols still keep the process traceable and auditable.

1

Task negotiation and specification

Freezes task.json, creates the .forecast/ working directory, and records target columns, time columns, horizon, metrics, budget constraints, and human preferences.

2

Offline rule induction

Runs two tracks in parallel: qualitative domain analysis through WebSearch and quantitative diagnostics through CastSense. The outputs induce candidate forecasting rules from data, context, and domain knowledge.

3

Experience accumulation and Skill audit

Planner pauses after drafting 2 to 4 candidate Skills, waiting for human review of evidence sources, risks, failure boundaries, and applicability boundaries. Approved Skills become reusable solving experience.

4

Online slow-thinking adaptation

Read prior experience → recognize the current context → choose a config → build representations with CastFeat → train and evaluate through CastZoo → record reflections → check budget → repeat. If Generative Prediction Reasoning is enabled, candidate Skills are designed from the validation-front half and accepted only through validation-back metrics. In UserPrior mode, model search and training are skipped so the submitted prior can be optimized directly.

5

Evaluation, explanation, and workflow release

Critic consolidates experiment artifacts, performance breakdowns, and visual explanations into a structured final-report.md. The report keeps workflow-effectiveness judgments, case-level evidence, and auditable raw / adjusted artifacts when applicable.

Design focus

CastClaw is not differentiated by "running more models." It is differentiated by learning which forecasting workflow fits which context, then turning successful experience into reusable workflow assets.

Human in the Loop

What Human in the Loop Means

When candidate experience stops adding value, result explanations become abnormal, or accumulated experience clearly conflicts with domain knowledge, the system pauses at a recoverable checkpoint and waits for human feedback. This is not failure. It is a correction window for experience accumulation.

Checkpoint 1: Confirm the task setup

Confirm the target column, time column, forecast horizon, evaluation metric, and resource limits so a flawed task definition does not get amplified downstream.

Checkpoint 2: Review candidate experience

Confirm that the applicability conditions, evidence sources, risk notes, and failure boundaries of a candidate Skill are reasonable before low-quality conclusions enter the experience library.

Checkpoint 3: Intervene in experience accumulation

Add domain priors, label abnormal cases, revise applicability boundaries, or add failure attribution before continuing to accumulate experience.

Do not treat Human in the Loop as a rerun button

Effective intervention changes what gets accumulated as experience: add evidence, revise applicability conditions, explain anomalous dates, record failure boundaries, or add external constraints.

Skill Audit: How to Intervene

When reviewing a Skill, the key question is whether this experience truly fits the current task, not whether the YAML looks neat. Focus on applicability, evidence sources, failure boundaries, and risk notes.

What to review

  • Whether the applicability conditions match the data profile, such as strong seasonality, long sequences, or stable frequency.
  • Whether the evidence source is strong enough to support reusing this experience.
  • Whether the risk warnings cover known failure modes such as overfitting on small samples, distribution drift, or nighttime zeros.

Recommended interventions

  • Add known holidays, equipment changes, or policy events to the domain notes.
  • Label which case types this experience applies to or does not apply to.
  • Add failure causes so similar tasks do not accumulate the same low-quality experience again.

When to Confirm Results and Intervene

The most valuable moments for human review are when the question "should this be accumulated as experience?" changes, not after every single result.

No new experience Results conflict with domain knowledge Candidate experience conflict Anomalous dates matter materially Applicability boundary is unclear
Practical rule

If your intervention cannot change what gets accumulated in the experience library, do not step in yet. Human in the Loop creates value by changing experience accumulation, not by repeatedly confirming the current state.

Plugin Toolbox

CastSense: Data Diagnostics

CastSense answers the question, "What state is this series in right now?" It turns trend, seasonality, anomalies, and distribution changes into structured knowledge that Planner can use to generate strategies.

Trend and seasonality detection

Detects long-term trends, daily cycles, weekly cycles, and multiscale periodicities to help decide which model path should come first.

Anomaly and drift localization

Finds change points, outliers, non-stationarity, and distribution drift, providing evidence for risk prompts and experience review.

Structured outputs

Turns diagnostics into structured knowledge that later Skill retrieval, feature design, and model orchestration can all consume.

CastFeat: Feature Construction

CastFeat answers the question, "How should the data be transformed into model-ready representations?" It converts raw time series into forms that better match downstream models.

lag / rolling statistical features frequency-domain and multiscale representations patch / token embedding model-ready representation
How to think about it

CastFeat is not "manual feature engineering one more time." It unifies domain features, statistical features, and foundation-model input formats into a single representation-building pipeline.

CastZoo: Model Orchestration

CastZoo answers, "Which models should be used, and how should they be combined?" It is not only a model repository. It also handles strategy-aware scheduling.

Supported model families

Statistical models such as ARIMA, AutoARIMA, ETS, ExponentialSmoothing, SimpleExponentialSmoothing, Holt, HoltWinters, and Theta; machine learning models; deep learning models such as Informer and PatchTST; and foundation models such as Chronos, TimesFM, and Moirai.

Supported strategies

Single-model runs, multi-model ensembles, coarse-to-fine two-stage scheduling, or using foundation-model outputs as priors.

Skill and Experience Library

What a Skill Is

A Skill is an analyzed, validated, and reviewed strategy template. It describes which model families, tool combinations, search spaces, feature templates, and known risks fit a given context. It is both an executable strategy and the key asset layer through which CastClaw accumulates solving experience and releases reusable workflows.

Carry forward proven experience

Preserve validated rules, tool routes, and failure boundaries instead of starting from scratch every time.

Guide future tasks

Narrow both the model space and the workflow-choice space so Forecaster starts from a more reasonable baseline.

Keep humans in control

Review before use so the system evolves on top of trusted experience instead of automatically accumulating noise.

Skill File Structure

Skills are expressed in YAML. The core fields are applicability conditions, model family, search space, feature template, risks, and experience notes. You can think of a Skill as a reusable workflow fragment for a class of cases.

name: deep_learning_periodic
applicable_conditions:
  - strongly seasonal data
  - sequence length > 5000
model_family: deep_learning
models: [PatchTST, iTransformer]
search_space:
  learning_rate: [1e-4, 5e-4]
  patch_len: [16, 32, 64]
feature_template: patch_token
risks:
  - high overfitting risk when data volume is insufficient
domain_notes: ""
Review focus

Start with applicable_conditions and risks, then check whether validation evidence supports this route. These parts most directly determine whether the Skill should be used for the current task.

How to Review and Curate Skills

  1. Planner drafts 2 to 4 candidate Skills from pre-forecast analysis and candidate rules.
  2. Humans review the model route, applicability conditions, and risk notes, editing them directly when needed.
  3. Approved Skills enter .forecast/skills/ for reuse in the current and similar tasks.
  4. The library evolves over time and gradually becomes a team-level experience and workflow asset.
Review principle

Keep a small number of high-quality Skills rather than accumulating a large set of low-signal strategies. The value of the Skill library is trustworthiness, validation, and reuse, not size.

/cast-creation Command

Interactively generates the CAST.md project-constraint file. Use it before a task starts to define disallowed models, budget caps, evaluation preferences, and domain notes.

When to use it

Use it when you already know which models should be excluded, how many experiments the budget allows, or which domain notes must be injected for every agent.

What problem it solves

It avoids repeating the same constraints verbally in every run and reduces the chance that agents forget critical limits in later phases.

Examples

These three cases cover load, solar, and financial time series. The point is to build intuition for how different data shapes map to different experience patterns. Focus on the data profile, the recommended Skill path, and how Human in the Loop helps accumulate experience.

Power Load Forecasting (load.csv)

load.csv is the best starter dataset for a first demo. It contains hourly load values with stable daily and weekly cycles.

Data profile

Hourly frequency, roughly 15,000 samples, strong daily seasonality at 24 hours, strong weekly seasonality at 168 hours, and clear summer and winter peaks.

Recommended strategy

Start with a combined deep_learning path using PatchTST and iTransformer plus a foundation path using Chronos.

Expected outputs

If you see pre-forecast.md, the experiment directories, and final-report.md, the main workflow is running end to end.

Solar Power Forecasting

Solar generation combines strong daily seasonality, fixed nighttime zeros, and strong weather sensitivity. It is a canonical case where domain knowledge should participate in experience accumulation.

Data profile and diagnostic focus

This is hourly data from the GEFCom2014 Solar Track. CastSense should pay special attention to nighttime zeros, abrupt weather changes, and seasonal shifts.

Recommended experience and Human in the Loop

Start with a statistical plus foundation experience path using Theta together with TimesFM or Moirai. Human input matters most when labeling long cloudy periods and weather-abnormal days, because those labels define applicability boundaries.

Financial Time-Series Forecasting

Financial series are volatile, non-stationary, and sensitive to external shocks. They are not a good fit for blindly committing to a single deep-learning route and require stronger risk awareness and external-event injection.

Recommended strategy

Use a conservative statistical + foundation ensemble so the full budget is not concentrated on one path.

Where humans enrich experience

Mark earnings releases, policy announcements, and macro shocks, then use CastSense alerts on distribution drift and structural breaks to decide whether these events should enter the experience library.

FAQ & Troubleshooting

Common Questions

How do I switch LLM providers?

Update the model configuration in castclaw.json or switch the relevant environment variables.

How do I continue after a Human-in-the-Loop pause?

Enter feedback about evidence, applicability boundaries, or failure causes in the Forecaster tab and submit it. The system continues accumulating experience in the current context without reinitializing from scratch.

Where are Skill files managed?

They live in .forecast/skills/ by default. Stable reviewed Skills should be promoted into a shared team asset library.

Why are results unstable?

First check whether the task definition or budget is too small, then check for unlabeled anomalous dates, and only after that consider model optimization.

Environment Troubleshooting

SymptomWhat to Check
Bun version is too old Upgrade to 1.3.11 or later, reopen the terminal, and verify with bun --version.
Python backend errors Enter the Python directory and run uv sync to make sure dependencies are installed correctly.
API key is not taking effect Check whether the environment variable has been exported in the current shell, or confirm that castclaw.json overrides the model settings.
A phase will not advance Check whether .forecast/ is missing required files, especially task.json and the report artifacts for each phase.
This documentation is organized in the order of getting started first, understanding the system second, and checking details last. For a first CastClaw demo, start with your first forecasting task and Forecasting Workflow Learning Path.