## Feature request: simple bootstrap script for new projects

[hawaka6667-dev]

Hi, I was setting up CodeGraph for multiple projects and noticed that the first-time workflow still needs a few manual steps.

Currently the flow is something like:

codegraph install
cd my-project
codegraph init

This works fine, but for people using AI coding agents it is easy to miss the init step or forget whether a project already has an index.

I made a small Windows .bat script for my own workflow:

@echo off
chcp 65001 >nul
cd /d "%~dp0"

echo CodeGraph initialization

where codegraph >nul 2>nul
if errorlevel 1 (
    echo CodeGraph not found
    pause
    exit /b 1
)

codegraph --version

if exist ".codegraph" (
    echo Existing index found
    set /p REBUILD="Rebuild? (y/N): "

    if /i not "%REBUILD%"=="y" (
        exit /b 0
    )
)

codegraph init

echo Done

Nothing complicated, it just:

• checks that CodeGraph exists
• initializes the current project
• avoids accidentally rebuilding existing indexes

I wonder if something similar would be useful as an official example/template.

Maybe something like:

codegraph init --bootstrap

or an examples/ script folder.

Especially with AI agents, the problem is not only installing the tool, but making sure the project is prepared correctly before the agent starts working.

Not sure if this belongs in the main project or just documentation, but wanted to share the idea.

[sunerpy]

Reopening this. I closed it too quickly: codegraph install --yes --init only covers the first project. The problem you describe, an agent starting work in a project nobody initialized, is still there for every project after that.

What's planned:

• By default CodeGraph still won't create an index on its own. When a project has no index, CodeGraph will tell the agent to let you know and offer to run codegraph init, so a missing index doesn't go unnoticed.
• Optional automatic initialization that you turn on explicitly. It will only run at a git repository root and will refuse $HOME and /.

Doing this inside CodeGraph rather than in a script also covers what a .codegraph directory check misses: a CODEGRAPH_DIR override, the .codegraph-wsl root that WSL creates for projects on Windows drives, and whether the index is actually current.

Until then, run codegraph init in each new project (codegraph install --yes --init does the install and the init in one go). It's idempotent: on a readable current index it prints Already initialized and doesn't rebuild. codegraph status . --json shows the current state, and codegraph index . forces a full rebuild.

[hawaka6667-dev]

I also noticed another maintenance issue that seems related to keeping the index current.

When a project has a large number of file renames or moves, the index can become stale enough that I usually need to manually run codegraph index . --force to recover it.

Would it be possible for CodeGraph to detect this kind of situation and automatically trigger, or at least recommend, a full reindex?

For example, it could detect an unusually large number of renames/deletions between the current index state and the Git working tree, and report something like:

The project structure changed significantly. A full reindex may be required. Run codegraph index . --force.

This would be particularly useful for AI coding agents, since large refactors and file reorganizations are common and the agent may otherwise continue working against a stale graph.

I think this could fit nicely with the index-currentness check you mentioned above.

[sunerpy]

The MCP server already keeps an existing index current. When an indexed project is loaded, it attaches to that project's background daemon, which watches the files and re-indexes changes a couple of seconds after they settle. Renaming or moving a directory triggers a full rescan, and when the server starts again it first catches up on anything that changed while it wasn't running. It never creates an index, which is the gap the plan above covers.

Large renames shouldn't need a full rebuild, though. codegraph status . --json already lists the added, modified and removed paths the index hasn't caught up with, and codegraph sync . reconciles the whole project against the index; --force no longer changes what codegraph index does. If the index goes stale while the server is running, the watcher most likely missed events: when a burst of changes overflows the operating system's event queue, the dropped events don't currently trigger a full rescan. Rather than warn based on how much changed, we plan to fix that directly: a large burst of changes, or any sign that events were dropped, will make the watcher run a full rescan on its own.

To confirm it's the same problem, could you share:

• codegraph --version and your OS (native Windows, or WSL with the project under /mnt/, where file watching is off by default?)
• how the renames happened (IDE refactor, git mv, a branch switch, ...) and whether the agent's MCP server was running at the time
• the output of codegraph status . --json while the index looks stale, before you run anything to fix it

The next release will also update the MCP tool descriptions and the skill.