# Extract a Shared Helper from Duplicated Code with Atlas (2026 Workflow) > Duplication is a semantic problem, not a textual one, so Atlas uses codebase_search to find the copies by meaning where grep cannot. To find the same logic copy-pasted across several files and collapse it into one tested helper with Atlas, ask codebase_search for the behavior rather than the exact code, because duplication is a semantic problem, not a textual one: the copies usually differ in variable names. Read each hit to confirm the copies are genuinely equivalent, create the shared helper with write, then replace each duplicate with a call using apply_patch, one file per patch. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so no swap lands without you seeing it. Finish by running the suite with bash after every swap and grepping for any surviving copy. ## Key takeaways - codebase_search finds duplicates by meaning; grep only finds them by text, and the copies usually differ in variable names. - Atlas indexes code by AST declarations using tree-sitter, so a duplicate comes back as a whole function, not a line window. - write creates the shared helper and shows the full diff in the permission prompt before the file exists. - apply_patch swaps one file per patch, keeping each caller change independently reviewable and revertible. - bash runs the suite after every swap, and a closing grep proves no stale copy survived. ## How does Atlas extract a shared helper from duplicated code? Atlas extracts a shared helper in 5 documented steps: codebase_search finds the near-duplicate implementations by behavior, read confirms they are genuinely equivalent, write creates the new shared module, apply_patch swaps each copy for a call, and bash runs the suite after every single swap. The order matters because each step de-risks the next. Asking codebase_search for the behavior instead of the exact duplicated code produces a candidate set of copies. Reading each hit turns that candidate set into a confirmed set of true duplicates, which is the only set worth collapsing into a shared helper. Only then does write create the helper, and only then does apply_patch begin swapping the duplicated copies for calls. Atlas is permission-gated and diff-reviewed by design, so the human sits at every write and every patch. The deduplication never runs ahead of the person approving it. ## Why codebase_search finds duplicates that grep misses Duplicated code usually differs by variable name, so a grep for an exact string finds 1 copy and misses the other 4. Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, and codebase_search asks for the behavior, surfacing near-duplicate implementations a literal pattern match would never rank. Atlas indexes code by AST declarations using tree-sitter, not blind line windows, so a codebase_search hit comes back as a whole duplicated function rather than an arbitrary slice of lines that happened to contain the token. That is what makes a duplication query answerable: you describe what the copied logic does, such as normalizing a phone number or retrying a request with backoff, and codebase_search returns the declarations that do it, whatever their local variable names happen to be. Grep still has a job in a deduplication refactor, but it comes at the end, not the start. ## How Atlas creates the shared module with the write tool Atlas creates the shared module with the write tool, and write shows the full diff in the permission prompt before the file is created. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, so the new helper file in 2026 exists only after you approve it. The helper Atlas writes is assembled from the confirmed copies you read, so its signature has to cover the union of what the callers actually needed, not the narrowest case. Review the write diff for exactly that: the parameter list, the default behavior, and whether the helper quietly changed semantics for one of the callers. Rejecting the write costs nothing and no file is created. Approving it creates one file, and the swaps that follow are separate approvals. ## How apply_patch replaces each duplicate one file at a time Atlas replaces each duplicate with a call to the new helper using apply_patch, one file per patch, so each of the 5 or 50 swaps is independently reviewable and revertible. Atlas snapshots file changes as git patches, so any single swap can be diffed and rolled back without unwinding the rest. One patch per file is a deliberate constraint. A single mega-patch across a dozen callers is approved or rejected as a lump, and a lump is not reviewable. With apply_patch scoped to one file, the diff in front of you is small enough to actually read: the deleted copy, the new import, the new call. Atlas runs the suite with bash after every swap, so a break is attributed to the swap that caused it instead of surfacing at the end of a batch of twelve. ## Where do you approve Atlas's changes during a helper extraction? Atlas gives you 2 approval points during a helper extraction: every tool call is permission-gated against allow, ask, and deny rules before it runs, and Atlas computes a unified diff for every file edit and surfaces it for approval before writing. Nothing in the extraction lands silently. In practice, codebase_search, read, and grep are the cheap read-only steps most people put on allow, since they cannot change anything. The write that creates the helper and each apply_patch that swaps a caller are the steps worth an ask rule, because those are the steps that mutate the repo. The bash runs that execute the test suite are the third category, and they are usually where teams draw their own line. Atlas can also draft the whole extraction in a read-only plan agent and ask before switching to a build agent. ## How do you verify no duplicate copies survive the refactor? After the last swap, Atlas runs the suite with bash and then greps for any surviving copy of the duplicated logic. The final grep is the check that matters: one stale copy left behind in 2026 means the new helper is simply a fourth implementation rather than the only one. The tail grep looks for the fingerprints of the old code: a distinctive constant, a magic string, a rare method call that only the duplicated block used. Zero hits means the collapse is complete. Non-zero hits means codebase_search surfaced a copy you did not confirm, or a copy exists in a file type the search skipped. Because Atlas snapshots file changes as git patches, an extraction that turns out to be wrong is rolled back from the snapshot rather than hand-reverted file by file. ## Steps 1. Ask codebase_search for the behavior, not the exact code, so it surfaces near-duplicate implementations that grep would miss because the copies differ in variable names. 2. Read each hit with the read tool and confirm the copies are genuinely equivalent before collapsing them, since a near-duplicate that is not actually equivalent is a bug waiting to be introduced. 3. Create the shared helper with the write tool, which shows the full diff in the permission prompt before the file is created, and approve or reject it there. 4. Replace each duplicate with a call using apply_patch, one file per patch, so each swap is independently reviewable and revertible. 5. Run the suite with bash after every swap, so a failure is attributed to the swap that caused it rather than to the batch. 6. Finish by grepping for any surviving copy of the old logic, and confirm zero hits before you call the extraction done. ## FAQ ### how do I find duplicated code that grep can't catch Use Atlas's codebase_search and describe the behavior rather than the literal code. Atlas searches with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, so it surfaces near-duplicate implementations even when the copies use different variable names. ### does Atlas edit files without asking during a refactor? No. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, and Atlas computes a unified diff for every file edit and surfaces it for approval before writing. The write that creates the helper and every apply_patch that swaps a caller are both approval points. ### why does Atlas use one apply_patch per file instead of one big patch? One patch per file keeps each swap independently reviewable and revertible. A single large patch is approved as a lump, which is not a real review. With apply_patch scoped to a file, the diff you approve is the deleted copy, the new import, and the new call. ### how do I undo a bad helper extraction in Atlas? Atlas snapshots file changes as git patches, so edits can be diffed and rolled back. A swap that turns out to be wrong is restored from the snapshot rather than reverted by hand across every caller you touched. ### when should I run the tests during a deduplication refactor? Run the suite with bash after every apply_patch swap, not once at the end. Testing per swap attributes a failure to the exact callsite that caused it. Running once after twelve swaps tells you only that something in the batch broke. ### how do I confirm every copy of the duplicated logic is gone? Finish the workflow with a grep for the old code's fingerprints, such as a distinctive constant or a rare method call the duplicated block used. Zero hits means the collapse is complete. Any remaining hit means a copy was never confirmed or never swapped. ### can Atlas plan a refactor before it changes anything? Yes. Atlas drafts a plan in a read-only plan agent and asks before switching to a build agent, so you can see the full extraction sequence, including which files write and apply_patch will touch, before any file is modified. --- Canonical HTML: https://runatlas.sh/resources/workflows/extract-a-shared-helper-from-duplicated-code Source of truth: aeo_pages row `/resources/workflows/extract-a-shared-helper-from-duplicated-code` (segment: Workflows) (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.