<div align="center"> <h1>Flyto2 Indexer</h1> <p><strong>Know what breaks. Prove the fix.</strong></p> <p> <a href="https://github.com/flytohub/flyto-indexer/actions"><img src="https://github.com/flytohub/flyto-indexer/workflows/CI/badge.svg" alt="CI"></a> <a href="https://github.com/flytohub/flyto-indexer/actions/workflows/benchmark.yml"><img src="https://github.com/flytohub/flyto-indexer/actions/workflows/benchmark.yml/badge.svg" alt="Benchmark evidence"></a> <a href="https://github.com/flytohub/flyto-indexer/actions/workflows/public-proof.yml"><img src="https://github.com/flytohub/flyto-indexer/actions/workflows/public-proof.yml/badge.svg" alt="Public proof"></a> <a href="https://pypi.org/project/flyto-indexer/"><img src="https://img.shields.io/pypi/v/flyto-indexer.svg" alt="PyPI"></a> <a href="https://github.com/flytohub/flyto-indexer/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License"></a> <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+"></a> </p> <p> <a href="#installation-and-first-result">Quick start</a> · <a href="#real-repository-proof-text-search-stops-indexer-keeps-going">Real proof</a> · <a href="docs/README.md">Documentation</a> </p> </div>
Your coding agent can edit a repository in seconds. The expensive mistakes come later: a missed caller, a stale contract, an ignored repository rule, or “done” declared after the nearest test passes.
Flyto2 Indexer gives any MCP-capable coding agent a local map before it edits and an evidence gate before it stops.
- Map the change: see callers, dependents, tests, APIs, and cross-project
impact before touching code.
- Keep the intent: carry repository rules, requirements, and decisions into
the actual diff.
- Prove the result: close lint, tests, security, documentation, and change
conformance before the agent says it is finished.
No API key. No model lock-in. No source upload.
Who It Is For
Flyto2 Indexer is most useful when:
- you use AI on an existing codebase that no one holds entirely in their head;
- a change can cross packages, services, or repositories;
- several developers or coding agents must follow the same rules;
- private, regulated, or air-gapped source must stay local.
It is not another code generator, IDE, or hosted dashboard. Keep the tools you already trust; Flyto2 Indexer gives them a shared change map and finish gate.
Installation And First Result
pip install flyto-indexer
flyto-index setup .
flyto-index verify . --strictsetup builds a local index and configures supported MCP clients. Then ask your agent:
impact(target="validateOrder", change_type="rename")7 call sites · 3 projects · 2 test files
Risk: high
Manual review: 1 unresolved dynamic referenceA text search finds the name. Flyto2 Indexer shows the change surface.
The Problems It Removes
| Pain | What Flyto2 Indexer changes | | --- | --- | | “I changed one function and something unrelated broke.” | Shows callers, dependents, likely tests, and unresolved references before the edit. | | “The agent ignored our repository rules.” | Loads the instructions that apply to the target and blocks contradictory or stale guidance. | | “The ticket said five things; the diff only did three.” | Links requirements to planned steps, changed paths, and proof. | | “Tests passed, but the change still was not ready.” | Verifies the index, impact, security checks, documentation, policy, package state, and working tree together. | | “Frontend and backend drifted apart.” | Compares calls, routes, and contracts so missing connections are visible. | | “Our scanner is so noisy that nobody trusts it.” | Keeps evidence local, reports confidence and provenance, and supports baselines for accepted debt. | | “The AI keeps hitting the same bad warning or missing the same connection.” | Records the problem locally, groups repeats, and turns them into a reviewable improvement backlog. | | “I switched AI tools and had to explain the whole task again.” | Keeps one local task state that any client can resume, and reminds you only when unfinished work needs a handoff. | | “A large repository overwhelms the agent.” | Returns bounded, relevant context instead of dumping the whole codebase. |
Real Repository Proof: Text Search Stops, Indexer Keeps Going
On the pinned, public fastapi/full-stack-fastapi-template commit used by our reproducible case, a literal search for render_email_template returns four lines in one file. A depth-two impact query finds four request handlers in three additional files above those direct calls.
git grep: 4 matching lines · 1 file
impact: 7 affected functions · 4 files · 0 scan errors
missed by literal search: 4 request handlersRun the proof yourself:
python scripts/reproduce_impact_case.py --check-snapshotRead the method, pinned source, exact result, and limits or inspect the machine-readable receipt. This proves static transitive discovery for the pinned case; it does not replace runtime tests.
Why It Fits Your Existing Workflow
Flyto2 Indexer complements the tools you already use:
| Keep using | What it already does well | What Flyto2 Indexer adds | | --- | --- | --- | | Your coding agent | Understands requests and applies edits | A local change map, scoped rules, and a finish gate | | IDE search or grep | Finds names and direct references quickly | Transitive impact, cross-project links, likely tests, and unresolved gaps | | Linters and test suites | Catch the failures they are configured to detect | Proof that the requested work, changed paths, and required checks still agree | | CI | Repeats commands on every change | One regression-aware repository and workspace verdict |
You do not need to replace your model or development workflow. Try it on one risky refactor first.
Usage
Keep daily work in one closed loop:
find → understand impact → plan → pass the gate → edit → validate → verifyThe public tool names are short:
search → impact → task(plan) → task(gate) → edit → task(validate) → verifysearchfinds the relevant code and concepts.impactshows what a change can affect.taskkeeps decisions, project rules, requirements, and proof connected.verifychecks whether the repository is actually ready to finish or merge.
When a session exposes a weak rule, missing relationship, slow scan, or poor recommendation, keep that evidence instead of losing it in chat history:
task(
action="feedback",
feedback_action="record",
feedback_category="framework_gap",
feedback_summary="A lazy-loaded route was missing from impact analysis"
)Repeated problems are grouped into a local improvement backlog. Feedback never uploads prompts or source code and cannot automatically weaken repository policy. See Learn from every AI miss.
When you switch between coding agents, the existing task(plan), task(gate), and task(validate) flow keeps a small resumable state under the ignored local index. structure(focus="profile") exposes that state to the next MCP client; no handoff file or extra MCP tool is created.
flyto-index task-status .
flyto-index usage-record task-1 . --provider openai --model gpt-5 \
--usage '{"input_tokens":1200,"output_tokens":300}'
flyto-index usage-report . --task task-1 --format jsonUsage evidence stores normalized counts, never prompts, responses, source, or raw provider payloads. A reduction is reported only for two verified runs with the same model, commit, task fingerprint, tool policy, proof policy, and sample count. See Resume across AI tools.
When a gate fails, it explains what is missing. Complete those actions and run the same gate again. A failed gate pauses the unsafe step; it does not abandon the task.
When The Task Is Still Vague
Use the optional Decision Grill before planning. It resolves facts from the repository first, then asks one high-value question at a time. Once the important decisions are settled, it freezes them into the plan so the final diff can be checked against what was agreed.
task(action="grill", grill_action="start", description="Add robot adapter")
task(action="grill", grill_action="freeze", grill_session_id="grill_...")
task(action="plan", grill_session_id="grill_...", ...)If there is no real product or architecture choice to make, skip Grill and go straight to task(plan).
API And Integration Surfaces
Most users need only the five short MCP tools: search, impact, task, audit, and structure. The CLI adds local setup, reports, and CI verification without requiring a hosted account. A loopback HTTP bridge is available for clients that need a persistent process, but it stays on the local machine by default.
All public contracts are generated from the current source, so an integration does not have to trust a hand-maintained command list. Start with the MCP guide, CLI guide, or the source-backed reference.
The Main Questions It Can Answer
| Tool | Question | | --- | --- | | search | Where is the relevant code? | | impact | What could break if this changes? | | task | Are the decisions, rules, requirements, and proof complete? | | audit | Where are the most important quality and security risks? | | structure | How is this project connected? | | verify | Is this repository ready to finish or merge? |
Focused checks also cover secrets, unsafe data flow, dependencies, licenses, software inventory, architecture boundaries, documentation, pull-request risk, and multi-repository verification. The exact tool contracts live in the generated MCP reference.
What “Verified” Means
verify combines checks that are usually scattered across several commands:
- Is the local index current and internally consistent?
- Can the requested context and impact path be reproduced?
- Did secret, unsafe-data-flow, and repository-policy checks pass?
- Are documentation, package metadata, and generated files in sync?
- Is the working tree clean enough for the requested gate?
It does not pretend static analysis proves runtime behavior. Browser, service, integration, race, container, security, and deployment checks remain project-owned. Their local results can be attached as content-addressed, optionally attested proof receipts; only fresh trusted receipts satisfy a required runtime-proof gate.
CLI
flyto-index scan . --full
flyto-index impact useAuth --path .
flyto-index context --path . --query "auth routes query keys"
flyto-index task plan --description "Refactor auth" --target src/auth.py
flyto-index verify . --strict
flyto-index verify-workspace . --changed-only --base origin/mainThe same guarded task workflow is available through the CLI when an MCP client has a stale long-running process.
CI
- run: pip install flyto-indexer
- run: flyto-index scan . --full
- run: flyto-index verify . --strict
- run: flyto-index check . --threshold medium --base mainProjects can keep an accepted baseline and fail only newly worse findings:
flyto-index verify . \
--baseline .flyto-baselines/flyto-indexer.json \
--regression-onlyDesigned To Stay Lean
- The public MCP surface stays at 20 tools instead of growing one tool per
scanner.
- Normal analysis is local and works without a hosted service.
- Generated data stays under
.flyto-index/and can be deleted at any time. - Task continuity is one bounded local SQLite file: terminal history is kept
for at most 90 days and capped at 1,000 runs.
- Flyto2 Indexer reports evidence; it does not auto-edit, auto-commit, or take
over the coding agent.
- Optional precision adapters remain optional. The default install keeps one
runtime dependency.
- Large results are bounded and pageable so they do not flood the agent's
context.
For clients that need a persistent local connection, an optional loopback-only HTTP bridge can keep one MCP process warm and restart it after a failure. See the MCP guide.
Languages
Built-in indexing covers Python, TypeScript and JavaScript, Vue, Go, Rust, Java, Dart, and C/C++. Local language servers and SCIP data can improve reference precision when available; the built-in index remains the fallback. Precision is not presented as identical across languages. The language evidence matrix separates indexing, relationship analysis, security depth, committed positive/negative cases, and known limits.
Evidence, Privacy, And Limits
Target repositories are treated as untrusted input. Static checks do not intentionally import or execute the code being analyzed. Findings include confidence and trace evidence without retaining raw secrets.
The committed offline benchmark covers positive, negative, sanitized, and cross-file cases across Python, JavaScript, TypeScript, and Go. It gates accuracy, false positives, scan errors, and latency on every release. See the reproducible benchmark and security model.
Ignored production Ruff and dependency-isolated, Linux-targeted mypy findings are also held to an exact baseline. They can decrease through reviewed cleanup, but CI blocks new debt and requires every improvement to tighten the baseline immediately.
Documentation
- Choose a guide by your pain
- Problems and capabilities
- CLI guide
- MCP setup and runtime
- Configuration
- Verification
- Learning from AI development problems
- Technical whitepaper
- Real-repository impact case
- Language evidence and limits
- Generated references
The design references explain what was borrowed from Spec Kit, OpenSpec, Gemini CLI, Serena, Grillme, and other projects—and what was deliberately left out to avoid bloat.
Contributing
python -m ruff check .
python -m pytest
python benchmarks/evaluate.py --check
flyto-index verify . --strictSecurity reports: security@flyto2.com.
License
Apache License 2.0. See NOTICE.
<!-- mcp-name: io.github.flytohub/flyto-indexer -->
