FSIBLOG

Claude GitHub Sync Failing and Stuck in Retrieval Mode: What Each One Means and How to Get Your Repo Back

Daniyal Ahmed

Claude GitHub Sync Failed and Stuck in Retrieval Mode Fix

Your Claude Project says GitHub is connected, yet you keep seeing “failed to sync with GitHub,” and the repo no longer fills project knowledge the way it used to. These are two different problems. This guide shows how to tell them apart and fix each one, step by step.

This guide is built on a question a Claude user posted:

Two Separate Problems Hiding in One Complaint

Before you change anything, split the problem in two:

“Failed to sync with GitHub” or “Syncing knowledge…” that never ends:

Project shows retrieval mode, files are not “in” the knowledge:

Problem A: the sync itself Claude cannot pull fresh files from GitHub. This is a connection fault, mostly on Anthropic’s side.

Problem B: the project size Not a fault. The project has grown too big to load at once, so Claude searches it instead.

Problem B is a size issue you can fix today. Problem A may need a workaround while Anthropic fixes it. The steps below handle both, in the order that wastes the least time.

What “Retrieval Mode” Really Means in a Claude Project

So “retrieve” is not a button that pulls the repo back in. Retrieval mode means the repo is too big to load whole. Pressing retrieve again cannot change that, but trimming the repo can.

Why “Failed to Sync With GitHub” Shows Up While the Repo Still Says Connected

Step 1

Check How Much of the Project Your Repo Is Using

  1. Open your Project on claude.ai.
  2. Look at the project knowledge panel on the right.
  3. Note the capacity figure and whether the project is marked as using retrieval.
  4. Click the GitHub repo entry to see which folders and files are selected.
Step 2

Trim the Repo Down to the Files Claude Needs

  1. In the project knowledge panel, open the repo and choose Configure files.
  2. Untick folders Claude never needs to read:
    • node_modules, vendor, venv
    • dist, build, .next, coverage
    • images, fonts, videos and PDFs
    • lock files such as package-lock.json, yarn.lock, poetry.lock
    • test fixtures and large data files
  3. Keep the source folders you ask about, plus the README and main config files.
  4. Save, then press Sync.
  5. Check the capacity figure again. Once it drops below the limit, the project goes back to full load on its own.
Lock files alone can be tens of thousands of lines. They are often the single biggest reason a small app pushes a project into retrieval mode.
Step 3

Reset the GitHub Connection the Way That Has Worked for Others

Plain disconnect and reconnect rarely helps. These are the versions users reported success with:

  1. Remove the repo from the project first. A project stuck on “Syncing knowledge…” often starts accepting messages again once the repo is removed.
  2. On GitHub, open github.com/settings/applications, find Claude and revoke it.
  3. Open a private or incognito browser window and sign in to claude.ai.
  4. In the project, add the repo again from + → GitHub and approve the GitHub screen when it opens.
  5. On GitHub, go back to Settings → Applications → Claude and check that your account and any organization show access granted. Press Grant if it is offered.
  6. Select only the trimmed set of files from Step 2, then sync.
Results have been mixed. One user needed many tries before the incognito method worked, and another found the Grant fix stopped working later. If two attempts fail, move to Step 4 or Step 5 instead of looping.
Step 4

Try the Repo in a Fresh Project

  1. Create a new Project.
  2. Copy your project instructions across from the old one.
  3. Add the GitHub repo there, with the trimmed file selection.
  4. Ask a test question that names one file, for example: “What does src/api/client.ts export?”
Step 5

Pack Your Repo Into Text Files and Upload Them Yourself

Users on the issue tracker confirm that manually uploaded files keep working when GitHub sync does not. This step turns your repo into a few Markdown files you can drag into project knowledge. It does not depend on the GitHub connector at all.

What You Need

The Script

Save this as pack_repo.py:

import os
import sys

# Folders and file types Claude does not need
SKIP_DIRS = {".git", "node_modules", "dist", "build", ".next", "venv", ".venv",
             "__pycache__", "vendor", "coverage", ".idea", ".vscode"}
SKIP_EXT = {".png", ".jpg", ".jpeg", ".gif", ".webp", ".ico", ".svg", ".pdf",
            ".zip", ".gz", ".mp4", ".mp3", ".woff", ".woff2", ".ttf", ".lock",
            ".exe", ".dll", ".so", ".pyc", ".map"}
MAX_FILE_KB = 200          # skip any single file bigger than this
TOKEN_BUDGET = 60000       # rough size for each output file

def main():
    repo = sys.argv[1] if len(sys.argv) > 1 else "."
    name = os.path.basename(os.path.abspath(repo))
    parts, current, used, total = [], [], 0, 0

    for root, dirs, files in os.walk(repo):
        dirs[:] = sorted(d for d in dirs if d not in SKIP_DIRS)
        for f in sorted(files):
            path = os.path.join(root, f)
            rel = os.path.relpath(path, repo).replace("\\", "/")
            if os.path.splitext(f)[1].lower() in SKIP_EXT:
                continue
            if os.path.getsize(path) > MAX_FILE_KB * 1024:
                continue
            try:
                with open(path, encoding="utf-8") as fh:
                    text = fh.read()
            except (UnicodeDecodeError, OSError):
                continue
            block = f"\n## File: {rel}\n\n```\n{text}\n```\n"
            tokens = len(block) // 4          # about 4 characters per token
            if current and used + tokens > TOKEN_BUDGET:
                parts.append(current)
                current, used = [], 0
            current.append(block)
            used += tokens
            total += tokens

    if current:
        parts.append(current)

    for i, blocks in enumerate(parts, 1):
        out = f"{name}-part{i}.md"
        with open(out, "w", encoding="utf-8") as fh:
            fh.write(f"# {name} (part {i} of {len(parts)})\n")
            fh.writelines(blocks)
        print(f"Wrote {out}")

    print(f"About {total:,} tokens in {len(parts)} file(s)")

if __name__ == "__main__":
    main()

Run It

  1. Open a terminal (PowerShell on Windows, Terminal on Mac).
  2. Go to the folder where you saved the script.
  3. Run it with the path to your repo:
python pack_repo.py C:\Users\you\projects\my-app
  1. You will see something like:
Wrote my-app-part1.md
Wrote my-app-part2.md
About 104,350 tokens in 2 file(s)
  1. In your Claude Project, click + in project knowledge and upload the .md files.
  2. When the code changes, run the script again, delete the old parts from the project, and upload the new ones.

Change What Gets Packed

If You Use Node.js Instead

The open-source tool Repomix does the same job with one command, run from inside your repo folder:

TerminalCopy

npx repomix --style markdown --ignore "**/*.lock,**/dist/**,**/node_modules/**"

It writes a single file named repomix-output.md that you upload the same way.

Before uploading, check the files for secrets. Open the output and search for .env, API_KEY, password and token. Delete anything private before it goes into the project.

How to Ask Questions So Retrieval Finds the Right File

If your project stays in retrieval mode, the way you ask makes a big difference. Anthropic’s own tips for RAG projects, applied to code:

When to Report It to Anthropic Instead of Trying Again

Exit mobile version