FlowSeeker

Give AI coding agents the right files before they start guessing.

FlowSeeker is a context-prep layer for AI coding workflows. Describe a task, and FlowSeeker scans the codebase, ranks the relevant files, explains why they matter, and returns a compact Solve Packet for Claude Code, Codex, VS Code Chat, Cursor, Windsurf, Antigravity, or any MCP-compatible client.

It does not try to replace your coding agent. It gives the agent a cleaner starting point: what to read, what may need editing, what is probably noise, what is missing, and which checks are worth running.

Task: Fix grade export to Excel

FlowSeeker returns:
- likely edit files
- read-only context files
- routes/controllers/services/schema slots
- missing links if the flow is incomplete
- verification commands
- token-savings proof
- guardrails so the agent does not edit random files

Why This Exists

AI coding agents are powerful, but on large repos they often spend the first part of a task doing blind exploration:

• reading unrelated files
• grepping broad keywords
• mixing stale context from another project
• filling gaps with guesses
• burning tokens before reaching the real edit location

FlowSeeker handles that retrieval step first. The goal is simple: turn a vague code task into a small, evidence-backed context packet that an AI agent can act on.

Use It Your Way

| Workflow | Best entry point | |---|---| | VS Code user | FlowSeeker sidebar or @flowseeker /guide | | Claude Code / Codex CLI user | flowseeker guide, flowseeker auto, flowseeker files | | MCP-first user | flowseeker mcp, flowseeker-mcp, or fs-mcp | | Marketplace/OpenVSX user | Install the extension | | Automation/eval user | Headless CLI and reproducible benchmark scripts |

30-Second Start

VS Code Chat

@flowseeker /guide The payment confirmation email is not sent after checkout

FlowSeeker retrieves the relevant context and returns an agent-ready Solve Packet.

@flowseeker /auto Add SMS notification when payment fails

/auto starts from the same retrieval step, but asks the AI for a reviewable plan before edits.

Claude Code / Codex CLI

Install from npm, then run FlowSeeker from the target repo:

npm i -g flowseeker

cd /path/to/your/repo
flowseeker guide "Fix checkout webhook retry"
flowseeker auto "Add CSV export with tests"
flowseeker files "Find the auth middleware"
flowseeker retrieve "Debug login session expiry"

FlowSeeker works immediately without embeddings. No API key, model, runtime, or setup is required for the default deterministic retrieval path.

FlowSeeker core does not bundle the local embedding runtime/model in the npm or VSIX package; install flowseeker-local only when you want local embeddings.

Optional local embeddings with no API key:

npm i -g flowseeker-local
flowseeker semantic init --local
flowseeker semantic check --test

If the ready local package is not available in your environment, use explicit project-level setup:

flowseeker semantic local setup --yes       # install @huggingface/transformers
flowseeker semantic local download --yes     # fetch/cache model files
flowseeker semantic check --test

Offline mode (pre-cached model, no network): flowseeker semantic local download --yes --offline

Hosted embeddings are also supported through provider-neutral OpenAI-compatible config:

flowseeker semantic init --openai-compatible
# set semanticModel / semanticBaseUrl in .flowseeker/config.json
# put your API key in .env as FLOWSEEKER_EMBEDDING_API_KEY
flowseeker semantic check --test

Deterministic/no-embedding mode works without setup and is the default. No API key, no runtime, no model - just code-structure analysis.

Local evidence report: Verify your local embedding setup produces valid vectors. The command is report-only - no install, no download, no network by default.

# Structured JSON report (preferred):
flowseeker semantic local evidence --json
flowseeker semantic local evidence --report .flowseeker/local-evidence.json

# Setup and download are explicit separate commands:
flowseeker semantic local setup --yes
flowseeker semantic local download --yes

The report includes: workspace, runtime/model status, readiness, provider, model ID, dimensions, vector count, finite check, embed latency, classification, and next action. Classifications: runtime_missing, model_missing, model_invalid, pass, runtime_api_mismatch, embedding_shape_invalid, unknown_error.

Developer/manual opt-in script (source-repo only, requires env flags):

set FLOWSEEKER_RUN_REAL_LOCAL_RUNTIME_TEST=1
set FLOWSEEKER_LOCAL_TEST_WORKSPACE=<path>
node scripts/smoke-local-real-runtime-manual.js
# Optional: allow install/download via FLOWSEEKER_ALLOW_RUNTIME_INSTALL=1 etc.

Recommended terminal flow:

flowseeker auto "Fix payment retry idempotency" --out .flowseeker/agent-prompt.md

Then paste the generated prompt into Claude Code, Codex CLI, or your preferred agent.

Short aliases are also available:

fs-guide "Fix checkout webhook retry"
fs-auto "Add CSV export with tests"
fs-files "Find the auth middleware"

Claude Code MCP

After global install, run the one-command setup from your project:

# One-command setup (preview first, then apply):
flowseeker setup claude --no-exec
flowseeker setup claude --yes

# Optional: add ready local embeddings (no API key needed)
npm i -g flowseeker-local

# Verify everything:
flowseeker doctor --mcp
flowseeker semantic check --test

Also available: flowseeker setup codex, flowseeker setup cursor, flowseeker setup vscode. Then ask Claude Code to use FlowSeeker for the task. The MCP server exposes flowseeker_guide, flowseeker_auto, flowseeker_retrieve, and flowseeker_files.

MCP Server

npx -p flowseeker flowseeker-mcp --workspace /path/to/your/repo

Short alias after install:

flowseeker mcp --workspace /path/to/your/repo
fs-mcp --workspace /path/to/your/repo

For Cursor, Antigravity, Windsurf, Claude Desktop, and VS Code/Copilot config snippets, see docs/mcp-onboarding.md.

What A Solve Packet Contains

FlowSeeker separates context by role so the agent can act without treating every file as an edit target.

| Section | Purpose | |---|---| | Primary edit candidates | Files most likely to need changes | | Read-only context | Files that explain behavior but should not be edited by default | | Candidate Flow | Route/controller/service/schema/test style flow slots | | Missing Links | Required context that was not found, with search hints | | Noise Risk | Files that matched keywords but may be irrelevant | | Verification | Focused checks and test targets | | Token proof | Solve Packet size compared with scanned/indexed workspace text |

This is the core idea: the agent starts with a map, not a pile of files.

Features

• Task-aware retrieval: understands the task shape, extracts keywords, and checks required context slots.
• Evidence-ranked files: every selected file includes score, role, slot, confidence, and reasons.
• Solve Packet 3.0: compact markdown packet designed for AI coding agents.
• CLI-first workflow: fs-guide, fs-auto, fs-files, fs-retrieve, and fs-mcp.
• One-command install path: npm i -g flowseeker, then flowseeker guide, flowseeker auto, or flowseeker mcp.
• MCP support: exposes retrieval tools and prompts through a standalone stdio server.
• VS Code integration: sidebar, result tree, Native Chat participant, and bundled MCP provider where supported.
• Structured extraction: structured-regex parser for 13 languages.
• Semantic retrieval setup: optional local or hosted embeddings configured via .flowseeker/config.json, verified with flowseeker semantic check --test.
• Cache safety: atomic cache writes, corrupt-cache recovery, and delete cleanup checks.
• Honest fallbacks: if context is incomplete, FlowSeeker reports missing links instead of pretending it knows.

MCP Tools

FlowSeeker exposes these MCP tools:

| Tool | Use | |---|---| | flowseeker_retrieve | Return the full Solve Packet | | flowseeker_guide | Return an agent guidance prompt | | flowseeker_auto | Return a reviewable implementation-plan prompt | | flowseeker_files | Return top ranked files only |

Example MCP config:

{
  "mcpServers": {
    "flowseeker": {
      "command": "npx",
      "args": ["-p", "flowseeker", "flowseeker-mcp", "--workspace", "."]
    }
  }
}

VS Code/Copilot .vscode/mcp.json uses servers instead of mcpServers.

Evidence-Backed Capabilities

FlowSeeker avoids inflated claims. The public claims below are tied to reproducible local checks.

| Capability | Evidence | |---|---| | Cold scan under 2s (153 files) / 5s (149 files) for benchmarked workspaces | Generated by scripts/smoke-phase06-warm-query-performance.js | | Warm reuse with zero churn on unchanged workspace | Phase 06 warm query report | | Solve Packet 3.0 with 5 role sections | Phase 07 packet gate report | | Candidate Flow with numbered execution steps | Packet gate report and Solve Packet output | | Actionable Missing Links with slot-specific search hints | Packet gate report and Solve Packet output | | Runnable verification commands with separate metadata | Packet gate report | | Structured-regex parser for 13 languages | src/index/structuredExtractor.ts | | Delete safety and corrupt-cache recovery | Phase 06 smoke scripts | | VS Code extension, MCP stdio, and headless CLI | src/extension.ts, src/mcp/mcpTools.ts, src/cli/* | | 9 smoke tests passing on clean compile | npm.cmd run test:smoke |

Reproduce The Proof

npm.cmd run compile --silent
npm.cmd run test:manifest
npm.cmd run test:smoke

node scripts/analyze-phase08-public-proof.js --out-md .flowseeker/reports/phase08-8a-public-proof.md --out-json .flowseeker/reports/phase08-8a-public-proof.json
node scripts/smoke-phase06-warm-query-performance.js --out-md .flowseeker/reports/phase06-6g-warm-query-performance.md --out-json .flowseeker/reports/phase06-6g-warm-query-performance.json

Generated reports are written under .flowseeker/reports/.

Supported Languages

Structured-regex extraction currently supports:

TypeScript, JavaScript, Python, PHP, Dart, Java, Go, Ruby, C#, Swift, Kotlin, Rust, and Scala.

Tree-sitter support is available for TypeScript/JavaScript but is not part of the default public benchmark claim.

Optional Semantic Retrieval

FlowSeeker works without embeddings by default. Semantic retrieval only runs when you explicitly enable it.

Default mode needs no setup:

flowseeker guide "Find the checkout retry logic"

Optional local embeddings with no API key:

npm i -g flowseeker-local
flowseeker semantic init --local
flowseeker semantic check --test

Optional hosted embeddings:

flowseeker semantic init --openai-compatible
# Edit .flowseeker/config.json:
#   semanticModel = the embedding model exposed by your provider
#   semanticBaseUrl = provider endpoint if needed
# Add the key to .env:
#   FLOWSEEKER_EMBEDDING_API_KEY=your_key_here
flowseeker semantic check --test

Non-secret settings (provider, model, base URL, cache, limits) are written to .flowseeker/config.json. Only FLOWSEEKER_EMBEDDING_API_KEY goes into .env.

Expected result:

Result: active
Provider test: passed

Generic OpenAI-compatible path:

flowseeker semantic init --openai-compatible
# edit .flowseeker/config.json to set semanticModel before --test
# set semanticBaseUrl if your provider needs a custom endpoint
# fill FLOWSEEKER_EMBEDDING_API_KEY in .env
flowseeker semantic check --test

Config keys in .flowseeker/config.json:

• semanticProvider (e.g. openaiCompatible)
• semanticBaseUrl (provider endpoint)
• semanticModel (embedding model name from your provider)
• semanticApiKeyEnv (env var name for the key)

If token usage does not change on your provider dashboard, check flowseeker semantic check first. Most cases mean semantic is still disabled, the key is missing from the target repo's .env, or cached embeddings are being reused.

Embedding modes: FlowSeeker works without embeddings by default.

• Deterministic (default): No setup, no API key, no runtime, no model. Code-structure analysis only.
• Local (no API key): Install the optional flowseeker-local package, run flowseeker semantic init --local, then flowseeker semantic check --test. If needed, use project-level semantic local setup/download.
• Hosted: Bring your own embedding endpoint, model, and API key. Use flowseeker semantic init --openai-compatible, set the model/base URL, put the key in .env, then run flowseeker semantic check --test.

Use flowseeker semantic check or flowseeker doctor to confirm your status.

Hosted provider note: --openai-compatible initializes a provider-neutral config. Before --test, set semanticModel to the embedding model exposed by your provider. Set semanticBaseUrl if your provider needs a custom endpoint. The API key goes in .env. The model must match the provider and base URL.

Install

VS Code / OpenVSX

Search FlowSeeker in VS Code Extensions, or run:

ext install everestt2806.flowseeker

Also available on Open VSX for VSCodium and Eclipse Theia-compatible hosts.

npm / MCP / CLI

npx -p flowseeker flowseeker-mcp --help
npm i -g flowseeker
flowseeker --help
fs-guide --help
flowseeker mcp --help
flowseeker semantic check

Current Limits

These are intentionally explicit so users know what is proven today:

• No sub-second cold-scan guarantee.
• AI/LLM-based reranking exists experimentally but is disabled by default.
• Semantic/embedding retrieval is configurable but disabled by default.
• Tree-sitter parser support exists, but public proof uses structured-regex extraction.
• Graph expansion is not a production default.
• Monorepo, git-history, and LSP integrations are not public guarantees yet.

Roadmap

• Real-repo demo screenshots and short videos.
• More public benchmark fixtures across larger repo shapes.
• Cleaner first-run onboarding for MCP hosts.
• Bundled extension packaging to reduce VSIX size and startup overhead.
• Optional semantic retrieval profiles with provider-specific setup checks.

Rollback / Disable Semantic Retrieval

FlowSeeker works without embeddings. To return to deterministic/no-embedding mode:

# Disable semantic retrieval
flowseeker semantic check --workspace .  # confirm current status
# Edit .flowseeker/config.json: set "semanticEnabled": false
# Or remove the "index" block's semantic keys entirely
flowseeker benchmark  # verify: deterministic_no_embedding = first_class
flowseeker semantic check  # should show Result: disabled

Safe to remove from .flowseeker/config.json:

• semanticEnabled, semanticProvider, semanticBaseUrl, semanticModel, semanticApiKeyEnv, semanticCache, semanticMaxFilesPerRun, semanticTimeoutMs, semanticLocalModelPath, semanticLocalModelId, semanticDimensions, semanticRuntime

Safe to remove from .env:

• FLOWSEEKER_EMBEDDING_API_KEY

No models are bundled or auto-downloaded. Removing the config keys above returns FlowSeeker to its default deterministic retrieval mode. Use flowseeker benchmark anytime to confirm what is active.

License

MIT