🌤️ ShadowClaw Agent CLI Weather #

A lightweight, modular, headless weather station, multi-day forecasting engine, and outdoor operational advisor built for practical forecasting workflows. Powered by ShadowClaw headless CLI agents, Open-Meteo, and standard Unix streams.

Fully model-agnostic: works seamlessly with any configured model provider (including local models via Ollama or Transformers.js, or cloud providers such as OpenRouter, Anthropic, or OpenAI).

🌤️ Live Automated Weather Briefing — Chicago, IL #

✨ Key Capabilities #

• 🤖 Automated CLI Agent: Autonomous batch weather retrieval, data synthesis, and actionable outdoor advisories driven by ShadowClaw CLI.
• 🎯 Precision Tool Scoping: Avoids prompt and schema bloat by explicitly scoping tools (--tools "fetch_url" for retrieval, --tools none for downstream synthesis). Keeps token consumption minimal and execution deterministic.
• ⏱️ Operational Window Scanner: Hourly condition evaluator (bin/scan-window.mjs) parses 168+ consecutive forecast hours to identify exact windows meeting custom criteria (e.g., temperature thresholds, dew point spread, duration).
• 🔗 Unix Pipe Composability: Chain report outputs directly into subsequent agent queries using standard Unix pipelines (./bin/weather-now.sh | ./bin/weather-ask.sh "Do I need a coat?").
• 🌍 Location Agnostic: Out-of-the-box fallback to Chicago, Illinois, with instant geocoding resolution for any global location and persistent default location configuration.
• 🌐 Well-Known Agent Skills Discovery: Publishes standardized declarative tools and skills over HTTPS for external autonomous agents and remote discovery clients at https://xt-ml.github.io/shadow-claw-agent-cli-weather/.well-known/agent-skills/index.json.
• 📥 CLI Agent Import Compatible: Compatible with shadow-claw agent import—any external ShadowClaw agent can discover, import, and execute these weather tools natively with a single command.

🚀 Quick Start #

1. Initialize Your ShadowClaw Agent #

ShadowClaw CLI lets you configure your preferred inference provider on first run:

# Initialize workspace agent (select your preferred provider and model)
npx shadow-claw agent init

💡 Model Selection: You can configure any supported provider during initialization (including OpenRouter, Ollama, Anthropic, OpenAI, or any OpenAI-compatible endpoint).

2. Run Instant Weather Reports #

# Current conditions for default location (Chicago, IL)
./bin/weather-now.sh

# 7-day forecast for Chicago
./bin/weather-forecast.sh

# On-the-fly query for any global location
./bin/weather-now.sh "New York, New York, United States"

3. Generate HTML for GitHub Pages #

Whenever README.md or tools change, regenerate the static index.html:

./bin/build-html.mjs

🛠️ Script Catalog #

All executable scripts reside in bin/ and save structured markdown outputs into reports/:

🌐 Shared Well-Known Agent Skills & Declarative Tools #

This repository publishes and advertises standardized declarative tools and skills exclusively for external AI agents, autonomous clients, and remote systems via well-known agent skills discovery.

Published Discovery Endpoint #

The canonical public endpoint advertised for external consumers is:

https://xt-ml.github.io/shadow-claw-agent-cli-weather/.well-known/agent-skills/index.json

Declarative Tools Catalog #

The repository exposes four sandboxed, zero-dependency declarative JavaScript tools in .agents/tools/main/:

In addition, the bundled ShadowClaw skill skill-creator is indexed for creating, authoring, and validating skills.

Remote Agent Discovery & Inspection #

External autonomous agents and discovery clients can inspect our published capabilities directly over HTTPS:

# Fetch and inspect the live discovery index
curl -s https://xt-ml.github.io/shadow-claw-agent-cli-weather/.well-known/agent-skills/index.json | jq .

# Inspect an individual declarative tool manifest directly
curl -s https://xt-ml.github.io/shadow-claw-agent-cli-weather/.agents/tools/main/get_current_weather.json | jq .

📥 Importing into External ShadowClaw CLI Agents #

External ShadowClaw agents can import our published declarative tools directly using the CLI agent import command:

# 1. Import all published weather tools and skills directly into your agent workspace
npx shadow-claw agent import https://xt-ml.github.io/shadow-claw-agent-cli-weather/

# Or import from the explicit discovery endpoint
npx shadow-claw agent import https://xt-ml.github.io/shadow-claw-agent-cli-weather/.well-known/agent-skills/index.json

# 2. Selectively import specific tools
npx shadow-claw agent import https://xt-ml.github.io/shadow-claw-agent-cli-weather/ --tools "get_current_weather,get_weather_forecast"

# 3. List tools in your agent workspace to verify
npx shadow-claw agent tools

# 4. Inspect an imported declarative tool definition
npx shadow-claw agent tool get_current_weather

# 5. Execute an imported tool directly from the CLI
npx shadow-claw agent tool get_current_weather '{"latitude": 41.8781, "longitude": -87.6298}'

# 6. Run an agent prompt with the imported tool enabled
npx shadow-claw agent run --tools "get_current_weather" "What is the current temperature and conditions in Chicago?"

📖 Usage Examples #

1. Current Conditions #

# Check current weather for default location (Chicago, IL)
./bin/weather-now.sh

# Check current weather for New York
./bin/weather-now.sh "New York, New York, United States"

# Or use the --location flag
./bin/weather-now.sh --location "London, United Kingdom"

2. Multi-Day Forecasts #

# 7-day forecast for default location
./bin/weather-forecast.sh

# 3-day forecast for New York
./bin/weather-forecast.sh 3 "New York, New York, United States"

# 14-day extended outlook for Chicago
./bin/weather-forecast.sh 14

3. Persistent Default Location Management #

Configure your home station once—all scripts will respect it automatically:

# View active default location
./bin/set-default-location.sh

# Change persistent default to New York
./bin/set-default-location.sh "New York, New York, United States"

# Reset back to factory default (Chicago, IL)
./bin/set-default-location.sh --reset

4. Operational Window Scanner (Cold-Sensitive & Exterior Tasks) #

Identify exact multi-hour windows meeting strict operational criteria across 168 forecast hours:

# Find a 24-hour window above 2°C with at least 3°C dew point spread (exterior staining/curing):
./bin/weather-window.sh "temperature above 2C and at least 3C above the dew point for 24 hours"

# Find calm, dry windows for aerial spraying or lawn seeding:
./bin/weather-window.sh "no precipitation and wind under 15 km/h" "Chicago, Illinois"

5. Unix Pipe Composability & Zero-Noise Follow-Ups #

Ask follow-up questions on existing data without re-fetching or wasting tokens:

# Pipe current weather snapshot into ask engine:
cat reports/weather-now.md | ./bin/weather-ask.sh "Do I need a warm jacket this evening?"

# Pipe 7-day forecast to find the best day for outdoor projects:
cat reports/weather-forecast.md | ./bin/weather-ask.sh "Which day this week has the lowest wind and zero rain?"

# Chain current weather directly into a clothing recommendation:
./bin/weather-now.sh | ./bin/weather-ask.sh "Give me a 1-sentence commuter recommendation."

6. Highway Travel & Road Hazards #

# General driving hazard outlook from Chicago
./bin/weather-travel.sh

# Specific corridor check
./bin/weather-travel.sh "drive to Milwaukee via I-94"
./bin/weather-travel.sh "drive to Indianapolis via I-65"

7. External CLI Agent Integration (Import & Zero-Code Tooling) #

Any standalone or remote ShadowClaw agent can import and use our weather station tools without cloning the repository or writing integration glue:

# In your own agent's project or workspace:
npx shadow-claw agent import https://xt-ml.github.io/shadow-claw-agent-cli-weather/

# Query Chicago weather directly via the imported declarative tool
npx shadow-claw agent tool get_current_weather

# Query forecast for custom coordinates (e.g. New York: 40.7128, -74.0060)
npx shadow-claw agent tool get_weather_forecast '{"latitude": 40.7128, "longitude": -74.006, "forecast_days": 3}'

# Ask the agent for weather analysis using the imported tools
npx shadow-claw agent run --tools "get_current_weather,get_weather_forecast" "Compare current conditions with the 3-day forecast outlook"

⚙️ Architecture & Operational Principles #

1. Explicit Tool Scoping (--tools) #

When executing batch agent steps with shadow-claw agent run, injecting all default built-in tools balloons context tokens and can cause models to execute unnecessary tools.

• Data Ingestion Step: Passes strictly --tools "fetch_url". The agent calls Open-Meteo, ingests raw data, formats markdown, and exits.
• Synthesis / Follow-Up Step: Passes --tools none. All tool schemas are stripped from the prompt, leaving 100% of context capacity for weather reports and instant synthesis.

2. Lightweight Node.js Processing #

All geocoding, coordinate transformation, hourly condition scans, and static site rendering run directly in standard Node.js scripts (bin/resolve-location.mjs, bin/scan-window.mjs, bin/summarize-forecast.mjs, bin/build-html.mjs) without extra external dependencies.

3. Declarative Tools & Sandboxed Execution #

Declarative tool manifests in .agents/tools/main/ use standard JSON schemas and JavaScript execution definitions. They run deterministically inside worker sandboxes without granting unrestricted OS shell privileges.

4. Static Hosting on GitHub Pages with .nojekyll #

Because GitHub Pages defaults to Jekyll, dot-directories (.well-known and .agents) would otherwise be suppressed. The root .nojekyll file ensures direct public access to discovery schemas and tool definitions. Pre-rendering index.html guarantees instant browser viewing without requiring Jekyll compilation.

License #

AGPL-3.0