Why FocusShift

Context-switching is one of the most expensive things that happens during a coding session. Research on interruption recovery consistently finds that developers can lose upwards of 20 minutes rebuilding focus after even a brief break — not because the code changed, but because they forgot the exact file, line, and reasoning they were mid-thought on.

FocusShift doesn't try to prevent interruptions. It makes coming back from one instant instead of costly.

Features

• Automatic interruption detection — triggers on window blur (alt-tab away) or a configurable inactivity timer, whichever happens first.
• Instant context restore — reopens the right file and jumps your cursor back to the exact line and column, with no manual searching.
• A subtle return chime — a gentle audio cue when you come back, toggleable at any time.
• A smart "Welcome Back" popup — tells you in plain language what you were doing, e.g. "You were working in validateToken() in auth.ts — line 42."
• Two-tier summarization, so it's never just a blank guess:
  • Heuristic engine (always on, instant) — regex-based detection of the nearest enclosing class, method, function, or variable, tuned for TypeScript, JavaScript, and Python, with graceful fallback for every other language.
  • Local AI summaries via Ollama (optional) — a richer "Where You Were / Context / Suggestion" summary generated by a small local language model. Entirely offline — nothing about your code ever leaves your machine.
• Context History panel — a searchable, filterable log of every interruption, with the file, line, timestamp, and summary, viewable from the sidebar. Delete entries individually or clear them all at once.
• A dedicated sidebar — one-click access to Settings, Context History, and Ollama setup, with a live status badge showing whether AI summaries are ready.
• 100% local and private — no telemetry, no analytics, no data sent anywhere. Your code and your activity never leave your machine.

How it works

1. FocusShift watches for two signals: the VS Code window losing focus, or a period of inactivity (no edits, cursor moves, scrolls, or tab switches) past a threshold you control.
2. The moment either fires, it snapshots your open editors — cursor position, a code excerpt around it, and any active errors/warnings.
3. When you return, it generates a summary of what you were doing (instantly via the heuristic engine, upgraded a moment later by the local AI model if you've set it up) and shows it in a small, dismissible popup — along with a chime, if enabled.
4. Every interruption is logged to a searchable history panel, so you can look back at what you were doing an hour — or a week — ago.

Requirements

• VS Code 1.95.0 or later.
• (Optional) Ollama installed locally, for AI-generated summaries. Everything else works with zero setup — the heuristic engine requires no external dependency at all.

Installation

From the Marketplace: Search for FocusShift in the Extensions view (Ctrl+Shift+X / Cmd+Shift+X), or install directly:

code --install-extension focusshift.focusshift

From a .vsix file: Extensions view → ... menu → Install from VSIX...

Setting up AI summaries (optional)

FocusShift works fully out of the box using its built-in heuristic engine — no setup required. If you'd like richer, AI-generated summaries, you can optionally connect it to a small language model running locally via Ollama.

Option A — Guided setup: Run FocusShift: Setup Ollama from the Command Palette. FocusShift will open a terminal and walk you through installing Ollama and pulling the required model automatically.

Option B — Manual setup:

1. Install Ollama from ollama.com.
2. Run ollama pull qwen2.5-coder:1.5b-instruct.
3. Reload VS Code.

If Ollama isn't installed or isn't running, FocusShift automatically falls back to the heuristic summary — you'll never see an error, and there's nothing to configure.

Commands

Accessible via the Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

Extension Settings

*On first install, FocusShift checks whether Ollama is already available and adjusts this automatically — you don't need to configure it manually either way.

Privacy

FocusShift is entirely local by design:

• No telemetry, analytics, or usage tracking of any kind.
• No network requests, except to localhost when AI summaries are enabled and Ollama is running on your own machine.
• Your code, history, and activity are stored only in VS Code's local extension storage — never transmitted anywhere.

Known limitations

• The heuristic engine's construct-level detection (class/method/function names) is most accurate for TypeScript, JavaScript, and Python. Other languages still get a summary, but it may fall back to a simpler filename-and-line description.
• AI summaries require Ollama to be installed and running locally; this is entirely optional and the extension is fully functional without it.

Contributing / Development setup

git clone https://github.com/Mariammazen147/FocusShift.git
cd FocusShift
npm install
npm run watch

Press F5 in VS Code to launch an Extension Development Host window with FocusShift active.

Running tests

npm test

Runs the full Jest suite (unit tests for state management, the heuristic engine, AI summary integration, history storage, and HTML rendering) against a mocked VS Code API.

License

MIT — free to use, modify, and share.