haruLog

harulog는 Codex 대화 이력과 로컬 git 작업 흔적을 읽어서 글감과 초안을 추천하는 macOS용 CLI다. 배포 목표는 bunx harulog ... 한 줄로 어느 PC에서든 설정하고, launchd가 매주 금요일 오전 9시에 자동 실행되도록 만드는 것이다.

원하면 setup 단계에서 받는 이메일만 입력하고, Gmail 기준 기본값으로 결과를 이메일로도 받을 수 있다.

Quick Start

bunx harulog setup
bunx harulog run --force --ignore-history

기본 설정이 끝나면 사용자 데이터는 ~/Library/Application Support/harulog 아래에 저장된다.

• config.json: 사용자 설정
• state.json: 마지막 실행 상태
• topic_history.json: 최근 추천 이력
• outputs/: JSON/Markdown 결과
• logs/: scheduler 로그
• bin/: scheduler wrapper script

Commands

bunx harulog setup
bunx harulog run
bunx harulog run --force --ignore-history
bunx harulog scheduler install
bunx harulog scheduler status
bunx harulog doctor

• setup: 대화형 설정 마법사. Gemini 키, Codex 경로, git scan root, 받는 이메일, 스케줄을 저장하고 필요하면 launchd를 설치한다.
• run: 수동으로 1회 실행한다.
• run --scheduled: launchd용 실행 모드. 이번 주 금요일 09:00 스케줄 창이 열렸을 때만 동작한다.
• run --force: 스케줄 조건을 무시하고 강제로 실행한다.
• run --ignore-history: 최근 추천 이력을 무시하고 테스트용으로 다시 생성한다.
• scheduler install: ~/Library/LaunchAgents/com.harulog.weekly-topics.plist와 wrapper script를 설치한다.
• scheduler uninstall: launchd 등록과 wrapper script를 제거한다.
• scheduler status: 설치 상태와 plist/wrapper/log 경로를 보여준다.
• doctor: Bun, Gemini 키, Codex 경로, git repo 탐색, launchd 상태를 점검한다.

Email Delivery

setup에서 이메일 전송을 활성화하면 매 실행 성공 후 결과를 Gmail SMTP 기준으로 보낸다.

• 본문: 생성된 Markdown 결과
• 첨부: topics.md, topics.json (옵션으로 끌 수 있음)
• 전송 시점: run 또는 스케줄 실행이 성공적으로 끝난 직후
• setup에서 묻는 값: 발신 이메일, 발신 Gmail App Password, 받는 이메일

기본값은 아래처럼 잡힌다.

• SMTP_HOST=smtp.gmail.com
• SMTP_PORT=465
• SMTP_SECURE=true
• SMTP_USER
• EMAIL_FROM
• SMTP_PASS
• EMAIL_TO

Scheduler

자동 실행은 launchd LaunchAgent를 사용한다.

• 스케줄: 매주 금요일 09:00
• RunAtLoad: 로그인 직후 catch-up 실행
• wrapper: ~/Library/Application Support/harulog/bin/run-weekly.sh
• 실제 실행 명령: 설치 시점 버전으로 고정된 bun x --bun harulog@<version> run --scheduled

즉 scheduler는 “항상 최신”이 아니라 설치 시점 패키지 버전을 고정해서 실행한다.

Config

setup이 만드는 기본 설정 구조는 아래와 같다.

{
  "llmProvider": "gemini",
  "geminiModel": "gemini-2.5-flash",
  "geminiApiKeySource": "config",
  "codexHome": "/Users/me/.codex",
  "localGitRepos": [],
  "localGitScanRoots": [
    "/Users/me/Documents/work"
  ],
  "localGitScanDepth": 2,
  "schedule": {
    "weekday": 5,
    "hour": 9
  },
  "topicCount": 5,
  "recommendationWindowDays": 14,
  "email": {
    "enabled": false,
    "smtpHost": "smtp.gmail.com",
    "smtpPort": 465,
    "smtpSecure": true,
    "smtpUser": "[email protected]",
    "smtpPass": "app-password",
    "from": "[email protected]",
    "to": [
      "[email protected]"
    ],
    "subjectPrefix": "harulog",
    "attachOutputs": true
  }
}

Gemini API 키는 기본적으로 config.json에 저장할 수 있고, GEMINI_API_KEY 또는 GOOGLE_API_KEY 환경변수가 있으면 그 값이 우선한다.

Development

repo 안에서 개발할 때는 아래 명령을 쓴다.

bun install
bun run dev
bun run job:weekly
bun run job:weekly:force
bun run src/cli.ts help
bun run check

• job:weekly: CLI의 run --scheduled와 같다.
• job:weekly:force: CLI의 run --scheduled --force와 같다.
• job:daily, job:daily:force: 이전 이름과의 호환 alias다.

Optional Env Overrides

repo 개발이나 디버깅용으로는 .env.example에 있는 환경변수 override를 사용할 수 있다.

• HARULOG_HOME
• HARULOG_LAUNCH_AGENTS_DIR
• GEMINI_API_KEY / GOOGLE_API_KEY
• EMAIL_ENABLED
• SMTP_HOST / SMTP_PORT / SMTP_SECURE
• SMTP_USER / SMTP_PASS
• EMAIL_FROM / EMAIL_TO
• EMAIL_SUBJECT_PREFIX
• EMAIL_ATTACH_OUTPUTS
• CODEX_HOME
• LOCAL_GIT_REPOS
• LOCAL_GIT_SCAN_ROOTS
• LOCAL_GIT_SCAN_DEPTH
• TOPIC_COUNT
• RECOMMENDATION_WINDOW_DAYS
• SCHEDULE_WEEKDAY
• SCHEDULE_HOUR
• LLM_PROVIDER