FlowSeeker — AI-Ready Codebase Context

FlowSeeker is a VS Code extension that retrieves the most relevant files for a codebase task before an AI model starts reasoning. Instead of dumping the whole repo into a prompt, FlowSeeker builds a compact Solve Packet with ranked edit candidates, read-only context, verification targets, and identified noise — so the model sees what matters, not what doesn't.

How It Works

User Task → Task Understanding → Workspace Scan → Evidence Ranking → 
Framework Edge Graph → Solve Packet → VS Code Chat Model

Understand the task — intent, concepts, actions, retrieval strategies
Scan the workspace — language-agnostic text scan across 11 languages
Rank evidence — multi-signal scoring: path, content, framework edges, graph boosting
Build Solve Packet — candidate flow, edit candidates, read context, tests, noise risk, missing links
Send to AI — the selected VS Code Chat model receives the packet, not the whole repo

Quick Start

Open VS Code Chat and type:

@flowseeker /guide Fix the payment confirmation email not being sent after checkout

FlowSeeker scans your workspace and returns a ranked list of relevant files with reasoning.

@flowseeker /auto Add rate limiting to the login endpoint

The /auto command retrieves context and asks the model for a reviewable plan only — no files are changed. After you review and approve the plan, structured edits are generated and you apply them with a single button.

Chat Commands

Command	Description
`@flowseeker /guide <task>`	Retrieve context and get guidance on what to change
`@flowseeker /auto <task>`	Retrieve context, then ask the model for a reviewable plan
`@flowseeker /apply <planId>`	Generate structured edits from an approved plan

Features

Deterministic Retrieval (No API Key Required)

Task understanding in Vietnamese and English with synonym expansion
Language-agnostic text scanning with path, content, and structure signals
Persistent workspace index for fast repeated scans
Scan budget protection: max files, max bytes, max time

Solve Packet v1

Problem hypothesis from task intent
Candidate flow buckets: entry/route, handler/controller, service/domain, schema/config, tests
Noise risk detection and missing link identification
Agent instructions that warn: evidence is candidate context, not guaranteed truth

Framework-Aware Graph Edges

Laravel (PHP): route→controller, event→listener, controller→service, job→config, view rendering
NestJS (TypeScript): decorator-based controller→service, module→provider
Express (JavaScript): route→handler via require/import resolution
Framework-discovered units: files with zero keyword matches found through framework connections

Safety Guardrails

Plan-first workflow: /auto produces a plan only — edits require user approval
Scope lock: edits are validated against the approved plan's allowed files
Diff preview: file-level change preview before applying
Verification loop: auto-detect test/lint/typecheck commands after edits

Structured Extraction

Regex-based code structure extraction for 11 languages: TypeScript, JavaScript, Python, PHP, Java, Go, C#, Ruby, Rust, Kotlin. Extracts declarations, call sites, string literals, and comments for more precise evidence ranking.

Headless Evaluation

Repeatable retrieval benchmarking with hit@K, MRR, expected-path coverage:

npm run eval -- --manifest .flowseeker/eval-workspaces.example.json

Supported Languages

Level	Description	Languages
Text fallback	Path/content/chunk search	All text files
Structured extraction	Regex-based declarations, calls, strings	TS, JS, Python, PHP, Java, Go, C#, Ruby, Rust, Kotlin
Framework adapters	Route→controller→service→model→test edges	Laravel, NestJS, Express

Configuration

Workspace defaults in .flowseeker/config.json:

{
  "project": {
    "name": "my-app",
    "include": ["src", "app", "lib", "tests"],
    "exclude": ["node_modules", "vendor", "dist", "build"],
    "maxFileSizeKb": 800
  },
  "index": {
    "enableWorkspaceIndex": true,
    "enableTreeSitter": true,
    "enableDependencyExpansion": true
  },
  "pipeline": {
    "maxCandidates": 40,
    "maxContextTokens": 4000,
    "maxFiles": 5000,
    "maxTotalBytesMb": 120,
    "maxScanMs": 30000
  },
  "synonyms": {
    "mail": ["email", "smtp", "mailer", "notification"],
    "payment": ["billing", "invoice", "checkout", "transaction"]
  }
}

VS Code settings under flowseeker.* override workspace config.

Commands (Command Palette)

Command	Description
`FlowSeeker: Find Relevant Context`	Run retrieval from the command palette
`FlowSeeker: Copy Context Pack`	Copy selected evidence as markdown
`FlowSeeker: Copy Agent Solve Prompt`	Copy a guarded prompt for external AI tools
`FlowSeeker: Rebuild Index`	Clear and rebuild the workspace index cache
`FlowSeeker: Verify After Edits`	Run test/lint/typecheck on changed files
`FlowSeeker: Run Evaluation Suite`	Run local evaluation suites
`FlowSeeker: Explain Selection Relevance`	Explain why the active file appears in results
`FlowSeeker: Open Related Tests`	Open test evidence from current results
`FlowSeeker: Connect AI Gateway`	Configure custom AI gateway (optional)

Development

npm install
npm run compile

Press F5 in VS Code to launch the Extension Development Host.

# Package for distribution
npm run package

# Publish to Marketplace
npm run publish

AI Gateway (Optional)

FlowSeeker uses the VS Code Language Model API by default. When that isn't available, you can connect a custom AI gateway:

// Gateway request
{
  "product": "FlowSeeker",
  "mode": "auto",
  "task": "User task",
  "contextPack": "...",
  "topFiles": [...]
}

// Gateway response
{
  "message": "Summary",
  "edits": [{
    "file": "src/example.ts",
    "range": { "startLine": 10, "startColumn": 1, "endLine": 12, "endColumn": 1 },
    "text": "replacement"
  }]
}

License

MIT

FlowSeeker

everestt2806