# Ccal

> Chinese Calendar with Lunar-Solar Conversion

- Skill: `x-cmd/ccal` (Agent Skill, multi-file: 30 files)
- Install (CLI): `npx skillmds@latest add x-cmd/ccal`
- Raw SKILL.md: https://api.skillmd.com/api/skills/x-cmd/ccal/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity, Coding & Dev Tools
- Author: x-cmd (https://skillmd.com/u/x-cmd)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/x-cmd/ccal

---


## Overview

ccal is a Chinese calendar module that provides:
- Gregorian and lunar calendar conversion
- Solar terms (节气)
- Traditional Chinese holidays
- Almanac guidance (黄历宜忌)
- Heavenly Stems and Earthly Branches (干支)
- Six-day cycle (六曜)
- Duty star (值星)

## AI Agent Usage

### Output Modes

| Mode | Command | Use Case |
|------|---------|----------|
| **YML** (default in pipe) | `x ccal info <date>` | AI parsing, structured key-value output |
| **TSV** | `x ccal info --tsv <date>` | Piping to other tools, tab-separated |
| **CSV** | `x ccal info --csv <date>` | Spreadsheet import |
| **TTY** (default in terminal) | `x ccal info --tty <date>` | Human viewing, colorful calendar draw |

### Auto-Detection

When output is not a TTY (piped to another process):
- Automatically outputs YML format
- Same as calling `x ccal info --yml <date>`

When output is a TTY (interactive terminal):
- Uses `x ccal draw` to render colorful calendar
- Same as calling `x ccal info --tty <date>`

### Basic Examples

```bash
# AI: Get today's date info (auto-detects pipe vs terminal)
x ccal info

# AI: Get specific date in YML format
x ccal info --yml 2025-05-09

# AI: Parse YML output with your favorite tool
x ccal info --yml 2025-05-09 | grep "jianchu"

# TSV format (tab-separated)
x ccal info --tsv 2025-05-09

# CSV format (comma-separated)
x ccal info --csv 2025-05-09

# Force TTY mode even in pipe
x ccal info --tty 2025-05-09
```

### YML Output Format

```yaml
date: 2025-05-09
lunar_date: 2025-4-12
lunar_daycount: 29
jianchu: 收
weekday: 五
bazi: 乙巳 辛巳 戊寅
jieqi: 无
jieqi_next: 小满 (5, 21)
holiday: 无
xiuxi: 无
related: 无
yi: 结网 解除 馀事勿取
ji: 诸事不宜
```

### YML Field Descriptions

| Field | Description | Example |
|-------|-------------|---------|
| date | Gregorian date (YYYY-MM-DD) | 2025-05-09 |
| lunar_date | Lunar date (YYYY-M-D) | 2025-4-12 |
| lunar_daycount | Days in lunar month (29/30) | 29 |
| **jianchu** | **值星** (auspicious/inauspicious star) | 收/满/定/执... |
| weekday | Day of week (一-日) | 五 |
| bazi | Year/Month/Day Heavenly Stems | 乙巳 辛巳 戊寅 |
| **jieqi** | Solar term | 立夏/清明/无 |
| jieqi_next | Next solar term with date | 小满 (5, 21) |
| holiday | Holiday name | 劳动节/无 |
| xiuxi | 休(holiday)/工(workday)/空 | 休 |
| related | Holiday adjustment info | 劳动节 2025-05-01 |
| **yi** | **宜** (auspicious activities) | 出行 嫁娶 安葬... |
| **ji** | **忌** (inauspicious activities) | 动土 破土 祈福... |

### Key Fields for AI

**值星 (jianchu)** - Duty star for the day:
- 吉: 满/平/定/执 (auspicious)
- 凶: 收/破 (inauspicious)

**宜 (yi)** - Auspicious activities for the day
**忌 (ji)** - Inauspicious activities for the day

**六曜 (liuyao)** - Six-day cycle:
- 大安 ( auspicious)
- 赤口 (inauspicious)
- 先胜/友引/先负/佛灭

## Data Format (TSV)

The raw TSV data has 13 columns:

```
date    lunar_date  daycount  jianchu  wd  bazi         jieqi  jieqi_next  holiday  xiuxi  related    yi               ji
2025-05-09  2025-4-12  29       收       五   乙巳 辛巳 戊寅  无    小满 (5, 21)  无     无    无       结网 解除 馀事勿取  诸事不宜
```

## Data Source

### Archive Location

```
$___X_CMD_ROOT_DATA/ccal/data/
├── ccal-data-v0.0.6.tar.xz      # Main archive (stream-read, not extracted)
└── v0.0.6/cache/                # Pre-extracted index (after first run)
    ├── year.tsv                  # Year index
    └── month.tsv                 # Month index
```

### Download

- **URL**: https://codeberg.org/x-cmd/ccal-data/releases/download/v0.0.6/ccal-data.tar.xz
- **Trigger**: First run or `x ccal lunar update`

### Archive Contents

```
ccal-data/
├── index/
│   ├── year.tsv      # Year index
│   └── month.tsv     # Month index
└── lunar/
    └── {year}_{month}.tsv   # Monthly data (e.g., 2026_03.tsv)
```

### Direct Read (No Extraction)

```bash
DATA="$___X_CMD_ROOT_DATA/ccal/data/ccal-data-v0.0.6.tar.xz"

# Read specific month: 2026 March
x zuz cat "$DATA" ccal-data/lunar/2026_03.tsv

# Read all months of 2026
x zuz cat "$DATA" ccal-data/lunar/2026_*.tsv
```

## Reference

- `lib/awk/lunar.awk` - Lunar calendar computation
- `lib/awk/gongli.awk` - Gregorian calendar computation
- `lib/awk/ccal.awk` - Main calendar logic