Atlas locates where a behavior is implemented in Kotlin by attacking the problem from three angles at once: codebase_search for meaning, grep for exact text, and the lsp tool for the symbol graph. You describe the behavior in plain language, the semantic index returns candidate declarations even when your words do not appear in the source, grep confirms with a real regex through ripgrep, and the lsp tool's findReferences and workspaceSymbol operations give you the callsites and the declaration. The three are complementary, which is why Atlas ships all three rather than one fuzzy search box.
How do I find the Kotlin class responsible for a behavior I cannot name?
Atlas takes a plain-language description of the behavior and hands it to codebase_search, the first of 3 retrieval angles, which returns ranked candidate declarations even when your words never appear in the Kotlin source. Asking where a session token gets refreshed finds the suspend fun that does it.
Naming is the whole problem. A Kotlin codebase built over four years calls the same concept three things, and the class you want is TokenRotationCoordinator in src/main/kotlin/auth/, which nobody would guess. Atlas searches with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, so the description finds the declaration by meaning. Atlas also indexes Kotlin code by AST declarations using tree-sitter, not blind line windows, so the hit you get back is a whole class or suspend fun rather than a fragment cut through the middle of a coroutine builder.
Why does Atlas confirm with grep after codebase_search finds a Kotlin candidate?
Atlas confirms a codebase_search hit with grep, which takes a real regex plus include and path filters and runs through ripgrep. Semantic search ranks candidates; grep proves a specific string exists in src/main/kotlin. The 2 tools answer different questions, and a Kotlin investigation needs both answered.
Semantic retrieval returns the most plausible declarations, which is exactly right for discovery and exactly wrong for proof. If you need to know that a particular error message, a particular Gradle task name, or a particular annotation appears in the module, grep is the tool that can tell you it does or does not. Scoping the search with an include filter to Kotlin sources, or a path filter to one Gradle module, keeps the result set small enough to read. Atlas uses grep as verification, not as discovery.
What does File not found plus Did you mean mean in Atlas?
File not found plus a Did you mean list is the Atlas read tool failing loudly on a wrong path at step 3 of the workflow. A guess at src/main/kotlin/auth/TokenService.kt that does not exist returns the error and nearby candidates, so a bad path does not get quietly reasoned around.
Silent failure on a missing file is one of the more insidious agent bugs, because the model then reasons from an absence and produces a confident answer about code it never saw. Atlas refuses to do that. The Did you mean list is also actively useful in a Kotlin project, where the real path is frequently one Gradle module over, under a different source set, or named TokenRotationCoordinator.kt rather than what you typed. The failure is the fastest way to the right file.
How do you see every Kotlin callsite of a symbol once you have found it?
Atlas uses the lsp tool's findReferences operation to see every callsite of a Kotlin symbol, and workspaceSymbol to jump straight to the declaration by name. findReferences returns the authoritative reference set from the Kotlin language server, so a suspend fun called from 7 coroutine scopes shows all 7.
Locating the declaration is only half of understanding a behavior. The other half is who invokes it, under what conditions, from which Gradle module. findReferences answers that from the symbol graph rather than from a text match, so an overload on an unrelated class does not pollute the list. workspaceSymbol is the shortcut for the case where you already know the name: type it, jump to it, skip the search entirely. Together with codebase_search and grep, that is the three-angle attack.
How does Atlas summarize a Kotlin call path back to the developer?
Atlas summarizes the call path with concrete file and line references, so the answer to where a Kotlin behavior is implemented is a set of paths under src/main/kotlin, not hedged prose. Each of the 3 hops, entry point, intermediate suspend fun, and the class doing the work, carries a path you can open.
A summary without file and line references is not an answer, it is a hypothesis. Atlas gives you the entry point, the intermediate suspend fun, and the class that actually performs the work, each with its path. From there you can open the file, run the relevant JUnit 5 via gradle test target to see the behavior exercised, and make a change with confidence. Atlas is a terminal-native TUI, so that summary lands in the terminal where the Gradle build already runs.
Can Atlas explore a Kotlin codebase without changing anything?
Atlas drafts a plan in a read-only plan agent and asks before switching to a build agent, and every tool call is permission-gated against 3 rule types, allow, ask, and deny, before it runs. Locating a behavior across a Gradle multi-module Kotlin project touches nothing on disk.
That separation matters when the task is investigation. codebase_search, grep, read, and the lsp tool are all read-only, and the permission system enforces the boundary rather than trusting the model to respect it. When you do decide to change the Kotlin code you found, ktlint keeps the formatting consistent and JUnit 5 via gradle test proves the behavior still holds. Atlas computes a unified diff for every file edit and surfaces it for approval before writing.
Step by step
- 01Run atlas in a project with a build.gradle.kts and let Atlas read your modules, coroutines, and Gradle configuration.
- 02Describe the behavior to codebase_search; the semantic index returns candidate Kotlin declarations even when your words do not appear in the source.
- 03Confirm with grep, which takes a real regex plus include and path filters and runs through ripgrep, scoped to src/main/kotlin or a single Gradle module.
- 04Open the best candidate with read; a wrong guess fails loudly with File not found plus a Did you mean list, so bad paths do not go unnoticed.
- 05Use the lsp tool's findReferences operation to see every Kotlin callsite, and workspaceSymbol to jump to the declaration by name.
- 06Summarize the call path with concrete file and line references under src/main/kotlin rather than a prose description.
- 07Exercise the behavior by running the relevant JUnit 5 via gradle test target through the bash tool.
- 08If you then change the Kotlin code, run ktlint over the touched files and review the unified diff Atlas surfaces before it writes.
Frequently asked questions
- how to find where a feature is implemented in a large Kotlin codebase
- Describe the behavior to codebase_search. Atlas queries the semantic index and returns ranked Kotlin declarations even when your words do not appear in the source, then confirms with grep and enumerates callsites with the lsp tool's findReferences operation.
- does semantic code search work when I do not know the Kotlin class name
- Yes. That is the case it exists for. Atlas searches with hybrid semantic and keyword retrieval fused by reciprocal rank fusion and indexes code by AST declarations using tree-sitter, so a plain-language description returns the whole suspend fun or class.
- why does Atlas use both grep and semantic search
- They answer different questions. codebase_search ranks candidates by meaning, which is right for discovery. grep, running through ripgrep with real regex plus include and path filters, proves an exact string exists in a Gradle module, which is right for verification.
- what does File not found Did you mean mean in Atlas
- The read tool was given a path that does not exist and failed loudly, listing nearby candidates instead of silently returning nothing. In a Gradle multi-module Kotlin project the real file is often one module over, and the Did you mean list gets you there.
- how do I see every caller of a Kotlin suspend fun
- Use the lsp tool's findReferences operation. It returns the authoritative reference set from the Kotlin language server, so an unrelated overload sharing the name does not pollute the list. workspaceSymbol jumps to the declaration when you already know the name.
- does Atlas work with Gradle and ktlint
- Yes. Start atlas in a project with a build.gradle.kts and it reads your modules, coroutines, and Gradle configuration. It runs JUnit 5 via gradle test and ktlint through the bash tool, and can convert callbacks to coroutines with the diff shown first.
- can Atlas explore my Kotlin repo without editing anything
- Yes. Atlas drafts a plan in a read-only plan agent and asks before switching to a build agent, and every tool call is permission-gated against allow, ask, and deny rules. codebase_search, grep, read, and the lsp tool are all read-only.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Locate Where a Behavior Is Implemented with Atlas in 2026
How to locate where a behavior is implemented with Atlas in 2026: codebase_search for meaning, grep for exact text, and the lsp tool for the symbol graph.
Atlas for Kotlin in 2026
In 2026, Atlas empowers Kotlin developers with terminal-native AI coding. It integrates with Gradle and coroutines, offering secure, privacy-focused code assistance with local embeddings and granular control.
Refactor a Legacy Module in Kotlin with Atlas (2026)
Refactor a legacy Kotlin module in 2026 with Atlas: findReferences enumerates every callsite, apply_patch anchors on context, and JUnit 5 via gradle test pins behavior.
Research a Third-Party API Before Integrating It in Kotlin With Atlas (2026)
How to research a third-party API before integrating it in Kotlin with Atlas in 2026: websearch finds the docs, webfetch pulls them, and every request is permissioned.
Plan a multi-file change before editing in Kotlin with Atlas (2026)
Plan a multi-file Kotlin change in 2026 before editing: Atlas's plan agent denies edit for every path except .atlas/plans/*.md, so build.gradle.kts stays untouched.
Rename a Symbol Across the Repo in Kotlin with Atlas (2026 Guide)
Rename a Kotlin class or function across every Gradle module with Atlas: lsp findReferences, grep, edit replaceAll, then JUnit 5 via gradle test and ktlint.
Migrate a Deprecated API Across Every Callsite in Kotlin with Atlas in 2026
Effortlessly migrate deprecated Kotlin APIs across your entire codebase in 2026 using Atlas. Leverage Gradle, JUnit 5, and ktlint for a verified, complete transition.
Extract a Shared Helper from Duplicated Kotlin Code with Atlas in 2026
Streamline your Kotlin codebase in 2026 by extracting duplicated logic into a single, tested helper using Atlas. Leverage Gradle, JUnit 5, and ktlint for robust refactoring.