ScopeIn

Focus your Cursor or VS Code workspace on the folders that matter for the story or feature you are working on — hide the rest from the explorer, Quick Open, and AI context.

Inspired by StoryContextGen, a .NET CLI that solves the same problem from the terminal. ScopeIn brings that workflow into the editor with guided setup, one-click apply/clear, and safer defaults (validate-before-write, settings merge instead of overwrite).

When to use ScopeIn

Working on one slice of a large monorepo. You are fixing a bug in apps/api and do not want apps/web, packages/*, and docs cluttering the file tree or showing up in Cursor chat context.

Story- or ticket-scoped development. You have a user story that touches only a few paths. Apply a named scope, work until done, then clear — your full workspace comes back unchanged.

Repeatable focus configs. Save scopes under .scopein/ (e.g. checkout.json, auth-refactor.json) and switch between them without hand-editing JSON or absolute paths.

Pairing with AI assistants. .cursorignore uses an allowlist so Cursor indexes only the folders you chose. Fewer irrelevant files means less noise in @-mentions and agent context.

What you get

Artifact	Effect
.cursorignore	Allowlist for Cursor AI context (ignore all, then un-ignore selected folders)
.vscode/settings.json	files.exclude and search.exclude so the explorer and Quick Open respect your scope

ScopeIn also:

• Creates configs from the UI — pick folders, auto-fill repoRoot, save to .scopein/
• Validates before writing — bad paths or empty allowlists never corrupt your workspace
• Backs up and restores — Clear puts .cursorignore and settings back how they were
• Shows active scope — status bar and ScopeIn: Show Active Scope command

Commands

Command	Action
ScopeIn: Apply from Config…	Pick a .scopein/*.json config and apply
ScopeIn: Create Config…	Folder picker → save config → optional apply
ScopeIn: Clear	Restore pre-apply workspace files
ScopeIn: Show Active Scope	Show active config path and apply time

Config format

{
  "name": "my-feature",
  "repoRoot": "C:/path/to/repo",
  "folders": [{ "path": "apps/api" }],
  "globalExcludes": {
    "add": ["**/dist/"],
    "remove": ["**/node_modules/"]
  },
  "globalIncludes": ["tools/scripts"]
}

Field	Required	Description
repoRoot	Yes	Absolute path to the repository root
folders	Yes	Allowlisted folders (relative paths)
globalExcludes.add	No	Extra noise globs excluded even inside allowlisted folders
globalExcludes.remove	No	Omit built-in defaults (bin, obj, .vs, node_modules)
globalIncludes	No	Extra paths always visible in the explorer and Cursor context

Protected paths (always visible, not configurable): .vscode/, .scopein/, .cursor/, and .cursorignore.

Store configs in .scopein/ at the repo root. The apply picker can still open legacy .story-scope/ files via browse.

Local development

Prerequisites: Node.js 20+, VS Code or Cursor 1.85+

Check your version with node --version.

npm install
npm run lint
npm test
npm run compile
npm run test:integration

Lint before submitting: run npm run lint to check style and quality rules; use npm run lint:fix to auto-fix safe issues. CI runs the same lint check on every pull request. ESLint ignores build artifacts (dist/), dependencies, and .vscode-test/ (created when you run integration tests).

Unit tests (npm test): Vitest suite for core logic under test/unit/.

Run in Extension Development Host: open this repository in VS Code/Cursor and press F5. In the new window, use the command palette to run ScopeIn commands against a test workspace.

Integration tests (npm run test:integration): Extension Host smoke via @vscode/test-electron and Mocha — activation, command registration, apply/clear, and invalid-apply scenarios (INT-01–INT-05). pretest:integration runs compile automatically.

npm run test:integration

First run downloads a VS Code build into .vscode-test/ (~300 MB; gitignored). On Linux without a display, use xvfb-run -a npm run test:integration. CI runs lint, unit tests, compile, then integration tests on every pull request.

Install from VSIX (dogfood)

Use this when you want the real packaged extension in your daily Cursor session — not only the Extension Development Host (F5).

Build the package:

npm run package

This runs tests, compiles dist/extension.js, and produces scopein-{version}.vsix at the repository root (e.g. scopein-0.2.0.vsix). The file is gitignored; rebuild anytime.

Install in Cursor:

1. Command Palette → Extensions: Install from VSIX…
2. Select the .vsix file at the repository root
3. Reload the window if prompted

Verify: Extensions sidebar shows ScopeIn at the correct version; run ScopeIn: Apply from Config… on a test workspace.

Reinstalling a newer VSIX replaces the prior version.

Install from GitHub Release (teammates)

No marketplace account required.

1. Open the repository Releases page on GitHub
2. Download scopein-{version}.vsix from the latest release
3. Cursor → Extensions: Install from VSIX… → select the downloaded file
4. Run ScopeIn: Create Config… on your repo to confirm it works

Publishing a release (maintainers)

1. Bump version in package.json (e.g. 0.3.0)
2. Commit and merge to the default branch
3. Tag and push: git tag v0.3.0 && git push origin v0.3.0
4. Wait for the ScopeIn Release workflow (.github/workflows/release.yml) to complete
5. Confirm the GitHub Release includes scopein-0.3.0.vsix as a downloadable asset

The release job fails if the tag does not match package.json version (e.g. tag v0.3.1 with version 0.3.0).

Contributing

1. Fork and clone the repository.
2. Make changes with lint and tests passing (npm run lint, npm test, and npm run test:integration after npm run compile).
3. Follow existing patterns: pure core logic in src/core/, VS Code wiring in src/commands/ and src/extension.ts.
4. Update specs under specs/ if behavior changes (see Speckit workflow in the repo root).
5. Open a pull request with a short description of the user-facing change.

Bug reports and feature ideas are welcome. For scope-generation behavior, check specs/002- and golden tests in test/unit/ before changing algorithms.

Notes

• Folders listed in .gitignore may still be excluded from Cursor AI context even when allowlisted — ScopeIn warns on overlap.
• .cursorignore affects Cursor indexing, not terminal or MCP file access.