dancing-bear: Instructions file for Claude Code

Claude Code Project Instructions

Project Overview

Personal Assistants: unified, dependency-light CLIs for personal workflows across mail, calendars, schedules, phone layouts, resumes, and WhatsApp. Built to be safe by default (plan and dry-run first), with a single YAML source of truth for Gmail and Outlook filters.

Constraints: Python 3.11, dependency-light, stable public CLI

Self-contained: All helpers and utilities are repo-internal. External dependencies are minimal and lazily imported. This design ensures public CLI backwards compatibility and reduces fragility from external package changes. Internal APIs can be refactored freely—update all call sites atomically without backwards-compatible wrappers.

Primary consumers: LLM agents — CLI schemas, help text, and agentic capsules are designed for token-efficient LLM consumption. Keep output terse and accurate.

Quick Start

# Setup
make venv

# Run tests
make test

# CLI help
./bin/assistant <mail|calendar|schedule|resume|phone|whatsapp|maker> --help
./bin/mail --help
./bin/calendar --help

Architecture

src/                      # all Python source packages (installable via package-dir=src)
  mail/                   # Gmail/Outlook providers, CLI wiring, helpers
  calendars/              # Outlook calendar CLI + Gmail scans
  schedule/               # plan/apply calendar schedules
  resume/                 # extract/summarize/render resumes
  phone/                  # iOS layout tooling
  whatsapp/               # local-only ChatStorage search
  desk/                   # desktop/workspace tooling
  maker/                  # utility generators
  charts/                 # render time-series charts from JSON (line/bar/area/dual)
  diagrams/               # Mermaid diagram generation (flowchart/sequence/gantt/pie; telemetry cost/token pies)
  slides/                 # generate PowerPoint decks from YAML deck definitions
  sheets/                 # generate styled .xlsx spreadsheets from YAML workbook definitions
  workflow/               # YAML DAG workflow engine (parse/compile/run/lint/list/status)
  core/                   # shared helpers
  telemetry/              # Claude Code session telemetry (cost, tokens, TUI)
  worker/                 # background job queue and daemon
  apple_music/            # Apple Music CLI
  wifi/                   # Wi-Fi CLI
  qlty/                   # qlty scan/triage wrapper (tiers findings by remediation strategy)
bin/                      # entry wrappers and helper scripts
tests/                    # lightweight unittest suite
.llm/                     # LLM context, flows, capsules
configs/                  # runtime config templates (e.g. launchd plist)
out/                      # legacy/opt-in outputs (`--out-dir out`); default is outside the checkout