🦞 Claudoro: Open-Source Developer Focus Timer

Claudoro is an open-source desktop focus timer for developers, built with Electron + React. It combines Pomodoro and deep-focus timing with GitHub activity context in one terminal-style UI.

Quick Links

• Star on GitHub
• Issues / Feedback

Why Claudoro

• Terminal-inspired developer UX (clear, minimal, low-noise)
• Focus modes: Pomodoro / Short Break / Long Break / Deep Focus
• Session stats + streak tracking
• Optional GitHub integration for contributions and activity context
• Local-first setup via npm install and npm run dev

Run From Source (Primary Distribution)

Prerequisite: Node.js 22.12+

git clone https://github.com/starlash7/Claudoro.git
cd Claudoro
npm install
npm run dev

Production build:

npm run build

Discoverability Setup (GitHub)

Set your repository metadata like this:

• Description: Developer focus timer with GitHub activity sync for visible daily momentum.
• Topics: pomodoro, focus-timer, electron, react, productivity, developer-tools, github-integration

Promotion channels:

• Show HN
• Reddit (r/programming, r/productivity, r/SideProject)
• X (Twitter)
• Dev.to
• Product Hunt

Launch copy templates are in docs/LAUNCH_PLAYBOOK.md.

Open Source Growth Loop

1. Keep repository description and topics up to date.
2. Ship one visible improvement every week and post changelog screenshots.
3. Convert issues into public roadmap milestones.
4. Ask for specific feedback in every launch post (onboarding, timer UX, GitHub sync).
5. Pin the repo and post progress clips on X/Reddit/Dev.to consistently.

Product Highlights

• Focused timer modes Pomodoro, Short Break, Long Break, and Deep Focus (count-up mode).
• Mascot-driven feedback The mascot reacts to your current state: idle, focusing, break, and complete.
• Daily goal flow Set today’s goal, mark it complete, and review goal history over time.
• Streak and progress visibility Track completed sessions, focus minutes, and streak performance in one view.
• GitHub context (optional) Connect GitHub to see commits, PRs, and issue context while you work. The streak heatmap is shown as a full current-year view (January to December).

Focus Modes

Mode	Duration	Purpose
Focus (Pomodoro)	25 min	Deep work sprint
Short Break	5 min	Quick reset
Long Break	15 min	Recovery after cycles
Deep Focus	Unlimited	Manual, uninterrupted flow

Cycle logic:

• After each Focus session: Short Break
• Every 4th Focus completion: Long Break
• After a break: back to Focus

Who It's For

• Developers who want a clean desktop Pomodoro timer
• Builders who prefer terminal-style interfaces over gamified UIs
• People who want focus stats and GitHub context in one app

GitHub Connection (Optional)

1. Open Settings in Claudoro.
2. Choose mode:
   • Account: profile-wide contribution graph
   • Repository: repo-level commits, PRs, issues
3. Enter your GitHub token.
4. If using Repository mode, enter repository (repo or owner/repo).
5. Save and refresh the GitHub panel.

Heatmap behavior:

• Displays the current year in calendar order (Jan to Dec)
• Uses a single timeline (no year switcher)

GitHub token is stored in your OS secure keychain when available, with an encrypted local fallback for environments where native keychain modules are unavailable. Other GitHub settings are stored locally on your device.

Release Docs

• QA checklist: docs/RELEASE_QA_CHECKLIST.md (optional, release mode)
• Pipeline guide: docs/RELEASE_PIPELINE.md (optional, release mode)
• Launch playbook: docs/LAUNCH_PLAYBOOK.md

Roadmap

• Team leaderboard for shared focus tracking
• Optional cloud sync for multi-device continuity
• More session insights and weekly review surfaces

---

Built with Electron, React, Zustand, and Tailwind CSS.