FocusQuest is the flagship extension for this publisher's focus, daily planning, and Copilot configuration workflows.

FocusQuest

Neurodivergent-friendly developer workflow: Pomodoro, quests, Daily Brief, Copilot Sync, and local-first AI. No custom telemetry.

Publisher consolidation

focusquest.focusquest is the publisher's only maintained Marketplace publication surface. StandupBrief 0.1.7 and Twinport 1.0.2 are final compatibility releases that delegate to FocusQuest 1.9.0+; their source repositories and retained compatibility package are fail-closed against new Marketplace publication.

Publisher administrators remain the external trust boundary: VSCE can upload a prebuilt VSIX without running source hooks. The legacy repositories are archived after their freeze changes merge, and no maintained workflow or manifest exposes a legacy publication path.

What

VS Code extension providing a status-bar Pomodoro timer, a quest/task tree, XP and badges to reinforce focus behavior.

Features

• Pomodoro Timer: Customizable work/break cycles with automatic long breaks
  • Work sessions (default 25 min)
  • Short breaks (default 5 min)
  • Long breaks (default 15 min) automatically triggered after completing multiple work sessions
  • Configurable threshold for long break (default: every 4 work sessions)
  • Timer display shows HH:MM:SS with second-level updates (configurable)
  • Pause/Resume support for interruptions
• Quest System: Add tasks with optional AI-powered breakdown
  • Create tasks and epics (parent tasks)
  • Hide/show quests for screen-share-safe presentation
  • Edit and delete tasks
  • Right-click context menu actions
• XP & Gamification: Earn XP for completed quests and Pomodoro sessions
• Focus Copilot (desktop): Use @focusquest or the Focus Plan command to create a 3–7 step draft from explicitly selected, bounded, redacted editor selections, workspace files, diagnostics, Git diffs, or test evidence
• Dashboard: Unified overview for focus progress, Daily Brief actions, and Copilot Sync health
• Streak Tracking: Monitor consecutive daily focus sessions
• Walkthrough: Built-in onboarding guide
• Daily Brief (desktop only): Prioritized GitHub, Azure DevOps, incident, and local Git activity
• Copilot Sync (desktop only): Safely refresh allow-listed Copilot configuration from a Git repository

Badges

Stable badges (always on):

• First Quest: Complete your first quest (first_quest)
• Three Focus Sessions: Complete 3 focus sessions (three_focus_sessions)
• Two-Day Streak: Maintain a 2 day streak (two_day_streak)

Optional experimental badges (enable setting focusquest.experimentalBadges):

• Five-Day Streak (five_day_streak)
• Pomodoro Master: 10 focus sessions (pomodoromaster)
• Distraction Slayer: 3+ day streak & 5 focus sessions (distractionslayer)
• First AI Breakdown (first_ai_breakdown)
• AI Apprentice: 20+ AI subtasks generated (ai_apprentice)
• First Streamed Breakdown (first_streamed_breakdown)
• Multi Queue: Queued multiple AI breakdowns (first_multi_queue)
• Bounce Back: Successful breakdown after an empty one (first_non_empty_after_empty)

Badge unlock events appear via status updates; only newly achieved badges are emitted.

Commands

Core commands available via Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

See the capability inventory for the complete classification of all commands, compatibility aliases, agent tools, settings, and internal-only registrations.

• FocusQuest: Start Pomodoro - Begin a focus session
• FocusQuest: Cancel Pomodoro - Stop the current timer
• FocusQuest: Add Quest - Create a new task
• FocusQuest: Complete Quest - Mark a task as done and earn XP
• FocusQuest: Rename Task - Rename an existing task
• FocusQuest: Delete Task - Remove a task
• FocusQuest: Hide Quest - Hide a pending or completed quest from presentation views
• FocusQuest: Show Hidden Quest - Show a hidden quest again
• FocusQuest: Convert to Epic - Convert task to parent epic
• FocusQuest: Show Focus Stats - View XP, level, streak, badges
• FocusQuest: Sync Quests Now - Reconcile delayed quest changes from VS Code Settings Sync
• FocusQuest: Break Down Task with AI - AI-powered subtask generation
• FocusQuest: AI: Break Down This Task - Context menu AI breakdown
• FocusQuest: Cancel AI Breakdown - Stop active AI generation
• FocusQuest: Check Ollama Status - Verify AI setup
• FocusQuest: Select AI Model - Choose or enter custom Ollama model
• FocusQuest: Reset FocusQuest Data - Clear all data (with confirmation)
• FocusQuest: Show Proposal Inbox - Review imported quest proposals
• FocusQuest: Start My Day - Build a local report and pending proposals from local exports
• FocusQuest: Create Focus Plan - Preview a bounded focus-plan draft and explicitly approve its epic and child quests
• FocusQuest: Record Focus Checkpoint - Save a confirmed user note and optional selected context for an active plan
• FocusQuest: Review Focus Plan - Record completed, pending, and blocked work without changing quest completion

FocusQuest uses one status-bar item. During a session it shows the active focus/break timer and pauses or resumes on click; while idle it shows a compact XP summary and starts focus on click. AI state remains available in the tooltip.

Copilot Sync (desktop only)

The Copilot Sync view lives in the existing FocusQuest activity-bar container. Configure a GitHub repository in owner/repo form, then run FocusQuest: Copilot Sync: Sync Now to fetch its selected branch into a temporary worktree. FocusQuest checksum-compares and atomically installs the enabled .github/ categories into ~/.copilot/, optionally translating mcp-config.json for VS Code.

Protected personal databases, session state, OAuth configuration, logs, runtime packages, and user-owned settings are never replaced. New users must explicitly enable focusquest.copilotSync.autoSyncWeekly; migrated Twinport settings continue to work through deprecated aliases. Canonical settings take precedence over explicit twinport.* settings, which take precedence over explicit copilotConfigSync.* settings.

Configuration

Daily Brief (Desktop)

FocusQuest includes a Daily Brief view in the existing FocusQuest activity bar. It summarizes configured GitHub, Azure DevOps, incident, and local Git sources. A fresh install does not query or poll any source until at least one Daily Brief source is configured.

Use the FocusQuest Daily Brief commands to sign in, refresh, copy the brief as Markdown, diagnose authentication, or set a PAT. Built-in VS Code authentication is preferred; authenticated gh/az CLIs and GITHUB_PAT / ADO_PAT environment variables remain fallback options.

Configure new installations under focusquest.dailyBrief.*. Deprecated standupBrief.* settings and commands remain as compatibility aliases; an explicit canonical value takes precedence over an explicit legacy value. See the settings reference.

FocusQuest uses the standard Pomodoro technique with automatic long breaks:

Available focusquest.pomodoro.technique presets:

How Long Breaks Work: After completing the configured number of focus sessions (default: 4), FocusQuest automatically starts a long break instead of a short break. The session counter resets after the long break, starting a new cycle. This follows the traditional Pomodoro technique to provide extended rest periods.

Example with defaults:

1. Focus (25 min) → Short break (5 min)
2. Focus (25 min) → Short break (5 min)
3. Focus (25 min) → Short break (5 min)
4. Focus (25 min) → Long break (15 min) ← Counter resets
5. Cycle repeats...

Privacy & Telemetry

FocusQuest adds no custom telemetry. Quest records and deletion tombstones are registered for VS Code Settings Sync and semantically reconciled across signed-in machines when Sync is enabled. XP, badges, streaks, Pomodoro state, history, and settings remain machine-local; they are not merged from another machine. AI task breakdown is provider-selectable: the default auto provider tries a VS Code language model (for example, GitHub Copilot), then Ollama, then the built-in heuristic. A VS Code language model may send the task text to its provider. Choose ollama with a localhost URL or heuristic to keep breakdown local.

Copilot Sync makes a Git HTTPS request only when a manual or enabled scheduled sync runs. It does not log file contents, credentials, or machine-specific MCP paths.

Focus Copilot privacy and Restricted Mode

Focus Copilot is desktop-first. It does not select a model, scan the workspace, or make a network request during activation. Workspace context is available only in trusted workspaces and only after you select and approve a bounded manifest. Raw snippets, prompts, model responses, and secrets are kept in memory only; saved plans contain references, byte counts, summaries, and hashes instead. In Restricted Mode, context and SCM actions are blocked while the existing local quests, timers, Focus Session view, plan status, start, and review remain available. The @focusquest participant offers /plan, /status, /start, /checkpoint, and /review; context-dependent /plan and /checkpoint remain blocked in Restricted Mode.

Presentation privacy: Hide Quest removes a quest title from the quest tree and excludes it from dashboard task totals; hiding a parent also hides its subtasks. Default CLI and MCP quest listings also omit hidden quests. The quest remains stored and continues to participate in VS Code Settings Sync. Use Show Hidden Quest from the Command Palette to restore it. Hiding is intended for screen sharing; it is not encryption or access control, and anyone with access to your stored or synced FocusQuest state can still read hidden quests.

Streaks

Each completed work session increments streak; streak resets when a long break starts (new cycle). Canceling a session before completion prevents increment.

Note: The session counter for long breaks persists across VS Code restarts. If you completed 2 focus sessions, closed VS Code, and reopened it, the next 2 completed sessions will trigger a long break.

Stats Command

Run FocusQuest: Show Focus Stats to view current XP, level, streak count, and earned badges.

Installation

Install FocusQuest from the Visual Studio Code Marketplace.

1. Open VS Code
2. Open Extensions view (Ctrl+Shift+X or Cmd+Shift+X)
3. Search for "FocusQuest"
4. Click Install

Getting Started

After installation, use the Command Palette (Ctrl+Shift+P or Cmd+Shift+P) to access FocusQuest commands:

• FocusQuest: Start Pomodoro - Begin a focus session
• FocusQuest: Add Quest - Create a new task
• FocusQuest: Complete Quest - Mark a task as done and earn XP
• FocusQuest: Show Focus Stats - View your progress

Optional: AI-Powered Task Breakdown

FocusQuest can break down tasks into smaller steps. AI is enabled by default with the auto provider, which uses your VS Code language model (e.g. GitHub Copilot) when available. To run breakdown on a local model instead, use the Ollama provider:

1. Installing Ollama (free, open-source)
2. Pulling a model (e.g., ollama pull gpt-oss or ollama pull tinyllama)
3. Set focusquest.ai.provider to ollama (required for local inference — auto prefers your VS Code language model when one is available), then run FocusQuest: Break Down Task with AI

Supported Models: gpt-oss (default), llama3, llama3.2, llama3.1, tinyllama, mistral, phi3, gemma, qwen. Choose your preferred model in VS Code settings (focusquest.ai.model).

MCP server (agent CLI integration)

FocusQuest ships an MCP (Model Context Protocol) server so an MCP-aware agent — GitHub Copilot CLI, OpenCode CLI, or any other — can read your stats, manage quests, and start focus sessions on your behalf.

Topology: the CLI spawns node dist/mcp/server/main.js per invocation. The VS Code extension writes a small pointer file on activate (~/.focusquest/state-pointer.json) so the spawned child can find your state.json regardless of VS Code edition or portable-mode layout.

MCP tools (15): ping, focus_start, quest_add, quest_list, quest_update, quest_complete, quest_pomodoro_start, quest_pomodoro_finish, stats_get, proposal_import, proposal_list, proposal_decide, brief_get, brief_markdown, and quests_project.

VS Code Copilot Chat also exposes 15 language-model tools. Twelve share the quest, proposal, timer, and stats handlers above; the VS Code-only tools are daily_brief_refresh, focusquest_copilot_sync_health, and focusquest_copilot_sync_now.

CLI source surface

The repository contains a focusquest CLI that imports and reviews proposal batches without an MCP client or companion repository. It is built and tested with the extension, but is not currently published as a verified global npm package. A global npm installation is not a supported distribution path; install the Marketplace extension for the supported public distribution.

focusquest quests add "Review the release plan" --notes "Validate the evidence first"
focusquest quests list --status pending
focusquest quests update <quest-id> --title "Review and approve the release plan"
focusquest quests complete <quest-id>
focusquest proposals import ./proposals.json
focusquest proposals list --status pending,changes-requested
focusquest proposals decide <proposal-id> <revision> request-changes --feedback "Add a finish condition"
focusquest proposals decide <proposal-id> <revision> approve
focusquest day start --source-file ./work-items.json
focusquest day refresh --source-file ./work-items.json
focusquest day status

The CLI uses the state pointer written by the installed FocusQuest extension. For a portable or headless state file, add --state-file <path-to-state.json> to any command. Import, list, and decision commands use the same validation, locking, revision checks, receipts, and atomic approval handlers as MCP and the extension.

Start My Day automatically includes current quests as context and accepts repeatable provider-neutral --source-file exports. A conflict-free day start also starts the configured Pomodoro for the top visible pending non-template quest; an existing timer or an empty eligible queue is reported as a successful no-op. day refresh remains ingestion-only. The workflow updates only local state, report, ledger, and pending proposals; quests remain unchanged until explicit approval. See Start My Day for the bounded source schema, stale-change actionability rules, standalone --state-file workflow, and local persistence details.

Register with GHCP CLI

Add an entry to ~/.copilot/mcp-config.json (create the file if missing).

Recommended (VSIX install) — VSIX is the current shipping path. Point node at the extension's compiled MCP entry directly:

{
  "mcpServers": {
    "focusquest": {
      "command": "node",
      "args": [
        "<absolute path to extension>/dist/mcp/server/main.js"
      ]
    }
  }
}

The npm package exposes both focusquest for direct proposal commands and focusquest-mcp for MCP stdio clients.

Windows VSIX path — the extension installs under %USERPROFILE%\.vscode\extensions\focusquest.focusquest-<version>\. On macOS/Linux it's ~/.vscode/extensions/focusquest.focusquest-<version>/.

Override the state file

Set FOCUSQUEST_STATE_FILE to point at a specific state.json (useful for tests, headless runs, or pointing at a portable VS Code instance):

{
  "mcpServers": {
    "focusquest": {
      "command": "node",
      "args": ["<path>/dist/mcp/server/main.js"],
      "env": { "FOCUSQUEST_STATE_FILE": "/abs/path/to/state.json" }
    }
  }
}

Resolution order: FOCUSQUEST_STATE_FILE → pointer file → fail with an actionable error.

Register with OpenCode CLI

OpenCode reads MCP servers from an opencode.json config (project root, or ~/.config/opencode/opencode.json for all projects). Add a local MCP entry pointing at the same compiled entry:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "focusquest": {
      "type": "local",
      "command": ["node", "<absolute path to extension>/dist/mcp/server/main.js"],
      "enabled": true
    }
  }
}

To pin a specific state file, add an environment block:

{
  "mcp": {
    "focusquest": {
      "type": "local",
      "command": ["node", "<path>/dist/mcp/server/main.js"],
      "enabled": true,
      "environment": { "FOCUSQUEST_STATE_FILE": "/abs/path/to/state.json" }
    }
  }
}

The <absolute path to extension> is the same VSIX install directory used for the GHCP CLI config above. Verify it by running opencode and asking it to invoke the ping tool (expects a pong).

Known limitations

• R1 — state contention: the extension and the MCP child both write state.json via atomic tmp+rename under a cross-process file lock, with a per-field merge (CHILD_STATE_FIELDS) so a co-writer touching different fields never clobbers the other. External writes are now also read back live via a directory watcher (StateStore.reloadFromDisk), so no reload is needed to see CLI/MCP edits. Same-field, same-instant contention remains last-writer-wins.
• R2 — focus_start live timer: an external focus_start now updates pomodoro.current on disk and the extension ingests it live — the status bar and state reflect it without a reload. The live countdown tick for a session started entirely outside the extension still begins only once the extension drives its Pomodoro timer.

Release Status

Current Version: 1.10.1 (Stable) Stability: Stable unified release. Core focus workflows remain compatible; Daily Brief and Copilot Sync are dormant until configured or migrated. Versioning: Follows Semantic Versioning. Breaking changes only on MAJOR. Supported VS Code: 1.105.0+

Privacy & Security

• Zero Telemetry: No analytics or tracking. Respects env.isTelemetryEnabled if future telemetry added.
• AI Providers: By default (auto) AI uses your VS Code language model (e.g. GitHub Copilot) when available, which may send the task description you break down to that provider (potentially a cloud service). Set focusquest.ai.provider to ollama (local when ai.baseUrl is localhost, the default) or heuristic (no network) to keep all inference on your machine.
• Network Scope: The ollama provider connects only to focusquest.ai.baseUrl (default: localhost:11434). The vscode-lm provider routes through VS Code's language model API. The heuristic provider makes no network calls. Desktop Copilot Sync fetches only the configured GitHub repository when a manual or enabled scheduled sync runs.
• Data Storage and Sync: State persists locally. With VS Code Settings Sync enabled, only quests and deletion tombstones are semantically reconciled across machines. XP, badges, streaks, Pomodoro state/history, and settings remain machine-local.

Support & Feedback

Use the support link on the Visual Studio Marketplace listing to report issues or request features.

License

MIT