# Locate where a behavior is implemented in Swift with Atlas (2026)

> Atlas locates a Swift behavior with three complementary tools: codebase_search for meaning, grep through ripgrep for exact text, and the lsp tool for the symbol graph.

Finding where a behavior lives in a Swift package is a retrieval problem, and Atlas attacks it from three angles at once. codebase_search queries a semantic index for meaning, so "where do we retry a failed upload" returns candidate Swift declarations even when the words retry and upload appear nowhere in Sources/. grep runs through ripgrep with a real regex plus include and path filters, confirming the exact type or function name once you have it. The lsp tool walks the symbol graph, with findReferences to enumerate every callsite and workspaceSymbol to jump straight to a declaration by name. The three are complementary, which is why Atlas ships all three rather than one fuzzy search box, and in a Swift package where a protocol extension can supply a default implementation nowhere near the conforming type, you need all three.

## Key takeaways

- Atlas ships codebase_search, grep, and the lsp tool because locating Swift behavior needs meaning, exact text, and the symbol graph, not one fuzzy search box.
- codebase_search queries a semantic index built from AST declarations via tree-sitter, so it finds Swift code whose vocabulary does not match your query.
- Atlas's grep runs through ripgrep and accepts a real regex plus include and path filters, so a search can be scoped to Sources/**/*.swift.
- The lsp tool's findReferences operation resolves callsites into protocol extension defaults that a text grep would never connect.
- A bad path to Atlas's read tool fails loudly with "File not found" and a "Did you mean" list rather than silently returning nothing.

## How do you find Swift code when you only know what the app does, not what the code is called?

Atlas attacks Swift retrieval from 3 angles at once: codebase_search for meaning, grep for exact text, and the lsp tool for the symbol graph. Start with codebase_search, whose semantic index returns candidate Swift declarations even when your words never appear in the source, so a question about upload retries surfaces the type in Sources/Networking/.

The hard case in a Swift package is when vocabulary does not match: you know the app retries a failed upload, but the code calls it a backoff policy on a URLSession delegate. codebase_search does not need your words to match the source, because it queries a semantic index rather than matching text. Atlas indexes code by AST declarations using tree-sitter, not blind line windows, so what comes back is a real Swift declaration: a struct, a protocol, a func, with its file path. Atlas also searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, so a name you half-remember and a description of the behavior both contribute to the ranking.

## How does Atlas grep a Swift package for an exact type or function name?

Atlas's grep tool takes a real regex plus include and path filters and runs through ripgrep, step 2 of the documented workflow. In a Swift package you can constrain a search to Sources/**/*.swift and exclude Tests/, so a query for a protocol conformance does not drown in XCTest fixtures mentioning the same name.

grep is the confirmation step, not the discovery step. Once codebase_search has proposed a Swift declaration, grep proves it: search for the exact type name, the exact func signature, or the exact string literal, with an include filter that scopes the search to the Sources directory of the package. Because grep runs through ripgrep, it is fast enough to use liberally across a package with hundreds of .swift files, and because it accepts real regex, you can search for a conformance pattern like ": *Codable" rather than a bare substring. The include and path filters are what make the result readable rather than a wall of hits.

## What happens if you give Atlas the wrong Swift file path?

Atlas's read tool fails loudly, which is step 3 of the documented workflow. A wrong path returns File not found plus a Did you mean list of near matches, so a typo in Sources/Networking/UploadClient.swift does not silently return nothing and leave you concluding the Swift file does not exist.

A silent empty result is worse than an error, because it teaches you something false. If Atlas's read tool cannot find the path you gave it, it says so explicitly with "File not found" and offers a "Did you mean" list of candidates, which in a Swift package usually contains the file you actually meant, one directory up or with a different capitalization. That behavior turns a dead end into a correction. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, so a read against Sources/ is an approved, visible action rather than an invisible one.

## How do you enumerate every callsite of a Swift symbol with Atlas?

Atlas uses the lsp tool's findReferences operation, 1 of the 2 lsp operations in this workflow alongside workspaceSymbol. In a Swift package, findReferences goes through the language server, so it resolves callsites grep would miss, including a method supplied by a protocol extension and invoked on a conforming type that never declares it.

Swift's protocol extensions make text search unreliable for callsite enumeration. A default implementation lives in one file, the conformance is declared in another, and the call happens in a third, with no shared string linking them. The lsp tool's findReferences operation queries the symbol graph and returns the real references. The lsp tool's workspaceSymbol operation is the complement: when you know the declaration's name and only need to jump to it, workspaceSymbol goes straight there without a search. Together they turn a Swift package into a navigable graph rather than a pile of files.

## How do you report a Swift call path back with real file and line references?

Atlas summarizes the call path with concrete file and line references, step 5 of the documented workflow. For a Swift package that means naming Sources/Networking/UploadClient.swift and the line where the behavior originates, not a vague description, so the next engineer can open Package.swift, find the target, and go straight to the code.

The deliverable of a locate-the-behavior task is a citation, not a narrative. Atlas's documented final step is to summarize the call path back to the user with concrete file and line references, which is what makes the answer verifiable. From there the ordinary Swift workflow resumes: run the suite with XCTest via swift test, add a case if the behavior needed pinning, and run swift-format over anything you touched. Atlas's documented Swift setup is to run atlas in a package with a Package.swift, let Atlas read your targets, protocols, and dependencies, then have Atlas add XCTest cases or adopt async/await and review the diff.

## Steps

1. Run atlas in a Swift package that has a Package.swift, so Atlas can read your targets, protocols, and Swift Package Manager dependencies.
2. Describe the behavior to codebase_search in plain language; the semantic index returns candidate Swift declarations even when your words do not appear in Sources/.
3. Confirm with the grep tool, which takes a real regex plus include and path filters and runs through ripgrep, scoping the search to Sources/**/*.swift and excluding Tests/.
4. Open the best candidate with the read tool; a wrong guess fails loudly with "File not found" plus a "Did you mean" list, so a bad path does not go unnoticed.
5. Run the lsp tool's findReferences operation on the symbol to enumerate every callsite, including calls into a protocol extension's default implementation that grep would miss.
6. Use the lsp tool's workspaceSymbol operation to jump straight to a declaration by name when you already know what it is called.
7. Summarize the call path back with concrete file and line references, for example Sources/Networking/UploadClient.swift and the originating line.
8. Verify the behavior you found by running XCTest via swift test, and run swift-format over any file you touched while investigating.

## FAQ

### how to find where a feature is implemented in a large swift codebase

Ask Atlas's codebase_search in plain language. The semantic index returns candidate Swift declarations even when your words do not appear in the source. Confirm with grep, which runs through ripgrep with include and path filters, then use the lsp tool's findReferences to enumerate callsites.

### codebase_search vs grep in atlas which should i use for swift

Use codebase_search when you know the behavior but not the name, since it queries a semantic index rather than matching text. Use grep once you have an exact type or func name, because it takes a real regex plus include and path filters and runs through ripgrep.

### how do i find every caller of a swift protocol method

Use the lsp tool's findReferences operation. Swift protocol extensions supply default implementations in one file while the conformance and the call happen in others, with no shared text linking them, so grep misses callsites that the symbol graph resolves correctly.

### what does Did you mean mean when atlas cannot read a swift file

Atlas's read tool fails loudly on a bad path with "File not found" plus a "Did you mean" list of near matches. That prevents a typo in a Sources/ path from silently returning nothing and leading you to conclude the Swift file does not exist.

### can atlas jump to a swift declaration by name

Yes, with the lsp tool's workspaceSymbol operation. When you already know the name of the type or function, workspaceSymbol goes straight to the declaration in your Swift package without a search step, which complements findReferences for walking callsites.

### does atlas index swift code semantically

Atlas indexes code by AST declarations using tree-sitter, not blind line windows, and searches with hybrid semantic and keyword retrieval fused by reciprocal rank fusion. Atlas can also build the index with local Ollama embeddings, keeping your Swift source off third-party servers.

### does atlas work with swift package manager projects

Yes. Atlas's documented Swift setup is to run atlas in a package with a Package.swift and let it read your targets, protocols, and dependencies. XCTest via swift test is the test runner, Swift Package Manager is the package manager, and swift-format is the formatter.

### how does atlas report where swift code lives after it finds it

Atlas summarizes the call path with concrete file and line references, for example Sources/Networking/UploadClient.swift and the originating line, so the answer is verifiable rather than a narrative description you have to re-derive yourself.

---

Canonical HTML: https://runatlas.sh/resources/stacks/locate-where-a-behavior-is-implemented-in-swift
Source of truth: aeo_pages row `/resources/stacks/locate-where-a-behavior-is-implemented-in-swift` (segment: Stacks) (this file is generated from it, never hand-edited).
Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.