geekgeekrun/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Package Manager

Always use proto run pnpm -- <args> instead of bare pnpm. The project requires pnpm >=8.15.9 <9.0.0; the system pnpm (10.x) is incompatible and will cause errors.

proto run pnpm -- install
proto run pnpm -- -F geekgeekrun-ui dev

Key Commands

All UI development happens in packages/ui. The dev/build/start scripts automatically rebuild sqlite-plugin first.

# Electron app (main entry point for users)
proto run pnpm -- -F geekgeekrun-ui dev          # development mode
proto run pnpm -- -F geekgeekrun-ui build         # production build
proto run pnpm -- -F geekgeekrun-ui build:win     # Windows installer

# Lint & format (run from packages/ui)
proto run pnpm -- -F geekgeekrun-ui lint          # eslint --fix
proto run pnpm -- -F geekgeekrun-ui format        # prettier --write

# Type checking (run from packages/ui)
proto run pnpm -- -F geekgeekrun-ui typecheck     # both node + web

# SQLite plugin (must build before UI if changed)
proto run pnpm -- -F @geekgeekrun/sqlite-plugin build
proto run pnpm -- -F @geekgeekrun/sqlite-plugin dev   # watch mode

Architecture

This is a pnpm monorepo (packages/*) — a desktop automation tool for BOSS Zhipin (job platform) built on Electron + Puppeteer.

Two Sides

Job-seeker side (older, more complete):

• packages/geek-auto-start-chat-with-boss — core automation: LLM-based resume matching, auto-chat
• packages/run-core-of-geek-auto-start-chat-with-boss — headless daemon entry point

Recruiter side (newer, under active development):

• packages/boss-auto-browse-and-chat — core automation: browse candidates, filter, send greetings, extract resumes via Canvas hook
• packages/run-core-of-boss-auto-browse — headless daemon entry point

Electron App (packages/ui)

The app uses mode-based process routing: every worker subprocess is actually the same Electron binary launched with a --mode flag. src/main/index.ts switches on runMode:

• No --mode (default) → opens the settings GUI window (OPEN_SETTING_WINDOW)
• bossRecommendMain / bossChatPageMain / bossAutoBrowseAndChatMain → recruiter workers
• geekAutoStartWithBossMain → job-seeker worker
• launchDaemon → background daemon process (manages worker subprocesses via @geekgeekrun/pm)

The GUI renderer is Vue 3 + Pinia + Vue Router served by electron-vite. IPC handlers live in src/main/flow/OPEN_SETTING_WINDOW/ipc/index.ts.

Plugin/Hook System

All automation cores (both sides) use tapable (AsyncSeriesHook, AsyncSeriesWaterfallHook) for extensibility. The sqlite-plugin and webhook features attach to these hooks:

Worker flow file
  → constructs hooks object
  → new SqlitePlugin(dbPath).apply(hooks)
  → calls core function (startBossAutoBrowse / startBossChatPageProcess / startGeekAutoChat)

Shared Packages

• packages/sqlite-plugin — TypeORM + better-sqlite3, compiled TypeScript (dist/). Entities: CandidateInfo, CandidateContactLog, ChatStartupLog. Must be built before UI.
• packages/utils — ESM utilities: sleep, OpenAI/GPT requests, Puppeteer helpers
• packages/pm — Electron multi-process daemon/worker management
• packages/laodeng / packages/puppeteer-extra-plugin-laodeng — anti-bot-detection Puppeteer plugin

Storage Layout

~/.geekgeekrun/
  config/
    boss-recruiter.json       # recruiter automation config
    candidate-filter.json     # candidate filter criteria
    webhook.json              # webhook integration config
  storage/
    boss-cookies.json         # persisted BOSS Zhipin cookies
    boss-local-storage.json   # persisted localStorage
    public.db                 # SQLite database

Recruiter Automation Stack (boss-auto-browse-and-chat)

Key files and their roles:

• index.mjs — startBossAutoBrowse(): browser launch, login, main loop
• candidate-processor.mjs — DOM parsing (#recommend-list > div > ul > li), candidate filtering
• chat-handler.mjs — clicking 打招呼 (button.btn-greet), handling popup (button.btn-sure-v2), processCandidate
• resume-extractor.mjs — network intercept + iframe Canvas fillText hook (MutationObserver pattern, see plan/cv_canvas_solution.md)
• constant.mjs — all CSS selectors and URLs; update here first when BOSS site HTML changes

Anti-detection: stealth + laodeng + anonymize-ua plugins; all clicks via ghost-cursor (createHumanCursor); random delays via sleepWithRandomDelay.

Known post-login popups — all must be auto-dismissed or automation will hang:

• Governance notice (dialog-uninstall-extension) — appears every login; handled by dismissGovernanceNoticeDialog(page) in index.mjs, called after login in both launchBrowserAndNavigateToChat and startBossAutoBrowse. Confirm button is div.confirm-btn (a <div> styled with a background image, not a <button>). See plan/recruiter_architecture.md §14.1 and examples/BOSS直聘-治理公告*.html.
• Intent dialog (.op-btn.rightbar-item div.dialog-container) — per-session, per-conversation; handled in chat-page-processor.mjs.
• When selectors break, update constant.mjs first, then follow the checklist in plan/recruiter_architecture.md §14.5.

Code Style

Enforced by eslint + prettier in packages/ui:

• No semicolons, single quotes, printWidth: 100, no trailing commas
• Vue 3 <script setup> SFC style
• .mjs files (automation core) are plain ESM, no TypeScript, no build step

Plan Documents

plan/ contains architecture decision documents intended for AI-assisted development:

• recruiter_architecture.md — high-level overview of the recruiter side
• recommend_page_flow.md — detailed DOM structure, selectors, and flow for the recommend page
• cv_canvas_solution.md — how BOSS Zhipin's WASM+Canvas resume protection works and how it's bypassed