Flyto2 Indexer

Know what breaks. Prove the fix.

Quick start · Real proof · Documentation

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

Terminal

pip install flyto-indexer
flyto-index setup .
flyto-index verify . --strict

setup builds a local index and configures supported MCP clients. Then ask your agent:

text

impact(target="validateOrder", change_type="rename")

text

7 call sites · 3 projects · 2 test files
Risk: high
Manual review: 1 unresolved dynamic reference

A 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.

text

git grep:  4 matching lines · 1 file
impact:    7 affected functions · 4 files · 0 scan errors
missed by literal search: 4 request handlers

Run the proof yourself:

bash

python scripts/reproduce_impact_case.py --check-snapshot

Read 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:

text

find → understand impact → plan → pass the gate → edit → validate → verify

The public tool names are short:

text

search → impact → task(plan) → task(gate) → edit → task(validate) → verify

search finds the relevant code and concepts.
impact shows what a change can affect.
task keeps decisions, project rules, requirements, and proof connected.
verify checks 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:

text

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.

bash

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 json

Usage 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.

text

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

bash

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/main
flyto-index research-priority . --top 20

The same guarded task workflow is available through the CLI when an MCP client has a stale long-running process.

Research priority

research-priority answers a different question from the rest of the audit: not "is this codebase healthy" but "which code paths are worth a security researcher's next hour". It ranks functions by fusing taint reachability, sink severity, entry-point exposure, complexity, git churn, test gaps, and swallowed error handling, returns one candidate per function, and prints why each one placed where it did.

It is a triage aid, not a verdict. Three properties keep it honest:

Evidence tiers are labelled. A proven source-to-sink flow outranks an unproven lead, and the tier is printed with every candidate. Use --proven-only to drop the unproven tiers entirely.
Unmeasurable signals are reported, not zeroed. No git repository, no index, or a non-Python file makes a signal null; scoring renormalizes over what was actually measured, so a repository without history is not penalized.
Truncation is visible. When a scan hits its caps, the output says so — "found nothing" and "stopped looking" must not look alike.

CI

yaml

- run: pip install flyto-indexer
- run: flyto-index scan . --full
- run: flyto-index verify . --strict
- run: flyto-index check . --threshold medium --base main

Projects can keep an accepted baseline and fail only newly worse findings:

bash

flyto-index verify . \
  --baseline .flyto-baselines/flyto-indexer.json \
  --regression-only

Designed 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

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

bash

python -m ruff check .
python -m pytest
python benchmarks/evaluate.py --check
flyto-index verify . --strict

Security reports: security@flyto2.com.

License

Apache License 2.0. See NOTICE.