FocusFlow

A Chrome productivity workspace for understanding your browsing habits, reducing distractions, and building consistent deep-work routines.

FocusFlow brings screen-time tracking, website blocking, a Pomodoro timer, tasks, notes, video-speed controls, dark mode, and productivity insights into one browser extension.

What you can do with FocusFlow

Workspace	What it is for
Home	A minimal overview of your current browsing activity and quick controls
Focus	Smart Focus sessions, daily goals, Pomodoro timer, tasks, and quick notes
Tools	Block distracting websites, adjust video speed, and enable website dark mode
Insights	Review activity, streaks, achievements, productivity score, coding activity, and reports
Settings	Manage preferences, export or restore data, and reset data

Install FocusFlow

FocusFlow is currently loaded in Chrome as an unpacked extension.

Download the repository: click Code → Download ZIP on GitHub, then extract it. Alternatively, clone it:
```
git clone https://github.com/cosmiccoder200x-sys/Focusflow.git
```
Open Chrome and visit chrome://extensions.
Turn on Developer mode (top-right).
Select Load unpacked.
Choose the extension folder inside the extracted/cloned repository. Choose the folder that contains manifest.json, not the repository root.
Pin FocusFlow from Chrome's Extensions menu so it is easy to open.

Repository layout:

Focusflow/
├── extension/       # Load this folder in Chrome
│   ├── manifest.json
│   ├── background.js
│   ├── popup.html
│   ├── popup.css
│   ├── popup.js
│   ├── options.html
│   └── ...
├── api/              # Optional backend for sync
├── package.json
└── README.md

Note: FocusFlow is a browser extension, not a standalone website. The extension's core local features do not require you to deploy the optional backend.

Your first five minutes

Open FocusFlow: click the pinned FocusFlow icon in Chrome.
Check Home: get familiar with the overview and quick controls.
Add a task: open Focus → Tasks, enter one small task, and add it.
Start a focus session: open Focus → Timer, choose your study and break durations, then press Start.
Review your activity: after browsing or studying, visit Insights → Activity or Insights → Reports.
Protect your data: open Settings and create a JSON backup.

You can use the extension gradually. You do not need to configure every tool before starting.

How to use each workspace

1. Home — your daily overview

See the currently tracked website and today's tracked screen time.
Use Website dark mode to toggle dark mode for the current website.
Use the video-speed shortcuts when a supported video is open.
Keep Home as your quick check-in; open the other workspaces when you need more detail.

Tip: Screen-time tracking follows the active browser tab. It measures time in the browser, not time spent working away from the computer.

2. Focus — timer, tasks, and notes

Pomodoro timer

Open Focus → Timer.
Set your study duration (default: 25 minutes) and break duration (default: 5 minutes).
Press Set if you changed either duration.
Press Start to begin.
Use Reset to restart the current timer.

The extension keeps Pomodoro session state and history in Chrome storage. A completed session can trigger a browser notification if Chrome notifications are allowed.

Smart Focus (feature-branch preview)

Open Focus → Smart Focus.
Choose 25 min, 50 min, 90 min, or Custom.
Edit the distraction list and the sites that should always be allowed during the session. Separate domains with commas.
Select Start focus. FocusFlow applies the session's temporary block and allow rules while the countdown runs.
Use Pause to pause the countdown and temporarily suspend Smart Focus blocking. Select Resume to reactivate both.
Use Emergency override · 5 minutes when you need a short exception. The session timer continues, and blocking automatically resumes when the override expires.
Select End session to stop early and save actual focused time. Completed and ended sessions appear under Recent Focus Sessions.

Smart Focus rules are additive: they do not overwrite your regular blocked-sites list or Website Profiles. The session's allow list takes priority over blocked-site rules while the session is running. Paused sessions do not apply Smart Focus rules. Session state and history are stored locally and included in JSON backup/restore.

Daily Goals

Open Focus → Daily Goals.
Set a daily focus-time target (15–720 minutes) and a task-completion target (1–30 tasks).
Select Save daily targets. Progress rings update as study time is tracked and tasks are completed.
Review the current streak, best streak, completed-day count, and seven-day strip.

Focus time is calculated from websites classified as Study in Overview. Task progress counts tasks marked complete after Daily Goals is installed; earlier task completions are not backfilled. Daily goal settings and task-completion history are included in JSON backup/restore. A day counts toward a streak when both targets are met.

Tasks

Open Focus → Tasks.
Type a task into the input field.
Select + Add.
Mark tasks complete as you finish them.

The task panel also displays the current task/blocking status. Follow the status shown in the extension; do not assume that adding a task alone starts a timed focus session.

Quick notes

Open Focus → Notes, type your note, and let it save automatically. Notes are stored locally in the extension.

3. Tools — control distracting websites and media

Website blocking

Open Tools → Block.
Enter a domain, for example instagram.com.
Select + Add.
To stop blocking a site, remove it from the blocked-sites list.

Enter a domain rather than a full page URL. Blocking is applied by the extension's background service worker when Chrome reports navigation/tab activity.

Video speed

Open Tools → Speed.
Choose a preset or move the slider.
Select Apply to Page.

The speed control works with supported HTML5 video/audio players. Some websites use custom players or restrict script access, so compatibility can vary.

Website dark mode

Open Tools → Dark mode.
Turn on Global Dark Mode to enable it across supported websites, or use the Current Site switch for a site-specific override.
Choose Smart, Invert, Dim, or Grayscale.
Adjust intensity if needed.

You can also use the Home quick toggle for the current website. Some websites may render imperfectly with automatic dark-mode CSS; switch the site off or try another style if that happens.

Website Profiles (branch preview)

Open Tools → Profiles.
Enter a domain such as youtube.com, or select Use current while visiting the website.
Choose whether automatic profile rules are enabled.
Set a default playback speed for HTML5 video/audio players.
Optionally set a daily time limit in minutes. Use 0 for no limit.
Choose whether dark mode follows the global setting or is always on/off for that domain.
Select Save website profile. Use Edit or Remove to manage saved profiles.

Profiles match the saved domain and its subdomains. Daily limits use FocusFlow's existing per-site screen-time totals; when a limit is reached, the website is redirected to FocusFlow's blocked page. Browser-internal pages cannot be controlled. Profiles are stored locally in Chrome and are included in JSON backup/export files.

4. Insights — understand your habits

Open Insights and choose the panel you want:

Activity: yearly activity heatmap, current/longest streak, and productive days.
Score: daily productivity score and its contributing factors.
Badges: achievements earned from tracked activity.
Coding: time on supported coding platforms and platform breakdown.
Reports: weekly summary and export options.
Smart Insights: local analysis of study-time trends, focus share, top distractions, Smart Focus sessions, and practical suggestions.

Smart Insights

Open Insights → Smart Insights.
Review your seven-day study time, focus share, week-over-week trend, and best study day.
Check the top non-study sites and recent Smart Focus session completion rate.
Use the suggestions as small experiments—not as a score or judgment.

Smart Insights runs locally using tracked browsing time, your Study/other site categories, and Smart Focus session history. It compares the latest seven days with the previous seven days. It does not upload browsing history or infer activity outside the extension's tracking data.

Insights depend on the activity FocusFlow has collected since installation. Empty or incomplete charts are normal when you are just getting started.

5. Settings — manage your data

Backup Data (JSON): download a backup of supported extension data.
Restore Data: select a FocusFlow JSON backup to restore its supported data keys.
Export All Data (JSON/CSV): download data for your own records or analysis.
Reset Statistics: remove tracking statistics and related history.
Reset ALL Data: clear all extension storage.

Important: Reset actions are destructive. Create a backup first. Restoring a backup writes the included data into extension storage; reload the extension if it asks you to.

Optional RangOS sync

The repository includes an optional backend integration. It is not required for normal local use. To configure it, open the extension's options page and provide your own backend endpoint and matching sync key. See SETUP.md for deployment and environment configuration. Never publish your sync key or backend secrets in a public repository.

Back up and restore your data

A simple safety routine:

Open Settings → Backup Data (JSON).
Save the downloaded file somewhere safe.
Before moving to another computer or reinstalling the extension, make another backup.
On the destination installation, open Settings → Restore Data and select the backup file.

Chrome extension storage is associated with the browser profile. A local backup is the portable copy you control. Keep backups private because they may contain browsing activity, tasks, and notes.

Privacy and permissions

FocusFlow requests these Chrome permissions to provide its features:

Permission	Why it is needed
`tabs`	Identify the active tab and its website for tracking and site controls
`storage`	Save preferences, tasks, notes, timer state, and activity data
`alarms`	Run periodic tracking and timer events
`notifications`	Notify you about timer completion
`scripting`	Apply supported website styles and media controls
`activeTab`	Interact with the active tab when you use extension tools
`host_permissions: <all_urls>`	Enable supported controls on websites you choose to use them on

Core extension data is stored using Chrome extension storage. Optional sync requires configuring your own backend. Review the code and backend configuration before enabling any network sync.

Troubleshooting

Problem	Try this
FocusFlow does not appear after installation	Confirm Developer mode is enabled and that you loaded the `extension/` folder containing `manifest.json`.
A feature does not respond	Open `chrome://extensions`, find FocusFlow, and inspect Errors. Then use the extension's reload button.
A blocked website still opens	Check that its domain is in Tools → Block, then reload the tab. Restricted browser pages cannot be controlled by extensions.
Dark mode looks incorrect	Turn off the current-site override or choose another dark-mode style.
Video speed does not change	Confirm the page uses a supported HTML5 media player, then try Apply to Page again.
No activity appears in Insights	Keep a website active in a normal browser tab and check again after some usage has been recorded.
Restore does not accept a file	Use a valid FocusFlow JSON backup created by the extension.

For developers

Project structure

extension/: Chrome Manifest V3 extension (popup, background service worker, options, and page assets).
api/: optional backend endpoints.
package.json: backend/project scripts and dependencies.

Run locally

Clone the repository.
Load extension/ in Chrome using the installation steps above.
Make changes in the extension source.
Return to chrome://extensions and click Reload on FocusFlow to test changes.

For backend development and deployment, follow SETUP.md. Do not commit API keys, sync secrets, or personal backup files.

Roadmap

FocusFlow 2.0 — in development

The next productivity upgrade is being developed separately and is intended to connect:

Smart Focus Mode: an initial implementation is available on this feature branch, including 25-, 50-, 90-minute and custom sessions, temporary site blocking/allow lists, pause/resume, a five-minute emergency override, and actual-time session history.
Daily Goals: configurable focus-time and task targets, progress rings, a seven-day view, and current/best streak tracking.
Website Profiles: an initial implementation is available on this feature branch: per-site playback speed, daily time limits, dark-mode overrides, and enable/disable controls. It still needs browser-level regression testing before release.

Daily Goals are available as a feature-branch preview. Smart Focus Mode and Website Profiles are feature-branch previews only; do not treat them as released until the pull request is reviewed, browser-tested, and merged.

Contributing

Issues, bug reports, and focused pull requests are welcome. Please include:

Chrome version and operating system
Steps to reproduce the issue
Expected behaviour and actual behaviour
Relevant console or extension errors (remove private data first)

License

MIT — see LICENSE if present in this repository.

Name		Name	Last commit message	Last commit date
api		api
extension		extension
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
REDESIGN_PLAN.md		REDESIGN_PLAN.md
SETUP.md		SETUP.md
package-lock.json		package-lock.json
package.json		package.json
vercel.json		vercel.json

Latest commit

History

Folders and files

Repository files navigation