{"skill":{"slug":"vehicle-tracker","displayName":"Vehicle Expense Tracker","summary":"Track vehicle expenses (gas, maintenance, parts) in Google Sheets and save related photos. Handles mileage, cost, category, and photo organization.","description":"---\nname: vehicle-tracker\ndescription: Track vehicle expenses (gas, maintenance, parts) in Google Sheets and save related photos. Handles mileage, cost, category, and photo organization.\n---\n\n# Vehicle Expense Tracker\n\nA multi-language vehicle expense tracking tool that supports Google Sheets and local Excel files.\n\n## Features\n\n- **i18n Support**: Multiple languages via locale files (`locales/*.json`)\n- **Google Sheets Integration**: Write directly to Google Sheets via API\n- **Local Excel Fallback**: Saves to local `.xlsx` files if no Spreadsheet ID configured\n- **Metric/Imperial Units**: Configurable unit system (km/L vs mi/gal)\n- **Photo Management**: Auto-saves and renames photos with timestamps\n- **Aliases**: Support vehicle aliases (e.g., \"my car\" → \"Toyota Camry 2020\")\n- **Defaults**: Auto-fill quantity and unit based on category\n\n---\n\n## 🚀 Initialization (First-Time Setup)\n\n### Step 1: Choose Your Locale\n\nAvailable locales:\n- `zh-TW` - 繁體中文 (Taiwan)\n- `en-US` - English (US)\n- `ja-JP` - 日本語\n\n### Step 2: Create config.json\n\nCopy the template below and save as `skills/vehicle-tracker/config.json`:\n\n```json\n{\n  \"locale\": \"en-US\",\n  \"unit_system\": \"metric\",\n  \"vehicles\": {},\n  \"aliases\": {},\n  \"default_vehicle\": null,\n  \"category_defaults\": {}\n}\n```\n\n### Step 3: Copy Category Defaults from Locale\n\nBased on your chosen locale and unit system, copy the appropriate category defaults.\n\n**For English (metric):**\n```json\n{\n  \"category_defaults\": {\n    \"Gas\": { \"unit\": \"liter\" },\n    \"Accessory\": { \"unit\": \"pc\", \"quantity\": 1 },\n    \"Repair\": { \"unit\": \"job\", \"quantity\": 1 },\n    \"Maintenance\": { \"unit\": \"service\", \"quantity\": 1 },\n    \"Purchase\": { \"unit\": \"unit\", \"quantity\": 1 }\n  }\n}\n```\n\n**For English (imperial):**\n```json\n{\n  \"category_defaults\": {\n    \"Gas\": { \"unit\": \"gallon\" },\n    \"Accessory\": { \"unit\": \"pc\", \"quantity\": 1 },\n    \"Repair\": { \"unit\": \"job\", \"quantity\": 1 },\n    \"Maintenance\": { \"unit\": \"service\", \"quantity\": 1 },\n    \"Purchase\": { \"unit\": \"unit\", \"quantity\": 1 }\n  }\n}\n```\n\n**For 繁體中文 (metric):**\n```json\n{\n  \"category_defaults\": {\n    \"加油\": { \"unit\": \"公升\" },\n    \"周邊\": { \"unit\": \"個\", \"quantity\": 1 },\n    \"維修\": { \"unit\": \"件\", \"quantity\": 1 },\n    \"保養\": { \"unit\": \"次\", \"quantity\": 1 },\n    \"買車\": { \"unit\": \"輛\", \"quantity\": 1 }\n  }\n}\n```\n\n**For 日本語 (metric):**\n```json\n{\n  \"category_defaults\": {\n    \"給油\": { \"unit\": \"リットル\" },\n    \"アクセサリー\": { \"unit\": \"個\", \"quantity\": 1 },\n    \"修理\": { \"unit\": \"件\", \"quantity\": 1 },\n    \"メンテナンス\": { \"unit\": \"回\", \"quantity\": 1 },\n    \"購入\": { \"unit\": \"台\", \"quantity\": 1 }\n  }\n}\n```\n\n### Step 4: Add Your Vehicle\n\n**Option A: Google Sheets (recommended for cloud sync)**\n\n1. Create a Google Spreadsheet\n2. Share it with a Google Service Account (see `google-workspace` skill)\n3. Add the Spreadsheet ID to config:\n\n```json\n{\n  \"vehicles\": {\n    \"My Car 2020\": \"1ABC123...xyz\"\n  },\n  \"default_vehicle\": \"My Car 2020\"\n}\n```\n\n**Option B: Local Excel (no setup required)**\n\nJust add the vehicle name without an ID:\n\n```json\n{\n  \"vehicles\": {\n    \"My Car 2020\": null\n  },\n  \"default_vehicle\": \"My Car 2020\"\n}\n```\n\nFiles will be saved to `~/vehicle_tracker/My_Car_2020.xlsx`.\n\n### Step 5: Add Aliases (Optional)\n\n```json\n{\n  \"aliases\": {\n    \"car\": \"My Car 2020\",\n    \"toyota\": \"My Car 2020\"\n  }\n}\n```\n\n### Step 6: Custom Paths (Optional)\n\nOverride default directories:\n\n```json\n{\n  \"photo_base_dir\": \"/path/to/photos\",\n  \"local_excel_dir\": \"/path/to/excel/files\",\n  \"sheet_name\": \"Expenses\"\n}\n```\n\nDefault paths: `~/vehicle_tracker`\n\n---\n\n## Complete config.json Example\n\n```json\n{\n  \"locale\": \"en-US\",\n  \"unit_system\": \"imperial\",\n  \"vehicles\": {\n    \"Toyota Camry 2020\": \"1ABC123...spreadsheet_id\",\n    \"Honda Civic 2018\": null\n  },\n  \"aliases\": {\n    \"camry\": \"Toyota Camry 2020\",\n    \"civic\": \"Honda Civic 2018\",\n    \"car\": \"Toyota Camry 2020\"\n  },\n  \"default_vehicle\": \"Toyota Camry 2020\",\n  \"category_defaults\": {\n    \"Gas\": { \"unit\": \"gallon\" },\n    \"Accessory\": { \"unit\": \"pc\", \"quantity\": 1 },\n    \"Repair\": { \"unit\": \"job\", \"quantity\": 1 },\n    \"Maintenance\": { \"unit\": \"service\", \"quantity\": 1 },\n    \"Purchase\": { \"unit\": \"unit\", \"quantity\": 1 }\n  },\n  \"photo_base_dir\": \"~/vehicle_tracker\",\n  \"local_excel_dir\": \"~/vehicle_tracker\"\n}\n```\n\n---\n\n## Usage\n\n### Preview (Dry Run) - Always do this first!\n\n```bash\npython3 skills/vehicle-tracker/tracker.py \\\n  --vehicle \"camry\" \\\n  --mileage 15000 \\\n  --category \"Gas\" \\\n  --cost 45.50 \\\n  --quantity 12.5 \\\n  --dry-run\n```\n\n### Execute (After user confirms)\n\n```bash\npython3 skills/vehicle-tracker/tracker.py \\\n  --vehicle \"camry\" \\\n  --mileage 15000 \\\n  --category \"Gas\" \\\n  --cost 45.50 \\\n  --quantity 12.5\n```\n\n### With Photos\n\n```bash\npython3 skills/vehicle-tracker/tracker.py \\\n  --vehicle \"camry\" \\\n  --mileage 15200 \\\n  --category \"Maintenance\" \\\n  --cost 89.99 \\\n  --description \"Oil change\" \\\n  --photos \"/path/to/receipt.jpg\" \\\n  --dry-run\n```\n\n---\n\n## Arguments\n\n| Argument | Required | Description |\n|----------|----------|-------------|\n| `--vehicle` | Optional | Vehicle name or alias. Uses default if omitted. |\n| `--mileage` | Required | Current odometer reading |\n| `--category` | Required | Expense category |\n| `--cost` | Required | Expense amount (currency symbols auto-removed) |\n| `--quantity` | Optional | Quantity (uses default if available) |\n| `--unit` | Optional | Unit (uses category mapping if available) |\n| `--date` | Optional | Date YYYY-MM-DD (defaults to today) |\n| `--description` | Optional | Additional notes |\n| `--photos` | Optional | Photo file paths to save |\n| `--dry-run` | Flag | Preview only, no write |\n\n---\n\n## Adding a New Locale\n\nCreate `locales/{code}.json` based on existing locale files. Required fields:\n\n- `language_name`\n- `sheet_name`\n- `columns_metric` / `columns_imperial`\n- `photo_prefix`\n- `messages`\n- `units_metric` / `units_imperial`\n- `default_units_metric` / `default_units_imperial`\n\n---\n\n## Supported Locales\n\n| Code | Language | Unit Systems |\n|------|----------|--------------|\n| `zh-TW` | 繁體中文 | metric, imperial |\n| `en-US` | English (US) | metric, imperial |\n| `ja-JP` | 日本語 | metric, imperial |\n","topics":["Google Sheets","Expense"],"tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":2019,"installsAllTime":76,"installsCurrent":1,"stars":1,"versions":1},"createdAt":1770011796089,"updatedAt":1778485987525},"latestVersion":{"version":"1.0.0","createdAt":1770011796089,"changelog":"Initial release of vehicle-tracker.\n\n- Track vehicle expenses (gas, maintenance, parts) with support for Google Sheets and local Excel files.\n- Supports multiple languages and unit systems (metric/imperial).\n- Organizes expense photos and auto-renames them with timestamps.\n- Allows configurable vehicle aliases, default values per expense category, and custom save paths.\n- Includes detailed setup and configuration instructions for first-time users.","license":null},"metadata":null,"owner":{"handle":"huchengtw","userId":"s172rb90x8xjxeeywezw47bddd88594e","displayName":"huchengtw","image":"https://avatars.githubusercontent.com/u/1418929?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1779935196725}}