<!-- https://logikflow.dev/docs/introduction.md -->

# Introduction

LogiKFlow shows a GitHub pull request with its changed files in a reading order chosen by the author, instead of alphabetically. Files are grouped into sections, explained with notes, and paired with checklists that tell reviewers what to verify.

## Why

GitHub lists changed files by path. A reviewer opening a pull request usually meets the layout files and resources first, then the UI, and only at the end the model or feature flag everything else depends on. They end up reading the change backwards, or jumping around to rebuild the author's mental model.

The author already knows the right order. LogiKFlow lets them write it down once, or ask a coding agent to do it, so every reviewer reads the change the way it was built.

## What you get

- **A reading order.** Files appear in the order they should be read, usually in dependency order: contracts and flags first, then models, logic, storage, UI and resources.
- **Sections and notes.** Related files are grouped under a title, with a short note on what changed and why.
- **Review checklists.** Specific things to verify, such as "With the flag off, the list is unchanged". Each reviewer ticks their own, and everyone sees who checked what.
- **Flow diagrams.** Optionally, your agent draws how the change fits together, and each box opens its file.
- **One change at a time.** Step through the pull request change by change, not just file by file, with the author's notes always in view.
- **Viewed tracking.** Mark files as viewed. It's saved to your account, so it follows you across devices, and it resets for a file when that file changes.
- **History.** Every saved order is a version you can restore.
- **AI agents.** Connect Claude Code, Cursor or another MCP client and say "Arrange PR #123 in LogiKFlow". The agent reads the change, builds the order and gives you the link.

## How it fits your workflow

1. Finish the change and open the pull request on GitHub as usual.
2. Arrange it in LogiKFlow, either by hand in the web app or by asking your agent.
3. Share the LogiKFlow link with reviewers, or post it to the pull request with one click.
4. Reviewers follow the order, tick Viewed and checklist items, and leave their comments on GitHub as usual.

LogiKFlow doesn't replace GitHub reviews. Approvals, comments and merging stay on GitHub. LogiKFlow changes the order and adds context.

## Next steps

- [Quickstart](/docs/quickstart): sign in and arrange your first pull request.
- [Arrange with AI agents](/docs/agents): connect your coding agent.
- [Ordering guide](/docs/ordering-guide): the rules for a good reading order.

---

<!-- https://logikflow.dev/docs/quickstart.md -->

# Quickstart

Arrange your first pull request in about five minutes.

## 1. Sign in

Open [https://logikflow.dev](https://logikflow.dev) and choose **Sign in with GitHub**. LogiKFlow reads pull requests through your GitHub account, so you see exactly what you can see on GitHub.

## 2. Install the app for private repositories

Public repositories work right away. For a private repository, the LogiKFlow GitHub App must be installed on the account or organization that owns it:

1. Open the install page, linked from your dashboard as **Install LogiKFlow**.
2. Choose the account or organization.
3. Pick **All repositories** or only the ones you want.

Organization owners may need to approve the installation. The app asks for read access to code and pull requests, plus write access to pull requests so it can post the review link as a comment.

## 3. Open a pull request

On your dashboard, paste a pull request link such as `https://github.com/acme/app/pull/123`. Or take any pull request URL and replace `https://github.com` with `https://logikflow.dev`:

```text
https://github.com/acme/app/pull/123
https://logikflow.dev/acme/app/pull/123
```

LogiKFlow redirects that to the review page at `https://logikflow.dev/r/acme/app/pull/123`. Tabs such as `/files` or `/commits` at the end of the URL are fine. The same works for a repository (`https://logikflow.dev/acme/app`), which lists its pull requests.

You see the changed files in alphabetical order, like GitHub, until someone saves an order.

## 4. Arrange it

You need write access to the repository.

**By hand:** choose **Arrange files**. Drag files by the handle, or use the arrows, into reading order. Add sections with **Add section**, and add notes and checklist items where they help. Choose **Save order**. See [Arranging a pull request](/docs/arranging).

**With your agent:** connect LogiKFlow to Claude Code or another MCP client once:

```bash
claude mcp add --transport http logikflow https://logikflow.dev/mcp
```

Then, in the repository's checkout, ask:

```text
Arrange PR #123 in LogiKFlow in logical order.
```

See [Arrange with AI agents](/docs/agents).

## 5. Share it

Use **Copy link**, or **Post to PR** to add a comment on the pull request with the link and the section list. Reviewers open the link, sign in, and follow the order. See [Reviewing a pull request](/docs/reviewing).

---

<!-- https://logikflow.dev/docs/arranging.md -->

# Arranging a pull request

The author of a change knows the order it makes sense in. Arrange mode is where you write that down.

## Who can arrange

Anyone with **write access** to the repository (push, maintain or admin on GitHub) can save an order. Everyone who can read the repository can see it. LogiKFlow checks your permission with GitHub on every save.

## Open arrange mode

On the pull request page, choose **Arrange files**. Every changed file is listed, in the current order or alphabetically if nothing is saved yet.

- **Move a file or section:** drag it by the handle (⋮⋮), or use ↑ and ↓. The arrows work with the keyboard too.
- **Add a section:** **Add section** puts a new section at the top. Give it a title, then move it where it belongs. Files below a section belong to it until the next section.
- **Remove a section:** **Remove** deletes the section header. Its files stay where they are.
- **Split a file:** **Split · N** on a file with several changes turns it into one part per change, so you can place each part in the section where it belongs. See [Split a file across sections](#split-a-file-across-sections).
- **Start over:** **Reset to alphabetical** removes all sections, merges split files and sorts the files by path. Notes and checklist items on files are kept.

Nothing changes for reviewers until you choose **Save order**. **Cancel** or Esc discards your edits.

## Overview

The box at the top of arrange mode holds an **overview for reviewers**: two or three sentences on what the change does, how to read it, and where the risk is. Reviewers see it above the first section and at the start of one-change mode, and **Post to PR** puts it in the comment. Leave it empty for a tiny pull request.

## Sections

A section groups files that change for the same reason. Good sections make a large pull request feel like a short story:

| Instead of | Write |
|---|---|
| Kotlin files | Invite model and service |
| Models | Invites are stored per team |
| UI | Invite dialog and pending list |

Three to eight sections suit most pull requests. The [ordering guide](/docs/ordering-guide) has the full rules.

Pick a **layer** for a section from the menu next to its title (contracts and switches, models and types, core logic, storage, application logic, presentation, wiring, resources, build and tooling). Reviewers see it as a label, and **Check order** uses it to spot layers out of order.

## Notes

Sections and files can have a note, shown above the section or the file's diff. Use notes to say *why*, which the diff can't show:

- the reason behind a non-obvious choice;
- what to watch out for;
- that a file is a mechanical rename and can be skimmed.

Wrap code in backticks, for example `` `invitesEnabled` ``, to show it as code.

## Focus labels

Give a file a focus label from the menu next to its path:

- **Key file:** the heart of the change. It's highlighted for reviewers.
- **Skim:** mechanical or low-risk.
- **Generated:** generated or vendored output. It starts collapsed.

Most files need no label. Use **Key file** for one to three files at most, or it stops meaning anything.

## Split a file across sections

A file sometimes holds changes that belong to different sections, such as a shared router or strings file that gets a small addition for each feature. Instead of explaining that in a note, split it:

1. Choose **Split · N** on the file. It becomes N parts, one per change, each showing the line it starts at and its first changed line.
2. Move each part to its section with drag and drop, the arrows or **Move to…**. Parts can hold one change or several.
3. To regroup, drag a change by its row: drop it on another part of the same file to join that part, or between any files or on a section to make a new part there. **Move…** next to each change does the same from the keyboard. A part left with no changes is removed, and its note and checklist move with the change.
4. Give a part its own note, checklist or focus label if it needs one.

To undo, choose **Merge parts** on the file's first part. The parts join back into one card, keeping their notes and checklist items.

Split only when it helps. A reviewer reads most files best in one piece.

Reviewers see each part as its own card, labelled *Part 2 of 3*, with only that part's changes. Viewed is still per file: ticking any part ticks them all. If a later commit adds a change to a split file, it appears in the file's first part.

## Writing for one-change-at-a-time review

Reviewers can step through the order one change (diff hunk) at a time. Your section note and file note stay on screen above each change, so:

- put what a reviewer needs for the *whole file* in the file note;
- when a file mixes several unrelated edits, list them in the note in the order they appear.

## Checklists

Add **checklist items** to a section or a file for things a reviewer should verify:

- "With the flag off, the list is unchanged"
- "Accepting an invite also closes it"
- "Back button closes the dialog before the page"

Each reviewer ticks their own boxes. Everyone sees who checked each item (✓ amal, octo), and each section shows how many items you've checked. Items keep their identity when you move files around or edit other parts of the order, so ticks aren't lost.

Avoid vague items such as "Check for bugs". If an item can't be verified, it doesn't belong on the list.

## Check order

**Check order** compares your draft with the [ordering guide](/docs/ordering-guide#suggestions) and lists tips: a section title that is only a layer name, a key file without a note, a test placed before the file it covers, a file placed before one it imports, a generated file without its label, and more. Tips never block saving; apply the ones that fit. AI agents get the same tips when they save.

## When two people arrange at once

LogiKFlow uses versions. If someone else saves an order while you're editing, your save is stopped and you choose:

- **Load their order**: discard your edits and start from theirs.
- **Overwrite with mine**: save yours as the new version. Theirs stays in history.

## History and restore

**History** lists every saved version with who saved it, when, and whether an AI agent saved it. **Restore** saves an old version again as the newest one, so nothing is ever lost.

## Review progress

The people button in the toolbar shows who has started reviewing, how many files each person has viewed (counting only files that haven't changed since), and how many checklist items they've ticked.

## New commits after arranging

When commits are pushed after the order was saved, a banner says so and how many changed files aren't in the order yet. If you have write access, it offers **Arrange files**, and **Copy agent prompt**, which copies a one-line request you can paste into your agent to re-arrange.

The order stores file paths, so it survives new commits:

- Files you already placed keep their position. Parts of split files keep their changes, because each change is recognised by its content, not its line numbers.
- Files added to the pull request later appear at the end, under **Not in the saved order**. Arrange again to place them.
- Files removed from the pull request disappear from the order.

## Post the link to the pull request

**Post to PR** adds a comment on the GitHub pull request with the review link, the overview, the list of sections with their layer and size, and the key files. It's posted as you, and needs the Pull requests: write permission on the app installation.

After the first post, the button becomes **Update PR comment**. It edits the same comment instead of adding a new one, so re-arranging never clutters the pull request. If the comment was deleted, or someone else posted it and you can't edit it, a new comment is posted.

---

<!-- https://logikflow.dev/docs/reviewing.md -->

# Reviewing a pull request

Open the link the author shared, or any pull request at `https://logikflow.dev/r/<owner>/<repo>/pull/<number>`, and sign in with GitHub.

## Read in order

The toolbar says whose order you're looking at and when it was saved, for example *Reading order by octo · 2 hours ago*. Read top to bottom:

- **How to read this pull request** sits above the first section when the author wrote an overview or made two or more sections. It holds the overview, the list of sections with their layer and how many files you've viewed in each, and the key files to start with. Click a section or a key file to jump to it. Collapse the card with the arrow; LogiKFlow remembers that for this pull request.
- **Sections** start with a title, a layer label such as *Models & types* when the author set one, a note from the author, and sometimes a checklist.
- **File cards** show the diff, with the author's note and checklist above it when there is one.
- **Split files:** an author can split a file whose changes belong to different sections. Each part is its own card, labelled *Part 1 of 2*, and shows only its own changes. The file tree lists each part, marked *1/2*, *2/2*. Viewed is per file, so ticking one part ticks every part.
- The **file tree** on the left follows the same order and highlights the file you're reading. Type in the filter box to find a file by path.

Diffs over 400 changed lines, and files the author labelled **Generated**, start collapsed. Open one with the arrow in its header. Collapse a whole section with the arrow next to its title. Each section shows how many of its files you've viewed.

### Focus labels

Authors can label files so you know where to spend your attention:

| Label | Meaning |
|---|---|
| **Key file** | The heart of the change. Read it carefully. |
| **Skim** | Mechanical or low-risk, such as a rename or a string. |
| **Generated** | Generated or vendored output. Collapsed by default. |

### Comments

A speech-bubble count in a file's header, and in the file tree, shows how many review comments the file has on GitHub. Click it, or the GitHub icon, to open that file's diff on GitHub.

## Diagram

When the author's agent has drawn a flow diagram, a **Diagram** tab appears next to **All files** and **One change** (or press `d`). It shows how the pieces of the change connect: each box is a step or a piece of code, grouped into areas, with labelled arrows.

- **Click a box** to open its file, or the exact change it points to. Boxes that open something show ↗.
- **Hover a box** to highlight what it connects to.
- **Move around:** a large diagram opens at a readable size, starting from the left. Drag to pan, pinch or Ctrl and scroll to zoom, and **Fit** (or `0`) to see it all. `+` and `-` zoom from the keyboard.
- **Full screen:** the button next to the zoom controls (or `Shift`+`F`) gives the diagram the whole screen. Press Esc or the same button to come back.
- **List** shows the same diagram as a list, which reads better on a phone and with a screen reader. Phones start with the list.
- If commits were pushed after the diagram was drawn, it says so; ask the author to redraw it.

If there's no diagram and you have write access, the tab offers a prompt to copy into your agent.

## One change at a time

A file can hold several unrelated edits. Switch the toolbar from **All files** to **One change** (or press `f`) to review one change area at a time, in reading order:

- You see the current section's title, note and checklist, the file's header and the author's note, and just **one change** from that file. The overview card shows on the first change.
- The step bar shows where you are, for example *Change 7 of 42 · invite-service.ts · 2 of 3 here*, with a progress bar. For a split file it also says which part you're in.
- **Next change ›** moves within the file; at the file's last change it becomes **Next file ›**. Use `]` and `[` from the keyboard, or swipe left and right on a phone.
- On a file's last change, **Mark viewed and continue** marks the file viewed and takes you to the next file you haven't viewed.
- Clicking a file in the file tree jumps to its first change. `j` and `k` still move a whole file at a time.
- The address bar updates as you go (`#change-12-1`), so you can share a link to one exact change.

Choose **All files** (or press `f` again) to go back to the full list. Your choice is remembered.

## View settings

The gear button in the toolbar holds the diff settings. Your choices are remembered in this browser.

- **Unified** (one column) or **Split** (old and new side by side).
- **Hide whitespace:** hides lines whose only change is whitespace, such as indentation.
- **Compact line height:** fits more lines on screen.
- **Collapse imports:** folds 3 or more import lines in a row into one line, such as *8 import lines · +2 −1*, so the real change comes first. Click it to see the imports. It understands imports in JavaScript and TypeScript, Python, Kotlin, Java, Go, Rust, Swift, C and C++, C#, PHP, Ruby and Dart, including imports that span several lines.
- **One change at a time:** the same as the toolbar switch.
- **Expand all** and **Collapse all**.

Changed lines also highlight the exact characters that changed.

## Keyboard shortcuts

| Key | Action |
|---|---|
| `j` / `k` | Next or previous file |
| `n` | Next file you haven't viewed |
| `v` | Mark the current file viewed and go to the next one |
| `e` | Expand or collapse the current file |
| `o` | Open the current file in GitHub |
| `s` | Switch between unified and split |
| `f` | One change at a time on or off |
| `]` / `[` | Next or previous change, in one-change mode |
| `d` | Diagram on or off, when the pull request has one |
| `?` | Show all shortcuts |

## Viewed

Tick **Viewed** on a file when you're done with it. The card collapses and the file tree shows a check.

- Viewed is saved to your account, so it follows you to other devices and browsers.
- It's tied to the file's content. If the author pushes a change to that file, it becomes unviewed again, so you never miss a change.
- When that happens, the file shows **Changed since you viewed**. Choose it to see only what changed since you last looked, instead of the whole diff again. Choose **Show full diff** to switch back.
- **Clear viewed** unticks every file in the pull request at once, for when you want to start the review again.

The meter in the toolbar shows how many files you've viewed. The people button next to it shows everyone's progress: files viewed and checklist items ticked.

## Checklists

Tick checklist items as you verify them. Your ticks are saved and shown to everyone: each item lists who checked it, and each section shows how many you've checked. Untick an item to take your check back.

## Comments and approval

Leave review comments and approvals on GitHub as usual; **Open on GitHub** takes you there. LogiKFlow is for reading the change in the right order. It doesn't replace GitHub's review tools.

## Refresh

**Refresh** reloads the pull request from GitHub, including new commits and the latest saved order.

---

<!-- https://logikflow.dev/docs/conventions.md -->

# Repository conventions

Every team has its own idea of the right reading order. A conventions file tells LogiKFlow and your AI agents how *your* repository should be arranged, so every pull request in it is ordered the team's way.

## Add the file

Create `.github/logikflow.md` on the repository's default branch. It's plain Markdown: write what you'd tell a new teammate about reviewing this code base.

LogiKFlow reads the file from the pull request's **base branch**, so a PR that changes the conventions is still arranged by the current rules.

## What agents do with it

When an agent calls `get_pull_request`, the file comes back as `repoConventions`, and `get_ordering_guide` includes it too if you pass the owner and repo. The [ordering guide](/docs/ordering-guide) tells agents to follow your conventions, and that **your rules win** where they conflict with the general ones.

## A checklist section

Any heading that contains the word **checklist** starts a list of default checklist items. In arrange mode, **Add the team checklist** adds them to the order in one click, and agents add them to the most relevant section. Up to 20 items are used.

## Diagrams

Add a `diagram:` line anywhere in the file to decide whether agents draw a [flow diagram](/docs/agents#diagrams):

- `diagram: ask` (the default): after arranging, the agent asks the person whether they want one.
- `diagram: always`: the agent draws one for every pull request, without asking.
- `diagram: never`: the agent never offers one.

## Example

This is what a conventions file for an Android app might look like:

```markdown
# Reviewing this repository

## Order
- Feature flags and settings keys first, then models, then storage.
- Controllers before views; dependency injection and app wiring go last.
- Put XML layouts after the Kotlin that inflates them, and strings last.
- Keep `build.gradle` and version catalog changes in their own section at the top.

## Notes
- Anything behind a flag: say what happens with the flag off.
- Mention if a change affects startup time or scrolling performance.

## Checklist
- With the flag off, behaviour is unchanged
- No disk or network work on the main thread
- New strings are in `strings.xml`, not hard-coded
- Analytics events fire once per action

diagram: ask
```

## Tips

- Keep it short. A page of clear rules beats a long style guide.
- Say *why* when a rule isn't obvious. Agents follow reasons better than bare orders.
- Only the first 20,000 characters are read.

---

<!-- https://logikflow.dev/docs/extension.md -->

# Browser extension and link previews

## The browser extension

**LogiKFlow for GitHub** adds a small LogiKFlow button to the bottom-right corner of every GitHub pull request page, so it never covers the diff. A dot on it shows the status: green when a reading order exists, amber when it needs an update, none when there's no order. By default the button is Flo, the LogiKFlow mascot, who blinks, follows your cursor and waves when you hover. If you'd rather have a plain icon, open the extension's popup from the toolbar and choose **Icon** under **Button on GitHub**; the change applies right away. Hover over the button, or tab to it, to expand it into **Open in LogiKFlow** with a badge that tells you at a glance:

- **Reading order · 4 sections · by octo:** an order exists. Click to open it.
- **needs update:** commits were pushed after the order was saved.
- **No reading order yet · arrange it:** there's no order, and you can write to the repository. The button opens straight into arrange mode.
- **Sign in to see the order:** sign in to LogiKFlow in the same browser.

It works in Chrome, Edge, Brave, Arc and other Chromium browsers.

### Install

Until it's listed in the Chrome Web Store:

1. [Download the extension package](/downloads/logikflow-extension.zip) and unzip it.
2. Open `chrome://extensions` and turn on **Developer mode**.
3. Choose **Load unpacked** and select the unzipped folder.

The extension's toolbar icon opens a small menu: **Open LogiKFlow**, and the choice between Flo and a plain icon for the button on GitHub.

### Privacy

The extension only runs on `github.com` and only talks to `logikflow.dev`. It sends the repository and pull request number of the page you're viewing, using your existing sign-in, and stores nothing but your button choice. It can't read or reach any other site.

## Link previews in Slack, Teams and elsewhere

When you paste a LogiKFlow review link into Slack, Microsoft Teams, Discord, LinkedIn or similar, it shows a preview card.

- **Public repositories:** the card shows the pull request title, the section outline (for example *Flag and schema → Invite model and service → API*), the number of changed files, and how many reviewers have started.
- **Private repositories:** the card is generic, "Pull request review · LogiKFlow". The services that fetch previews aren't signed in, so LogiKFlow never shows them private details.

The preview image and text for public pull requests are refreshed every few minutes.

---

<!-- https://logikflow.dev/docs/agents.md -->

# Arrange with AI agents

Once your pull request is open, ask your coding agent to arrange it. The agent reads the change, orders the files so each comes after what it depends on, groups them into sections with notes and checklists, saves the order, and gives you the link.

```text
Arrange PR #123 in LogiKFlow in logical order.
```

LogiKFlow is a remote [MCP](https://modelcontextprotocol.io) server, so it works with any agent that supports remote MCP servers with OAuth.

## Connect

The server URL is:

```text
https://logikflow.dev/mcp
```

### Claude Code

```bash
claude mcp add --transport http logikflow https://logikflow.dev/mcp
```

Then run `/mcp` in Claude Code, select **logikflow**, and choose **Authenticate**. Add `--scope user` to the command to make it available in every project, not just the current one.

### Cursor

Add to `~/.cursor/mcp.json`, or `.cursor/mcp.json` in a project:

```json
{
  "mcpServers": {
    "logikflow": { "url": "https://logikflow.dev/mcp" }
  }
}
```

### VS Code

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "logikflow": { "type": "http", "url": "https://logikflow.dev/mcp" }
  }
}
```

### Other clients

Add a remote server that uses the streamable HTTP transport, with the URL above. The client registers itself automatically.

### Signing in

The first time, your browser opens a LogiKFlow page asking whether the app may act for you. It shows which app is asking and where access is sent. Choose **Allow**, then sign in with GitHub. For private repositories, the LogiKFlow GitHub App must be installed on the owning account or organization; see [Quickstart](/docs/quickstart#2-install-the-app-for-private-repositories).

## Ask

Run the agent from the repository's checkout. It can then read the whole codebase, not just the diff, and the order is much better.

```text
Arrange PR #123 in LogiKFlow in logical order.
```

```text
Create a LogiKFlow review for https://github.com/acme/app/pull/123 and add review checklists.
```

```text
Arrange the open PR for this branch in LogiKFlow.
```

```text
I pushed new commits to PR #123. Re-arrange it in LogiKFlow and keep the existing sections where they still fit.
```

Say what you care about and the agent takes it into account, for example "put the migration first" or "keep the tests at the end".

## What the agent does

1. Reads the [ordering guide](/docs/ordering-guide) with `get_ordering_guide`.
2. Fetches the changed files and any saved order with `get_pull_request`.
3. Studies the change, locally if it can, or from the patches.
4. Saves the order with `save_reading_order`.
5. Replies with the review link.
6. Asks whether you'd like a diagram, unless the pull request is small or your repository decides for it (see below).

## Diagrams

An agent can also draw a **flow diagram** of the change: boxes for each step or piece, grouped and connected with labelled arrows, laid out automatically. Reviewers open it from the **Diagram** tab on the pull request, and clicking a box opens its file, or the exact change inside it.

Diagrams are optional. After arranging, the agent asks whether you want one. Answer yes or no, or ask for one directly:

```text
Draw a flow diagram of PR #123 in LogiKFlow.
```

```text
Redraw the LogiKFlow diagram for PR #123; the retry path changed.
```

Redrawing replaces the diagram without touching the reading order. To stop the question, or to get a diagram every time, add a `diagram:` line to your [conventions file](/docs/conventions#diagrams). People with write access can remove a diagram from the Diagram tab.

The [MCP reference](/docs/mcp-reference) documents each tool.

## Safety

- **The agent acts as you.** It reads only what your GitHub account can read, and saves only on repositories where you have write access.
- **It can't drop or invent files.** Every changed file must appear exactly once, or nothing is saved and the agent gets the list to fix. Diagram boxes can only link to files and changes that are in the pull request.
- **It can't silently overwrite.** If someone saved a new order in the meantime, the agent gets a conflict and asks you.
- **It's labelled.** Orders saved by an agent say *arranged by octo's AI agent* on the page and in History, and any earlier version can be restored.
- **You can disconnect.** Remove the server from your agent.

## Troubleshooting

| Message | What to do |
|---|---|
| GitHub access for this connection has expired | Reconnect: in Claude Code, `/mcp`, then **Authenticate**. |
| This pull request doesn't exist or this account can't see it | Check the owner, repo and number. For a private repository, install the GitHub App on the owning account. |
| doesn't have write access | Only people who can push to the repository can save an order. |
| The order must list every changed file exactly once | The agent will usually fix this itself. If it doesn't, ask it to call `get_pull_request` again and include every file. |
| Conflict | Someone saved a newer order. Ask the agent to fetch it and decide whether to replace it. |
| Rate limited | Wait a minute. The limit is 120 requests per minute per person. |

---

<!-- https://logikflow.dev/docs/ordering-guide.md -->

# Ordering guide

How to arrange a pull request's changed files into a reading order for reviewers. It applies to people using arrange mode and to AI agents, which receive this page from the `get_ordering_guide` tool.

The goal: a reviewer who reads top to bottom always meets a piece of code after the things it depends on, and understands why each group of files changed.

## Workflow for agents

1. Call `get_pull_request` with the owner, repo and number. It returns every changed file, the current saved order (if any) and its `version`, and `repoConventions` when the repository has a `.github/logikflow.md` file. **Follow the repository's conventions: where they conflict with this guide, they win.** Add their checklist items to the most relevant section.
2. Understand the change. If you are running inside a checkout of the repository, read the diff and the surrounding code there (for example `git diff <base>...<head>`); that gives far better results than patches alone. Otherwise call `get_pull_request` again with `include_patches: true`. Files with more than one change also carry `changes`, with an `id` for each change; you need these only to [split a file across sections](#splitting-a-file-across-sections).
3. Build the order following the rules below: an [overview](#overview), [sections](#sections) with a `layer`, and files in dependency order. Use the [reading hints](#reading-hints) on each file to check yourself.
4. Call `save_reading_order` with `base_version` set to the `version` you received (0 when there was no order). If it reports missing or unknown paths, fix the list and save again. If it reports a conflict, someone else saved in the meantime: fetch again, and only overwrite if the user wants that.
5. If the result lists `suggestions`, apply the ones that fit and save once more with the new `version`. One revision is enough: see [Suggestions](#suggestions).
6. Tell the user the review link returned by the save.
7. Follow the save result's `nextStep` about a diagram. Diagrams are optional: see [Diagrams](#diagrams).

## Ordering rules

Order by dependency: a file comes after the files it uses, before the files that use it. When there is no dependency between files, use these layers, top to bottom:

1. **Contracts and switches**: feature flags, remote config, constants, API schemas, database migrations, public interfaces, event names.
2. **Models and types**: data classes, DTOs, enums, type definitions.
3. **Core logic and utilities**: pure functions, parsers, algorithms, helpers the rest builds on.
4. **Storage and data access**: repositories, caches, persistence, network clients.
5. **Application logic**: controllers, services, view models, use cases, state holders.
6. **Presentation**: views, components, adapters, screens, templates.
7. **Wiring**: dependency injection, routing, entry points, platform glue that only connects the pieces above.
8. **Resources**: layouts, drawables, styles, strings, dimensions, assets, translations. Put the main screen layout before the small pieces it includes.
9. **Build and tooling**: build scripts, CI, lint config, generated files, lockfiles.

A section can name its layer with `layer`: `contracts`, `models`, `logic`, `storage`, `app`, `ui`, `wiring`, `resources` or `tooling`, in that order. Reviewers see it next to the section title, and the save checks that layers come in order.

Tests go directly after the file they test, not in a separate block at the end, unless a test covers many files at once; then put it after the last of them.

Other rules:
- Deleted files go next to the file that replaced them, so the reviewer compares old and new together.
- A renamed or moved file with no real changes goes in the Build and tooling section or the last section.
- If one file is the heart of the change, it may come first with a note, even if it depends on small files; say so in the section note.
- Every changed file appears exactly once, unless you split it (below). Do not invent paths.

## Reading hints

`get_pull_request` adds up to three hints to a file when it can work them out. They come from paths and from the import lines visible in the diff, so treat them as a starting point and confirm against the code.

- `dependsOn`: changed files this file imports. A file should come after everything in its `dependsOn`, unless a note says why not. Imports that didn't change aren't in the diff, so the list can be incomplete.
- `testOf`: the changed file this test covers, from naming conventions such as `foo.test.ts`, `FooTest.kt`, `test_foo.py` and `foo_test.go`. Put the test directly after that file.
- `likelyGenerated`: a lockfile, or minified, vendored or generated output. Label it `generated`.

## Overview

Write an `overview` of two or three sentences. Reviewers read it before the first section, it opens one-change mode, and it goes into the pull request comment. Say:

1. what the change does, in one sentence that isn't the pull request title;
2. the reading path: "Start with the flag and migration, then the service, then the dialog";
3. where the risk is, or what to read slowly: "The retry loop in `InviteService` is the part to check."

Skip it only for a tiny pull request where the section notes already say everything.

## Sections

Group the files into 3 to 8 sections. A very small pull request (under 5 files) can use one section or none.

- **Title**: a short noun phrase naming what the group does in this change, such as "Feature flag and schema" or "Invites are stored per team". Not a file type ("Kotlin files") or a layer name alone ("Models"). Read your titles top to bottom: together they should tell the story of the change.
- **Layer**: the layer from [Ordering rules](#ordering-rules) this section belongs to, when one fits. Reviewers see it as a label next to the title.
- **Note**: one to three plain sentences saying what changed and why, and anything the reviewer should keep in mind. When it isn't obvious, open with how this section builds on the previous one: "Uses the `invitedAt` field from Part 1." Name concrete classes, functions or flags in `backticks`. Don't restate the file list.

## File notes

Add a note to a file only when it helps the review: a non-obvious reason, a risk, a follow-up, or "mechanical rename, skim". Most files need no note. Keep notes to one or two sentences.

Reviewers can step through a pull request **one change (diff hunk) at a time**, and they see the file's note above every change in that file. When a file holds several unrelated changes, say so in the note and name them in the order they appear, for example: "Two changes: the new `invitesEnabled` check, then the rename of `listMembers`." If those changes belong to different sections, split the file instead.

## Splitting a file across sections

Sometimes one file holds changes that belong to different parts of the story, such as a new model field near the top and the screen code that uses it further down. You can split that file so each part appears in the section it belongs to.

Split only when it really helps. Most files should stay whole: a reviewer reads a file more easily in one place. Good reasons to split:

- a shared file (a router, a strings file, a DI module, a large view model) that gets small unrelated additions for several features in the pull request;
- one change in a file is a prerequisite that has to be read early, and the rest only makes sense later.

How to split:

1. Take the change IDs from `files[].changes` in `get_pull_request`. Only files with two or more changes have them.
2. List the file once in each section where part of it belongs, with `hunks` naming the changes for that part, in any order. Each change goes in exactly one part.
3. Optionally, list the file once more *without* `hunks`. That part takes every change you didn't name, including changes from commits pushed later. Without it, every change must be named, and later changes join the first part.

Each part can have its own `note`, `checks` and `focus`. Give each part a short note saying what that part does, for example "Part 1: the new `invitedAt` field; the screen that shows it is in *Invite dialog*."

Change IDs come from each change's content, not its line numbers, so they stay the same when other changes move the lines around. If a part names an ID that no longer exists, the save is rejected with the current IDs to use.

## Focus labels

A file can carry one focus label:

- `key`: the heart of the change, where most of the review effort should go. Use it for one to three files, never most of them. Every key file needs a note saying what to look for; a key label without one tells the reviewer to read carefully but not what for.
- `skim`: mechanical or low-risk, such as renames, string changes and simple wiring.
- `generated`: generated, vendored or lock files. They start collapsed for reviewers.

Leave most files without a label.

## Checklists

Checklist items tell the reviewer what to verify. Add them to a section or file when there is something specific and checkable:

- Good: "With the flag off, the list is identical to before", "`acceptInvite` also closes the invite", "Back button closes the dialog before the page".
- Bad: "Code looks good", "Check for bugs", "Review this file".

Use 0 to 4 items per section and at most one or two per file. Keep each item under 120 characters.

## Suggestions

`save_reading_order` saves first, then checks the order against this guide. The result's `suggestions` list what would make it easier to follow: a section titled with a layer name, a key file without a note, more than three key files, a vague checklist item, a test placed before the file it covers, a file placed before one it imports, a generated file without its label, a missing overview, and similar. Nothing in the list blocks the save, and `get_pull_request` shows the same list for the current order.

Apply the suggestions that fit and save once more with the returned `version`. Skip one when you have a reason, and put the reason in the note it concerns. One revision is enough; don't loop.

## Diagrams

A diagram is an optional picture of how the pieces of the change connect. Reviewers open it from the **Diagram** tab, and each box can open its file or one exact change. Save one with `save_diagram`; it never touches the reading order.

### When to draw one

Follow `nextStep` from `save_reading_order` and the repository's `diagramPreference` from `get_pull_request`:

- `never`: don't offer or draw one.
- `always`: draw one for every pull request, without asking.
- `ask` (the default): after saving the order, ask the user once whether they'd like a diagram, unless the pull request is small (under 4 files) or they already answered in this conversation. Draw one only if they say yes, or they asked for one in the first place.

A diagram helps when behaviour flows across several files: a request passing through layers, an event and what reacts to it, a state machine, a fallback path. Skip it for renames, dependency bumps, copy changes or a pull request that is mostly one file.

### How to draw a good one

- **4 to 20 nodes.** One node is one step or one piece in the flow, not one file. Leave out files that don't take part in the flow (tests can be one node per behaviour they cover).
- **Titles are short verbs or nouns:** "Check cycle", "Queue outer boundary", "Invite model". Up to 80 characters; 2 to 4 words is best.
- **`kind`** sets the colour and icon:
  - `trigger`: where the flow starts, such as a user action, event, request or cron job.
  - `logic`: code that decides or transforms.
  - `decision`: a branch point.
  - `data`: models, storage, caches, migrations.
  - `ui`: screens, views, components.
  - `test`: tests that cover part of the flow.
  - `config`: flags, settings, build and wiring.
  - `external`: services and libraries outside the repository.
  - `warning`: a fallback, error path or known risk.
- **`lines`** add up to 4 short `label: text` rows. Useful labels are `change` (what this pull request changes here), `role`, `example`, `returns` and `why`. Keep each under 80 characters and wrap code in backticks.
- **`file`** links the node to a changed file. Add **`hunk`** with an id from `files[].changes` to point at one change. Only use paths and ids from `get_pull_request`.
- **Edges** go in the direction things happen or depend: caller to callee, event to handler, code to the test that covers it. Label them with 1 to 3 words ("walk graph", "covered by", "on error"). Use `dashed: true` for optional or indirect links.
- **Groups** (up to 12) draw a box around nodes that belong together, such as "Server", "Client payload" or "Regression coverage". Use the same names as your sections when they match.
- Give the diagram a `title` that says what it shows, such as "How an invite is accepted".

The layout is automatic, left to right, so you only describe the pieces and how they connect. Base `base_version` on `diagramBaseVersion` from `get_pull_request`. When the user asks to redraw, fetch again, start from `currentDiagram.diagram` and change what's needed.

## Style

Write for a busy reviewer: short, specific, no filler, no marketing tone, no emoji. Use the terms the code uses.

---

<!-- https://logikflow.dev/docs/mcp-reference.md -->

# MCP reference

LogiKFlow's MCP server lets an agent read a pull request and save its reading order.

| | |
|---|---|
| Endpoint | `https://logikflow.dev/mcp` |
| Transport | Streamable HTTP (stateless, JSON responses) |
| Authorization | OAuth 2.1 with PKCE; scope `reviews` |
| Server name | `logikflow` |

## Tools

### get_ordering_guide

Returns the [ordering guide](/docs/ordering-guide) as Markdown. Call it once before saving an order. It takes no input and is read-only.

### get_pull_request

Returns a pull request's changed files with reading hints, the saved order and its version, whether you may change the order, and the review link. Read-only.

| Input | Type | Required | Description |
|---|---|---|---|
| `owner` | string | yes | Repository owner, for example `acme` |
| `repo` | string | yes | Repository name, for example `app` |
| `number` | integer | yes | Pull request number |
| `include_patches` | boolean | no | Include each file's diff. Default `false`. Each file is capped at 20,000 characters and the response at 400,000. |

Result (JSON text):

```json
{
  "reviewUrl": "https://logikflow.dev/r/acme/app/pull/123",
  "repository": "acme/app",
  "pullRequest": {
    "number": 123, "title": "Add team invites", "state": "open",
    "author": "octo", "base": "main", "head": "team-invites", "headSha": "9fce14f", "url": "https://github.com/acme/app/pull/123"
  },
  "canArrange": true,
  "filesTruncatedByGitHub": false,
  "files": [
    { "path": "models/invite.ts", "status": "added", "additions": 20, "deletions": 0 },
    { "path": "services/invite-service.ts", "status": "added", "additions": 112, "deletions": 0, "dependsOn": ["models/invite.ts"] },
    { "path": "services/invite-service.test.ts", "status": "added", "additions": 60, "deletions": 0, "dependsOn": ["services/invite-service.ts"], "testOf": "services/invite-service.ts" },
    { "path": "package-lock.json", "status": "modified", "additions": 4, "deletions": 4, "likelyGenerated": true },
    {
      "path": "app/router.ts", "status": "modified", "additions": 9, "deletions": 1, "dependsOn": ["services/invite-service.ts"],
      "changes": [
        { "id": "h1pdwiwd", "header": "@@ -12,6 +12,7 @@ import", "preview": "+ import { invites } from \"./invites\";", "additions": 1, "deletions": 0 },
        { "id": "hyzm99a", "header": "@@ -40,4 +41,12 @@ export const routes", "preview": "+ { path: \"/invites\", view: invites },", "additions": 8, "deletions": 1 }
      ]
    }
  ],
  "currentOrder": null,
  "baseVersion": 0
}
```

`currentDiagram`, when a diagram exists, has `version`, `updatedBy`, `savedBeforeLatestCommits` and `diagram` (the same shape `save_diagram` takes). `diagramBaseVersion` is its version, or `0`. `diagramPreference` is `always`, `ask` or `never`, from the repository's conventions file (`ask` when it doesn't say).

`currentOrder`, when an order exists, has `version`, `updatedBy`, `source` (`web` or `agent`), `savedBeforeLatestCommits` (true when commits were pushed after it was saved), `overview` (when one was written), `sections` in the same shape `save_reading_order` takes, and `suggestions`: what would make the current order easier to follow (see [Suggestions](/docs/ordering-guide#suggestions)). `status` is GitHub's: `added`, `removed`, `modified`, `renamed`, `copied`, `changed` or `unchanged`. Renamed files also have `previousPath`. Files with two or more changes (diff hunks) have `changes`, one entry per change: `id` (use it in `hunks` to split the file), `header` (the `@@` line), `preview` (the first changed line, up to 120 characters), `additions` and `deletions`. IDs come from the change's content, so they survive line shifts from other changes.

Reading hints appear on a file only when LogiKFlow could work them out: `dependsOn` (changed files it imports, from import lines visible in the diff), `testOf` (the changed file this test covers, from naming conventions) and `likelyGenerated` (lockfiles and minified, vendored or generated output). See [Reading hints](/docs/ordering-guide#reading-hints).

### save_reading_order

Saves the reading order, replacing the current one. Earlier versions stay in history. Requires write access to the repository.

| Input | Type | Required | Description |
|---|---|---|---|
| `owner` | string | yes | Repository owner |
| `repo` | string | yes | Repository name |
| `number` | integer | yes | Pull request number |
| `base_version` | integer | yes | `baseVersion` from `get_pull_request`; `0` when no order exists |
| `overview` | string | no | Up to 2,000 characters: two or three sentences reviewers read before the first section. Backticks render as code. |
| `sections` | array | yes | 1 to 50 sections, in reading order |

Each section:

| Field | Type | Description |
|---|---|---|
| `title` | string, optional | Up to 200 characters. Omit only for a single untitled group in a tiny pull request. |
| `layer` | string, optional | `contracts`, `models`, `logic`, `storage`, `app`, `ui`, `wiring`, `resources` or `tooling`. Shown next to the title. |
| `note` | string, optional | Up to 4,000 characters. Backticks render as code. |
| `checks` | string[], optional | Up to 20 checklist items, each up to 300 characters |
| `files` | array | Files in reading order: `{ "path", "note"?, "checks"?, "focus"?, "hunks"? }` with the same limits. `focus` is `key`, `skim` or `generated`. `hunks` is a list of change IDs; see below. |

### Splitting a file into parts

To show a file's changes in different sections, list the file more than once, each time with `hunks` naming the change IDs for that part:

- Each change ID may appear in only one part of the file.
- At most one appearance may leave out `hunks`. It takes every change not named elsewhere, including changes from later commits.
- If every appearance has `hunks`, every change of the file must be named.
- Files that GitHub gives no diff for (binary or very large) can't be split.

```json
{ "title": "Routes", "files": [{ "path": "app/router.ts", "hunks": ["hyzm99a"], "note": "Part 2: the `/invites` route." }] }
```

Example input:

```json
{
  "owner": "acme", "repo": "app", "number": 123, "base_version": 0,
  "overview": "Adds team invites behind the `invitesEnabled` flag. Start with the flag and migration, then the model and service, then the dialog that calls it. The replace-on-reinvite rule in `InviteService` is the part to read slowly.",
  "sections": [
    {
      "title": "Flag and schema",
      "layer": "contracts",
      "note": "Everything new is behind `invitesEnabled`, off by default.",
      "checks": ["With the flag off, the members page is unchanged"],
      "files": [{ "path": "lib/flags.ts" }, { "path": "db/migrations/0003_invites.sql" }]
    },
    {
      "title": "Invite model and service",
      "layer": "logic",
      "note": "Builds on the schema above. `InviteService` owns the lifecycle; the model is a plain record.",
      "files": [
        { "path": "models/invite.ts" },
        { "path": "services/invite-service.ts", "note": "Re-inviting the same email replaces the open invite.", "focus": "key" }
      ]
    }
  ]
}
```

Result:

```json
{ "saved": true, "version": 1, "reviewUrl": "https://logikflow.dev/r/acme/app/pull/123", "overview": true, "sections": 2, "files": 4, "checklistItems": 1, "suggestions": [], "nextStep": "Done. Share the review link with the user. The pull request is small, so skip the diagram unless the user asks for one." }
```

`suggestions` lists what would make the order easier to follow, in plain sentences the agent can act on; it is empty when the order follows the [ordering guide](/docs/ordering-guide#suggestions). The save already happened, so the agent applies what fits and saves again with the new version. `nextStep` says so when there are suggestions, then tells the agent what to do about a diagram: nothing, ask the user, or draw one because the repository wants one for every pull request.

A checklist item with the same text in the same section or file keeps its identity across saves, so reviewers' ticks survive a re-arrange.

### save_diagram

Saves an optional flow diagram, shown in the pull request's **Diagram** tab. It replaces the current diagram and doesn't change the reading order. Requires write access to the repository. See [Diagrams](/docs/ordering-guide#diagrams) in the ordering guide for when and how to draw one.

| Input | Type | Required | Description |
|---|---|---|---|
| `owner`, `repo`, `number` | | yes | As above |
| `base_version` | integer | yes | `diagramBaseVersion` from `get_pull_request`; `0` when there is no diagram |
| `diagram` | object | yes | `{ "title"?, "groups"?, "nodes", "edges" }` |

| Field | Type | Description |
|---|---|---|
| `title` | string, optional | Up to 200 characters |
| `groups` | array, optional | Up to 12 boxes: `{ "id", "title", "note"? }`. Titles up to 80 characters. |
| `nodes` | array | 2 to 40: `{ "id", "title", "kind"?, "group"?, "lines"?, "file"?, "hunk"? }`. `kind` is `trigger`, `logic` (default), `decision`, `data`, `ui`, `test`, `config`, `external` or `warning`. `lines` is up to 4 `{ "label", "text" }` rows. `file` must be a changed file; `hunk` a change id of that file. |
| `edges` | array | Up to 80: `{ "from", "to", "label"?, "dashed"? }`, between node ids. Labels up to 40 characters. |

Ids are 1 to 40 letters, digits, `-` or `_`, unique across groups and nodes.

```json
{
  "owner": "acme", "repo": "app", "number": 123, "base_version": 0,
  "diagram": {
    "title": "How an invite is accepted",
    "groups": [{ "id": "server", "title": "Server" }, { "id": "tests", "title": "Coverage" }],
    "nodes": [
      { "id": "link", "title": "Invite link opened", "kind": "trigger", "lines": [{ "label": "example", "text": "/invite/abc123" }] },
      { "id": "accept", "title": "Accept invite", "kind": "logic", "group": "server", "file": "services/invite-service.ts", "lines": [{ "label": "change", "text": "closes the invite after joining" }] },
      { "id": "expired", "title": "Reject expired", "kind": "warning", "group": "server", "file": "services/invite-service.ts" },
      { "id": "spec", "title": "Invite service spec", "kind": "test", "group": "tests", "file": "services/invite-service.test.ts" }
    ],
    "edges": [
      { "from": "link", "to": "accept", "label": "token" },
      { "from": "accept", "to": "expired", "label": "if expired" },
      { "from": "accept", "to": "spec", "label": "covered by", "dashed": true }
    ]
  }
}
```

Result:

```json
{ "saved": true, "version": 1, "diagramUrl": "https://logikflow.dev/r/acme/app/pull/123#diagram", "nodes": 4, "edges": 3, "groups": 2, "linkedFiles": 2 }
```

## Errors

Tool errors come back as a result with `isError: true` and a message the agent can act on. Nothing is saved when a save fails.

| Situation | Message starts with |
|---|---|
| A changed file is missing, unknown or listed twice | The order must list every changed file |
| A split names an unknown change, leaves changes unplaced, or splits a file without a diff | The order must list every changed file, and place every change of a split file exactly once |
| Someone saved a newer version | Conflict: … saved version N |
| No write access | … doesn't have write access |
| Invalid input, such as an empty checklist item | The order is invalid |
| A diagram node points at a file or change not in the pull request | The diagram points at files or changes that aren't in the pull request |
| Invalid diagram, such as an edge to an unknown node | The diagram is invalid |
| Someone saved a newer diagram | Conflict: … saved diagram version N |
| Pull request not visible | GitHub says this pull request doesn't exist or this account can't see it |
| GitHub token expired or revoked | GitHub access for this connection has expired |
| GitHub rate limit | GitHub's rate limit was reached |

## Authorization

LogiKFlow follows the [MCP authorization specification](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization).

| Endpoint | Path |
|---|---|
| Protected resource metadata | `/.well-known/oauth-protected-resource/mcp` |
| Authorization server metadata | `/.well-known/oauth-authorization-server` |
| Authorization (consent page) | `/authorize` |
| Token | `/oauth/token` |
| Dynamic client registration | `/oauth/register` |

Client ID metadata documents are also accepted. Unauthenticated requests to `/mcp` get `401` with a `WWW-Authenticate` challenge.

- **Access tokens** last up to one hour and are refreshed automatically.
- **Refresh tokens** last 30 days from last use and at most 180 days.
- **Rate limit:** 120 MCP requests per minute per person.

---

<!-- https://logikflow.dev/docs/security.md -->

# Security and privacy

LogiKFlow is built to see no more than you can, and to store as little as possible.

## Access

- **Your permissions, not the app's.** Every request to GitHub uses your own token. You see only repositories and pull requests your account can see.
- **Writing an order requires write access.** LogiKFlow asks GitHub for your permission on the repository before every save.
- **Private repositories need the app installed.** The owning account or organization decides which repositories the LogiKFlow GitHub App can reach, and can remove it at any time.

## What the GitHub App can do

| Permission | Why |
|---|---|
| Contents: read | Show diffs of changed files |
| Pull requests: read and write | Read pull requests; write only to post the review link as a comment when you choose **Post to PR** |
| Metadata: read | Required by GitHub for every app |

LogiKFlow never pushes code, changes branches or approves pull requests.

## What's stored

| Data | Purpose |
|---|---|
| Your GitHub user ID, login and avatar URL | Show who saved an order or ticked an item |
| Sessions: a hash of the session token and your GitHub tokens, encrypted | Keep you signed in |
| Reading orders: file paths, section titles, notes, checklist text, and each version | The feature itself |
| Flow diagrams: box titles, short descriptions, labelled arrows and the file paths they link to, and each version | The Diagram tab |
| Viewed files and checklist ticks | Your review progress |
| Recently opened pull requests (repo, number, title) | Your dashboard |

LogiKFlow doesn't store source code or diffs. They're fetched from GitHub when you open a pull request.

## How it's protected

- GitHub tokens are encrypted with AES-256-GCM before they're stored. Session cookies hold a random token, and only its SHA-256 hash is stored.
- Cookies are `__Host-` prefixed, HttpOnly, Secure and SameSite=Lax.
- Every change must come from the LogiKFlow site itself and be sent as JSON, which blocks cross-site request forgery.
- A strict Content Security Policy, HSTS and `nosniff` are sent on every page.
- Agent connections use OAuth 2.1 with PKCE and a consent page that can't be framed or forged, and follow the MCP authorization specification.
- Requests are rate limited per person.

## Signing out and disconnecting

- **Sign out** on any page ends the session and deletes it.
- To disconnect an AI agent, remove the LogiKFlow server from the agent.
- To revoke LogiKFlow entirely, go to GitHub → Settings → Applications → Authorized GitHub Apps.

---

<!-- https://logikflow.dev/docs/faq.md -->

# FAQ

## Does LogiKFlow replace GitHub reviews?

No. Comments, approvals and merging stay on GitHub. LogiKFlow changes the order you read the files in and adds the author's context and checklists.

## Do reviewers need to do anything to see the order?

They open the LogiKFlow link and sign in with GitHub. There's nothing to install. For private repositories, the app must already be installed on the owning account or organization.

## Who can change the order?

Anyone with write access to the repository. Everyone who can read the repository can see it.

## What happens when I push new commits?

Files you placed keep their positions. New files appear at the end under **Not in the saved order**, and removed files disappear. A file you marked as viewed becomes unviewed if it changes. Ask your agent to re-arrange, or place the new files by hand.

## Does it work with GitHub Enterprise or GitLab?

Not yet. LogiKFlow works with github.com.

## Which AI agents work with it?

Any agent that supports remote MCP servers with OAuth, including Claude Code, Cursor, VS Code, Windsurf and others. See [Arrange with AI agents](/docs/agents).

## Does the agent send my code to LogiKFlow?

No. The agent sends only the reading order: file paths, section titles, notes and checklist items. Your code stays between your agent, your machine and GitHub.

## Is there a limit on pull request size?

GitHub returns at most 3,000 changed files for a pull request, and omits the diff for very large or binary files. LogiKFlow shows a warning when files are missing, and a link to GitHub for files without a diff.

## Is it free?

Yes. LogiKFlow is free during early access. Paid plans may come later, and they'll be announced before anything changes.

---

<!-- https://logikflow.dev/docs/support.md -->

# Help and support

Stuck, found a bug, or have an idea? We're happy to help.

## Contact us

Email **[support@logikflow.dev](mailto:support@logikflow.dev)**. Include the pull request link (`https://logikflow.dev/r/<owner>/<repo>/pull/<number>`) and what you expected to happen, and we'll usually reply within two working days.

- **Security issue:** email [security@logikflow.dev](mailto:security@logikflow.dev) instead. See [Security and disclosure](/legal/security).
- **Your data or account:** email [privacy@logikflow.dev](mailto:privacy@logikflow.dev), or export or delete your account yourself from the [dashboard](/app).
- **Legal questions:** [legal@logikflow.dev](mailto:legal@logikflow.dev).

## Quick fixes

| Problem | What to do |
|---|---|
| "Sign in to review" on a private repository | Install the GitHub App on the account or organization that owns the repository, from the button on that page. |
| The order is missing new files | Commits were pushed after it was saved. New files appear under **Not in the saved order**; choose **Arrange files** to place them. |
| The agent says GitHub access has expired | Reconnect the MCP server: in Claude Code, `/mcp`, then **Authenticate**. |
| The agent can't save the order | Only people with write access to the repository can save. See [agent troubleshooting](/docs/agents#troubleshooting). |
| The browser extension shows "Sign in to see the order" | Sign in to LogiKFlow in the same browser, then reload the GitHub page. |
| A very large file shows no diff | GitHub doesn't send diffs for very large or binary files. Use the GitHub link on that file. |

## Learn more

- [Quickstart](/docs/quickstart): sign in and arrange your first pull request.
- [Reviewing a pull request](/docs/reviewing) and [Arranging a pull request](/docs/arranging).
- [Arrange with AI agents](/docs/agents): connecting Claude Code, Cursor, VS Code and other MCP clients.
- [FAQ](/docs/faq).