# FlowIndex

[![CI](https://github.com/adu3110/flowIndex/actions/workflows/ci.yml/badge.svg)](https://github.com/adu3110/flowIndex/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/flowindex)](https://pypi.org/project/flowindex/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

![FlowIndex demo](.github/assets/demo.gif)

> **File trees and embeddings tell you what exists. FlowIndex tells you what runs, what breaks, and what matters.**

Behavior-first repository indexing for AI coding agents. FlowIndex maps how a codebase behaves: entrypoints, call paths, tests, runtime traces, and git history — so agents understand impact before editing code.

Most coding-agent tools index files, chunks, symbols, or embeddings. FlowIndex indexes **behavior**.

It answers questions like:

- What code path handles this feature?
- What will break if I change this function?
- Which tests should run for this patch?
- Which previous bug fixes touched this area?
- What minimal context should an agent receive before editing?

## Why behavior-first?

File trees and embedding search tell you what *exists*. They do not tell you what *runs*, what *breaks*, or what *matters* when you change a shared module.

FlowIndex builds a local, deterministic behavior graph:

- **Entrypoints** — API routes, webhooks, pages, CLI commands
- **Call paths** — function-to-function relationships from static analysis
- **Tests** — pytest, Jest/Vitest detection linked to symbols
- **Git history** — co-change patterns and bug-fix commit signals
- **Impact** — transparent risk scoring before you edit

No vector database. No LLM calls. No SaaS. Inspectable SQLite.

## How it differs

| Approach | FlowIndex |
|----------|-----------|
| Repo maps / file trees | Behavior graph with entrypoints and call edges |
| Embeddings / RAG | Deterministic lexical + graph ranking |
| Agent frameworks | Developer tool that feeds agents context |
| Generic static analysis | Agent-oriented impact, tests-for, context packs |

## Installation

```bash
pip install flowindex
```

MCP support for Cursor / Claude Code:

```bash
pip install "flowindex[mcp]"
```

From source:

```bash
git clone https://github.com/adu3110/flowIndex.git
cd flowIndex
pip install -e ".[dev]"
```

## Quickstart

```bash
cd your-project
flowindex init          # use --here inside nested example dirs
flowindex scan
flowindex overview
flowindex explain "POST /api/payments"
flowindex impact src/services/ledger.py
flowindex tests-for update_ledger
flowindex context "fix duplicate payments when webhook retries"
```

### Demo

```bash
cd examples/python_fastapi_app
flowindex init --here
flowindex scan
flowindex context "fix duplicate payments when webhook retries"
```

## CLI examples

```bash
# Initialize index in current repo
flowindex init

# Scan and build behavior graph
flowindex scan

# Explain an entrypoint flow
flowindex explain "POST /payments"

# Analyze change impact
flowindex impact services/ledger.py

# Suggest tests for a change
flowindex tests-for services/ledger.py

# Generate agent context pack
flowindex context "fix webhook retry duplicate ledger entries"
```

## MCP usage (Cursor)

Add to Cursor MCP settings (`~/.cursor/mcp.json` or project settings):

```json
{
  "mcpServers": {
    "flowindex": {
      "command": "flowindex",
      "args": ["mcp"],
      "cwd": "/absolute/path/to/your/repo"
    }
  }
}
```

Run `flowindex init && flowindex scan` in that repo first.

Start the server manually:

```bash
flowindex mcp
```

Tools: `get_repo_overview`, `explain_entrypoint`, `get_change_impact`, `suggest_tests`, `make_context_pack`, and more — see [docs/mcp.md](docs/mcp.md).

## Architecture

```mermaid
flowchart LR
  subgraph ingest [Ingest]
    Scan[File Scanner]
    Py[Python Parser]
    TS[TS/JS Parser]
    Git[Git Analyzer]
  end

  subgraph index [Local Index]
    DB[(SQLite)]
    Graph[Behavior Graph]
  end

  subgraph out [Outputs]
    CLI[CLI Commands]
    MCP[MCP Server]
    Pack[Context Packs]
  end

  Scan --> Py
  Scan --> TS
  Py --> Graph
  TS --> Graph
  Git --> Graph
  Graph --> DB
  DB --> CLI
  DB --> MCP
  DB --> Pack
```

## Example context pack

```bash
flowindex context "fix duplicate payments when webhook retries"
```

```md
# FlowIndex Context Pack

## Task
fix duplicate payments when webhook retries

## Likely Relevant Entrypoints
- POST /payments
- POST /stripe/webhook

## Likely Relevant Files
- main.py
- services/ledger.py
- services/payments.py

## High-Risk Symbols
- update_ledger()
- handle_stripe_webhook()

## Tests to Run
- tests/test_payments.py

## Caution
- services/ledger.py has high change risk.
- update_ledger() is shared by refunds and payments.
```

## Limitations

FlowIndex is a static-analysis tool, not a runtime tracer. Here is what works well and what is on the roadmap:

| Claim | Current reality |
|-------|-----------------|
| **Behavior indexing** | Static analysis + git co-change heuristics. Runtime traces not yet ingested. |
| **Call paths** | Cross-file resolution via import graph + named symbol matching. Not a full compiler-grade call graph. |
| **Test selection** | Name similarity, import edges, graph coverage links, co-change patterns. Not coverage-backed. |
| **Git history** | Scoped to the indexed repo root even inside monorepos. Commit relevance is keyword-matched, not coverage-tracked. |
| **TS/JS support** | Heuristic parser: functions, arrow functions, classes, class methods, qualified calls. Tree-sitter is on the roadmap. |
| **Context packs** | Import-aware file ranking. May miss files with no keyword match in their name. |

## Roadmap

- [ ] Tree-sitter parsers for TS/JS and richer call resolution
- [ ] Runtime trace ingestion (OpenTelemetry, test coverage)
- [ ] Cross-repo dependency indexing
- [ ] Patch-aware incremental scan
- [ ] Language servers: Go, Rust, Java

## Research questions

- How much agent error reduction comes from behavior graphs vs embeddings?
- What is the minimal context pack size that preserves patch correctness?
- Can co-change graphs predict test selection better than import graphs alone?
- Which entrypoint classes correlate most with production incidents?

## Contributing

1. Fork and clone the repository
2. `pip install -e ".[dev]"`
3. Make changes with tests
4. `ruff check . && mypy flowindex && pytest`
5. Open a pull request

See [docs/](docs/) for concepts, CLI reference, and examples.

## License

MIT — see [LICENSE](LICENSE).