How to make /understand run faster ?

[Antoliny0919]

Hello :)

I've been researching ways to quickly understand large codebases, and that's when I came across understand-anything. I've been getting a lot of value out of it!

That said, I did notice one thing that felt a bit lacking — the /understand command takes quite a long time on the first run, and the token consumption seems fairly high as well.

In my experience, the biggest strength of understand-anything is that after running /understand, the subsequent commands like /understand-chat and /understand-explain return much richer and more useful results compared to using plain Claude Code.

I haven't used it extensively yet, but you seem to be an expert in this area, so I'd love to ask a couple of questions:

1. Is there any way to improve the speed of /understand? (If you have any tips on reducing token consumption as well, I'd really appreciate it!)
2. Besides understand-anything, are there any other good tools you'd recommend for understanding a codebase?

I considered reaching out via email, but I decided to open this as an Issue in case others are facing the same challenges.

Thank you so much for building and maintaining understand-anything!

[Lum1104]

Hi @Antoliny0919, thanks so much for the kind words and for opening this issue! Really glad you're getting value out of understand-anything 😊

Great questions! On performance — in the latest version, I've introduced batch merge scripts to replace the original approach where an agent had to read intermediate outputs and merge them one by one. This has already reduced both runtime and token usage significantly. I'm continuing to explore ways to make it even faster without sacrificing too much accuracy — it's a tricky balance but definitely a priority.

Happy to discuss any ideas or approaches you have in mind — and PRs are always welcome!

[deka]

Wouldn't it be interesting to be able to exclude files? Currently how/understand chosen the folders to index?

[Lum1104]

Current file selection logic is defined in understand-anything-plugin/agents/project-scanner.md. The scanner:

1. Uses git ls-files for git repos (falls back to recursive listing otherwise)
2. Applies hardcoded exclusion filters:
   • Dependency dirs: node_modules/, .git/, vendor/, venv/, __pycache__/
   • Build output: dist/, build/, out/, coverage/, .next/, .cache/, .turbo/, target/
   • Lock files: *.lock, package-lock.json, yarn.lock, pnpm-lock.yaml
   • Binary/assets: images, fonts, videos, PDFs, archives
   • Generated files: *.min.js, *.min.css, *.map, *.generated.*
   • IDE config: .idea/, .vscode/
   • Misc: LICENSE, .gitignore, .editorconfig, .prettierrc, *.log
3. Keeps everything else — code, docs, configs, infra, CI/CD, schemas, scripts, etc.

Additionally, you can scope analysis to a subdirectory by passing a path: /understand path/to/subdir.

What don't have yet is user-configurable include/exclude. And I was thinking that if we can make these:

• Respect .gitignore — since we already use git ls-files, tracked files already respect .gitignore. But for non-git projects this could help.
• Support a .understandignore — a project-level file (similar to .gitignore syntax) where users can specify additional patterns to exclude from analysis.
• Support a .understandinclude — to force-include files that would otherwise be filtered out by the default rules.
• Add a args to exclude folder/types — in the /understand command allow some args to pass

Thanks for the advice, it is awesome!

[deka]

Build output: You can add bin/ and obj/ for .Net projects.

.understandignore -> Useful for my use case

[jimweller]

@Lum1104 .understandanythingignore resonates with me. That's how repomix and some other tools do it.

I made a similar pipeline for code reviews of HUGE code bases (~20k files, 4.5M LOC). I'm using a similar approach with ASG's, but using off the shelf tools and multi-vendor-model quorum. Slightly different use case, and very similar approach. I've toyed with using a graph/vector DB like you are. RN just sqlite.

LMK if you wanna chat somewhere.

I'm running UA on said code base as we speak. #holdmybeer

[Lum1104]

@jimweller Sure! I am based in Beijing time, happy to chat with you~ We can have a quick zoom chat if this work for you~

[newbielearnlinux]

That said, I did notice one thing that felt a bit lacking — the /understand command takes quite a long time on the first run, and the token consumption seems fairly high as well.

I would also add that there is like 30+ times approval for "containing a shell expansion" (or "JSON"), which makes the first run really loonnngggg.

The .understandanythingignore helps a bit, but overall the token usage and the time for first run is just too much for me.

[Lum1104]

For the approval issue, you can turn the auto accept on. And I am still trying a way on the token usage reduce~

[rorar]

How about using a "code parser" like Knip for a first overview and build upon that?
And maybe Grit is something worthy to discover: https://docs.grit.io/

There's also Claude Context https://github.com/zilliztech/claude-context as reference. (Can be used with other Coding Agents too)

[Lum1104]

How about using a "code parser" like Knip for a first overview and build upon that? And maybe Grit is something worthy to discover: https://docs.grit.io/

There's also Claude Context https://github.com/zilliztech/claude-context as reference. (Can be used with other Coding Agents too)

Hi, in case I did not misunderstand your point:

Current Understand Anything is using:

Tree-sitter:
Parse repo → extract symbols/imports/functions/classes → build knowledge graph

and we can add Knip to

Knip:
Analyze JS/TS repo → detect unused files/deps/exports → attach as cleanup/maintenance insights

Then finally clean up unuse codebase, to make the running faster

[AsimRaza10]

Hey @Lum1104, thanks for laying out the four subtasks. Quick status pass before I pick one up — I read through packages/core/src/ignore-filter.ts and ignore-generator.ts to avoid duplicating shipped work:

1. Respect .gitignore — partial. ignore-generator.ts reads .gitignore when scaffolding a starter .understandignore, but the runtime filter (createIgnoreFilter in ignore-filter.ts) doesn't read .gitignore directly. For git repos this is fine because git ls-files already filters. For non-git projects — the case you flagged — .gitignore is silently ignored at scan time.
2. .understandignore — already shipped (defaults + project-root + .understand-anything/.understandignore, with !-negation).
3. .understandinclude — I'd actually argue against building this. !-negation in .understandignore already re-includes files dropped by defaults, so a separate include file would be a second way to do the same thing. Happy to be wrong if you have a use case in mind that negation can't cover.
4. CLI args on /understand — not built. The skill parses --full, --auto-update, --no-auto-update, --review, --language <lang>, and a positional path, but no exclude/include flags.

Side note: bin/ is missing from DEFAULT_IGNORE_PATTERNS even though obj/ is there and the comment on line 7 mentions .NET. Tiny fix, can fold it into whichever PR you want or do it separately.

If you're open to it, I'd like to take subtask #1 — .gitignore runtime fallback for non-git projects. Proposed scope:

• In createIgnoreFilter, when the project root is not a git repo (no .git/ directory), also load .gitignore patterns into the merged ignore layer.
• Keep the precedence consistent with the existing layered model: defaults → .gitignore (non-git only) → .understand-anything/.understandignore → root .understandignore. Later layers override earlier ones, so user files always win.
• For git repos, behavior is unchanged — git ls-files continues to handle it.
• Add tests in __tests__/ignore-filter.test.ts covering: (a) non-git project picks up .gitignore, (b) git project ignores .gitignore at this layer to avoid double-filtering, (c) user .understandignore still overrides via !-negation.

Two scoping questions before I open the PR:

1. Should the non-git detection be "no .git/ directory" or should we read a flag (e.g., an option passed by the scanner when it falls back from git ls-files to recursive walk)? The second is more robust against detached worktrees and submodules but adds API surface.
2. Should nested .gitignore files (subdirectories) be respected, or only the project-root one? Real .gitignore semantics support nested files, but the existing ignore library handles them differently than root-only.

Happy to follow whichever direction you prefer.