scopekit-cli

Scope your AI coding assistant to exactly the right part of your codebase — and enforce it.

When you ask an AI to fix something in one module, it tends to load the entire project: token budgets bleed, responses slow down, and edits start stepping on code they shouldn't touch. ScopeKit gives each module a tight, anchored brief, derives ownership and dependencies from your real import graph, and uses a PreToolUse hook to make the AI load the right context before it edits anything.

This package ships three executables:

| Bin | Role | |-----|------| | scopekit-cli | init (wire it in), verify (CI gate), scaffold (analysis) | | scopekit-hook | The PreToolUse enforcement hook | | scopekit-mcp | The MCP context-provider server |

Install & wire it in (one command)

npm install -D scopekit-cli
npx scopekit-cli init

init writes the config for you — no hand-edited JSON, no absolute paths. It creates AGENTS/ + CLAUDE.md, merges the enforcement hook into .claude/settings.json (without clobbering existing hooks), registers the MCP server in .mcp.json, and writes a first-pass AGENTS/scopekit.json from your directory tree so enforcement is live immediately. Because it's installed locally, the paths it writes are relative (./node_modules/scopekit-cli/…) — portable across your team and safe to commit.

Restart your AI client, then tell Claude:

Refine AGENTS/scopekit.json and write the MOD-XXX.md briefs.

No-install option

npx -y scopekit-cli init --npx

--npx writes npx-based commands into the config instead of local paths — nothing is installed into the project.

Flags

| Flag | Effect | |------|--------| | --hook-only | Wire only the enforcement hook; skip the MCP server. | | --npx | Emit npx commands instead of local paths. | | --name=<project> | Project name in the generated config (defaults to the folder name). |

Verify in CI

npx scopekit-cli verify

Every glob must match files; every @anchor must point at a symbol that still exists. Non-zero exit on error, so it gates a PR.

How a scoped edit works

1. You (or the AI) start editing a file owned by a module.
2. The hook blocks the first edit this session and injects that module's brief: its files, its invariants, and the contract surface of every module it depends on.
3. You re-issue the edit — it proceeds, and you're not interrupted again for that module this session.

Full documentation, examples, and the design rationale: https://github.com/EagleMind/scopekit

License

MIT