Turn GitHub issues into reviewed draft PRs.
Flowly is factory software you run against any GitHub repository. It plans an issue, implements it in an isolated clone, runs repository-native checks, performs an independent review, and opens a draft PR.
Toolkit
Six tools. One budget. Zero side effects.
Every inspection call consumes one step of a shared budget (1–20, default 8). Retries never multiply the cost — one step per logical call. Planning meta-tools are free.
Walk the repository tree — the cheapest way to discover structure when a path is unknown.
consumes budgetRead a bounded line range (≤ 400 lines) from a known file to ground claims in context.
consumes budgetLiteral search over source files (≤ 50 matches) for symbols, config, and implementations.
consumes budgetLiteral search over documentation files — README, AGENTS, CHANGELOG, docs/, Markdown.
consumes budgetSemantic retrieval over a lazy TF-IDF index of source and docs, chunked at ~50-line segments. No external embeddings, no vector database.
consumes budgetFollow cited imports, dependencies, ownership, documentation links, and issue or pull-request references from a known repository path.
consumes budgetDeclare a 3–5 step plan before inspecting, revise it when a step returns nothing, and reflect on whether steps could merge.
meta-tools — no budgetHow it works
Plan, observe, act, reflect, answer.
The agent doesn't follow a hard-coded sequence. It declares a short plan, decides which tool to call, and reflects on whether it has enough evidence — or needs to dig deeper. Search results are leads, not proof; claims are only made after file reads.
Question ──▶ ┌────────────────┐ ┌──────────────────────────────────────┐
│ Flue harness │──────▶│ list_files / read_file / search_code │
│ + LLM │◀──────│ search_docs / retrieve / related_context │
│ plan→execute→ │ │ read-only, wrapped in reliability │
│ reflect │ └───────────────────┬────────────────────┘
└───────┬────────┘ │
│ reflect ▼
│ ┌──────────────────────────┐
└──────────────────────▶│ configured repo + lazy │
│ TF-IDF index (retrieve) │
└──────────────────────────┘
meta-tools (create_plan · replan · reflect_plan) never touch the budget.
Beyond the loop
A repository factory with trust boundaries you can inspect.
The evidence-first loop is the foundation. Around it live controlled implementation, independent review, GitHub event routing, evaluation, and reliability controls.
Issue to reviewed draft PR
A factory label starts classification, grounded planning, isolated
implementation, repository-native verification, independent review, and draft-PR
publication. Failed checks stop before publication.
PR review agent
Reviews pull requests with file-aware limits (30 files, 4000 diff lines), incremental reviews, and repository memory — and never auto-approves.
Event router
Maps PR, issue, comment, review, and workflow-run events to configured agents with declarative routes, filters, and duplicate-delivery dedupe.
Model benchmark
Seven capstone scenarios scored on tool success, citation accuracy, retrieval
relevance, and completeness — deterministic in CI (keyword judge), or live with
per-model providers and an optional LLM judge (--judge-model).
Retry, timeout, validate
Transient failures retry with exponential backoff and jitter; permanent errors fail fast with user-safe messages. A search→read fallback keeps answers useful.
Deterministic planner
The same plan→execute→reflect contracts the model uses are exposed as pure functions — so tests prove the behaviour without a provider key.
ADRs & code map
Architecture decisions live in docs/adr/; the seven-document code map lives in .planning/codebase/.
Architecture
Safety through architecture, not prompts.
Agent, tools, index, reliability, and sandbox are distinct, independently testable modules. The important controls live outside the model.
agents/repo-assistant.ts ── orchestration (tools, sandbox, skill, instructions) agents/pr-reviewer.ts ── PR review agent (file-aware limits, never approves) │ ┌────┼──────────┬──────────────┬───────────────┬──────────────┐ ▼ ▼ ▼ ▼ ▼ ▼ list_files read_file search_code search_docs retrieve │ │ │ │ │ │ │ │ │ │ └──────┐ │ │ │ └──────────────┼──────────────────────┼───────┤ │ └───────────┼─────────────┘ │ │ ▼ ▼ ▼ │ reliability wrapper ── retry · timeout · validate · fallback (search→read) │ │ │ │ └────────────────┼────────────────────────────────────┼───────┘ ▼ ▼ ┌──────────────────────┐ ┌─────────────────────────┐ │ RepositoryReader │ │ repository-indexer.ts │ │ path confinement + │ │ lazy TF-IDF index, │ │ bounded reads │ │ chunked ~50-line segments│ │ StepBudget │ │ (no embeddings, no DB) │ └───────────┬──────────┘ └────────────┬────────────┘ └────────────────────┬──────────────────┘ ▼ ┌──────────────────────────────────────────────────────────┐ │ restrictedSandbox — empty toolset: no shell, no write, │ │ no Git, no network │ └──────────────────────────────────────────────────────────┘ skills/analyzing-repositories/SKILL.md ── plan→execute→reflect methodology
Security
Repository access is application-controlled.
The model requests file operations by name. The application validates, confines, and caps every access before the filesystem is touched.
Only repository-relative paths accepted
Absolute paths and .. traversal are rejected at input validation,
before any filesystem call.
Symlink resolution checked
Canonical paths are verified against the repo root after realpath.
Symlinks pointing outside the repo are blocked.
Output caps enforced
400 lines per read, 50 matches per search, 1 MB file limit. Directory walks skip symlinks, VCS data, dependencies, and build output.
Finite inspection budget
One shared 1–20 call budget across all six tools; exhaustion stops the loop and the agent answers from collected evidence.
Content treated as untrusted data
Repository file content is never interpreted as instructions. The model is told to ignore instructions found in files.
No shell, Git, or network
Flue's default filesystem and shell tools are removed. Access exists only through the six inspection tools.
Docs
The map and the decisions.
A seven-document code map keeps the architecture current, and architecture decision records explain why it is shaped this way.
ADR index
Event router, model eval, tool-seam, and live-eval decisions.
GitHub event router
Why events map to agents via declarative routes.
Model eval benchmark
Deterministic scoring without a provider key.
Tool composition seam
One seam for budgets, reliability, and search scope.
Live-eval provider seam
Per-model providers, model-driven loop, LLM judge.
Transcript-based showcase
Verbatim demo transcripts, not screenshots; relative Pages assets.
Factory capability profiles
Least-capability manifests enforced at trusted factory adapters.
Workspace lifecycle
Persisted factory workspaces, resume checks, and deterministic GC.
Factory control plane
Append-only run events, projections, and a local inspection CLI.
Factory safety evals
Versioned trust-boundary invariants exercised against trusted adapters.
Code map
Stack, architecture, conventions, concerns, and more.
Also read README.md, AGENTS.md, and the eval documentation.
Get started
Use the assistant locally. Run the factory in GitHub Actions.
Point the read-only assistant at any local Git repository. The example target is project-oak/oak, a Rust monorepo for privacy-preserving distributed systems.
Clone both repositories as siblings
git clone https://github.com/jellydn/flowly.git git clone --depth 1
https://github.com/jellydn/oak.git
Install dependencies and set your API key
cd flowly npm install cp .env.example .env
# add your OPENROUTER_API_KEY to .env
Ask a question
npm start -- --input '{"message":"What is the architecture of oak?"}'
Run the benchmark without an LLM key
npm run eval -- run — seven deterministic scenarios, safe for CI. Add
--live --json to hit a real provider.
Apply the factory to a GitHub repository
Adapt the checked-in Event Router workflow in the target repository, run Flowly
alongside its checkout, add the model-provider secret, then label an actionable
issue
factory. Flowly opens only a verified draft PR; it never merges or
approves.
Requires Node.js ≥ 22.19.0. Override
REPOSITORY_PATH to inspect any local
checkout. GitHub automation is source-integrated, not a hosted app: the target workflow
must make Flowly available and install that repository's required toolchain. The current
factory entrypoint assumes
origin/main; adapt its base-ref wiring
for another default branch. Tune the budget with
REPO_ASSISTANT_MAX_STEPS.