Stop scope creep before it starts.
ScopeSentry is an open-source, privacy-focused scope analysis tool for freelancers and agencies. It helps identify client requests that may go beyond an agreed project scope by comparing the original project brief against client conversations.
Powered by Google's Gemma models through Ollama, ScopeSentry is designed to analyze sensitive project information locally without relying on a hosted AI API.
Scope creep happens when project requirements gradually expand without a corresponding change in budget, timeline, or agreement.
Freelancers often have to cross-reference project briefs, contracts, emails, and chat messages to determine whether a new request was originally included. This process can be tedious and error-prone.
ScopeSentry helps make that process easier by comparing the original agreement with new client requests and presenting evidence-backed findings for review.
- Local AI Analysis: Run analysis using Gemma through Ollama on your own machine.
- Evidence-Based Findings: Verify supporting quotes against the original agreement or conversation.
- Scope Classification: Categorize requests as
in_scope,potentially_out_of_scope,unclear, orneeds_review. - Actionable Recommendations: Understand why a request was flagged and what to clarify with the client.
- Professional Reply Drafting: Generate editable, context-aware client response drafts.
- Privacy-Focused Architecture: Avoid unnecessary data collection, external AI services, and persistent storage.
- Open Source: Inspect the code, contribute improvements, and adapt the tool to your workflow.
ScopeSentry provides decision support, not legal advice. Always review findings before making contractual or business decisions.
- Add your agreement: Paste the original project brief, proposal, or relevant contract text.
- Add the conversation: Paste the client's message or relevant conversation.
- Analyze the scope: Gemma compares the request with the information provided in the agreement.
- Review the findings: Examine classifications, supporting evidence, explanations, and recommended next steps.
- Draft a response: Generate and edit a professional reply before copying it to your client.
The interface is text-first: a paste workspace, then a report of classified findings with cited evidence, and a reply composer. A screenshot is still pending.
| Technology | Purpose |
|---|---|
| Next.js 16 (App Router) | Application and server-side API routes |
| React 19 | UI runtime |
| TypeScript (strict) | Type safety |
| Tailwind CSS v4 | Styling and responsive layouts |
| shadcn/ui (Base UI primitives) | UI components in components/ui |
| Ollama | Local model runtime |
| Google Gemma 3 | Local AI analysis |
| Zod | Runtime validation of structured AI output |
| Node.js built-in test runner | Unit tests via npm test |
- Node.js 20.9 or a version supported by your installed Next.js release (required to run the app; Node.js 22.18+ or 24 LTS is needed to run
npm test, which executes TypeScript directly) - npm or the package manager specified by the repository
- Ollama (0.6 or later, required by Gemma 3)
- A compatible Gemma model that your machine can run
git clone https://github.com/sufiankhan-dev/ScopeSentry.git
cd ScopeSentryFor an initial experiment, start with Gemma 3 4B:
ollama pull gemma3:4bOther options include:
# Smaller model to experiment with
ollama pull gemma3:1b
# Larger model that may provide better results
ollama pull gemma3:12bModel performance and memory requirements depend on quantization, context length, available RAM, and your hardware. Choose a model that works reliably on your machine.
Verify your installed models:
ollama listnpm installCreate .env.local from the example file:
Copy-Item .env.example .env.localcp .env.example .env.localConfigure the model and Ollama endpoint in .env.local:
OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_MODEL=gemma3:4b
OLLAMA_TIMEOUT_MS=300000Ensure OLLAMA_MODEL matches a model you have installed. Keep .env.local out of version control.
OLLAMA_BASE_URL must be a loopback address; a non-loopback host is rejected unless OLLAMA_ALLOW_NON_LOOPBACK=1 is set. OLLAMA_TIMEOUT_MS (1000–600000, default 120000) is worth raising on a CPU-only machine: an analysis is three sequential model calls, and in testing gemma3:4b generated at roughly 7 tokens per second on CPU, so the default timeout was not enough for a single pass. The full list of variables is documented in .env.example.
Make sure Ollama is running and the configured model is available. Depending on your installation, Ollama may start automatically when you open its application.
You can test the model independently:
ollama run gemma3:4bnpm run devOpen http://localhost:3000 in your browser.
The application ships with a fictional sample agreement and client thread, and a Fill both fields with sample input button that loads both into the workspace. Use that for the demo; the text lives in lib/samples.ts if you want to edit it.
The example below illustrates the kind of request to look for.
Project: Brand identity refresh and small-business website.
Scope: Brand refresh, including logo, color palette, typography, and high-fidelity design for six page templates.
Exclusions: Photography, copywriting, frontend development, and CMS configuration.
Client: Can you also produce a short brand guideline PDF so the team stops using the old logo in the cafe?
Freelancer: The agreement covers the refined logo files and palette. A written brand guideline document isn't explicitly listed among the six page templates.
ScopeSentry should examine whether creating a separate brand guideline document is reasonably covered by the agreed brand identity deliverables.
Depending on the full agreement and context, it may classify the request as potentially_out_of_scope or needs_review.
The finding should explain its reasoning, cite exact supporting text, and acknowledge that the agreement does not explicitly settle the question. It should not present an uncertain interpretation as a contractual fact.
ScopeSentry is designed around local inference and data minimization.
- Local Inference: AI analysis uses the configured Ollama instance rather than a hosted AI API.
- Server-Side Processing: Requests to Ollama are handled on the server, not directly from browser code.
- No Unnecessary Persistence: The MVP does not require a database or project-history storage.
- Evidence Verification: Supporting quotes are checked against the original submitted text using deterministic validation.
- No Cloud AI Fallback: Ollama failures should produce a clear error rather than silently sending private content to another AI provider.
In the current implementation these requirements are enforced in code: model calls are made only from lib/ollama.ts with a loopback-checked endpoint, redirects are refused, and nothing is written to a database, localStorage, sessionStorage, IndexedDB, or cookies. Re-verify this in the code before making absolute privacy claims. Local processing still does not protect against malware, a compromised machine, or a leaked config file.
- Hardware Dependent: Inference speed and model quality vary with available memory, processor, GPU, and model configuration.
- Initial Setup: Internet access is required to download Ollama and the selected model. Subsequent offline operation has not been established until tested.
- Pasted Text Only: PDF, DOCX, and chat-export imports are outside the initial MVP unless implemented separately. Each document is capped at 20,000 characters and is never silently truncated; longer input is rejected with a clear message.
- Advisory Classifications: AI can misinterpret agreements or conversations. Human review remains necessary.
- No Project History: The initial design does not require persistent project storage.
- Local Environment Required: The application needs access to the configured Ollama service. A remotely hosted application cannot automatically access Ollama running on a visitor's own computer.
Run the checks available in the repository:
npm run lint
npm run typecheck
npm test
npm run buildnpm test runs Node's built-in test runner against the TypeScript sources in tests/, with model calls stubbed, so the suite runs offline.
Important test cases include:
- Valid and invalid structured AI output
- In-scope, potentially out-of-scope, and ambiguous requests
- Exact evidence matching and fabricated quotes
- Missing or conflicting agreement terms
- Empty and oversized inputs
- Ollama connection failures and timeouts
- Invalid model responses
- Privacy-sensitive logging and unintended persistence
- Complete the core agreement and conversation analysis flow
- Improve evidence verification and handling of ambiguous findings
- Complete the findings report and editable reply drafting
- Add comprehensive automated tests
- Add PDF and DOCX support
- Support multiple conversation threads
- Explore optional encrypted local project history
- Add configurable scope rules and project-specific preferences
- Validate the offline workflow after initial setup
Before presenting ScopeSentry:
- Ollama is running and the selected Gemma model is installed.
-
.env.localpoints to the correct local model. - The application starts without errors.
- The demo agreement and conversation produce a meaningful report.
- Findings contain verifiable evidence from the submitted text.
- Ambiguous requests are not automatically treated as confirmed scope violations.
- Reply drafts can be edited before copying.
- Errors are handled when Ollama is unavailable.
- Privacy claims have been checked against the actual implementation.
Contributions are welcome.
- Fork the repository.
- Create a feature branch.
- Make a focused change.
- Run the relevant checks.
- Open a pull request describing the change and its purpose.
Please preserve the local-first approach and avoid introducing unnecessary data collection or cloud AI dependencies.
Choose an open-source license and include its corresponding LICENSE file in the repository before publishing. Update this section to identify the selected license.
Built to help freelancers protect their time, clarify project boundaries, and handle client requests with confidence.