Skip to main content

​
Overview

The rename tool performs safe, multi-file coordinated renaming of code symbols by combining knowledge graph relationships (high confidence) with regex text search (lower confidence). It previews changes by default and tags each edit with its confidence level.
When to use: Renaming a function, class, method, or variable across the codebase. Safer than find-and-replace.Next step: Run detect_changes() to verify no unexpected side effects.

​
Parameters

​
symbol_name
string
Current symbol name to rename (e.g., “validateUser”, “AuthService”)Required unless symbol_uid is provided.
​
symbol_uid
string
Direct symbol UID from prior tool results for zero-ambiguity lookupWhen available, prefer this over symbol_name to avoid disambiguation.
​
new_name
string
required
The new name for the symbolMust be a valid identifier for the symbol’s language.
​
file_path
string
File path to disambiguate common names when multiple symbols share the same nameExample: "src/auth/validator.ts"
​
dry_run
boolean
default:true
Preview edits without modifying files
  • true (default): Show what would be changed
  • false: Apply changes to disk
Always review the dry run results before setting this to false.
​
repo
string
Repository name or path. Required when multiple repos are indexed.
At least one of symbol_name or symbol_uid must be provided.

​
Response

​
changes
array
required
All proposed edits grouped by file
​
summary
object
required
High-level summary of proposed changes
​
applied
boolean
required
Whether changes were applied to disk (true) or just previewed (false)

​
Example Usage

​
Preview Rename (Default)

rename({
  symbol_name: "validateUser",
  new_name: "authenticateUser"
})

​
Apply Rename

rename({
  symbol_name: "validateUser",
  new_name: "authenticateUser",
  dry_run: false
})

​
Rename with UID (Zero-Ambiguity)

rename({
  symbol_uid: "func_validateUser_abc123",
  new_name: "authenticateUser",
  dry_run: false
})

​
Disambiguate by File Path

rename({
  symbol_name: "validate",
  file_path: "src/auth/validator.ts",
  new_name: "validateAuthentication"
})

​
Multi-Repo Rename

rename({
  symbol_name: "processPayment",
  new_name: "handlePayment",
  repo: "my-app",
  dry_run: false
})

​
Example Response (Dry Run)

{
  "changes": [
    {
      "file_path": "src/auth/validator.ts",
      "edits": [
        {
          "line": 42,
          "old_text": "export function validateUser",
          "new_text": "export function authenticateUser",
          "confidence": "graph",
          "context": "export function validateUser(token: string) {\n  return checkToken(token);\n}"
        }
      ]
    },
    {
      "file_path": "src/auth/login.ts",
      "edits": [
        {
          "line": 18,
          "old_text": "const result = validateUser(token);",
          "new_text": "const result = authenticateUser(token);",
          "confidence": "graph",
          "context": "async function loginHandler(req) {\n  const result = validateUser(token);\n  return result;\n}"
        }
      ]
    },
    {
      "file_path": "config.json",
      "edits": [
        {
          "line": 7,
          "old_text": "\"validator\": \"validateUser\"",
          "new_text": "\"validator\": \"authenticateUser\"",
          "confidence": "text_search",
          "context": "{\n  \"auth\": {\n    \"validator\": \"validateUser\"\n  }\n}"
        }
      ]
    }
  ],
  "summary": {
    "totalEdits": 12,
    "filesAffected": 8,
    "graphEdits": 10,
    "textSearchEdits": 2
  },
  "applied": false
}

​
Confidence Levels

Source: Knowledge graph relationshipsSafety: High — these are actual code references tracked by the graphExamples:
  • Function calls
  • Import statements
  • Class instantiations
  • Method invocations
Action: Generally safe to accept
Source: Regex text searchSafety: Lower — may include false positives like comments, strings, or unrelated matchesExamples:
  • References in config files
  • String literals
  • Comments
  • Dynamic references
Action: Review carefully, may need manual adjustment

​
Real-World Examples

​
Example 1: Safe Rename Workflow

// Step 1: Preview the rename
rename({
  symbol_name: "validateUser",
  new_name: "authenticateUser",
  dry_run: true  // default
})

// Review output:
// - 10 graph edits (safe): validator.ts, login.ts, middleware.ts...
// - 2 text_search edits (review): config.json, README.md

// Step 2: Review text_search edits
// config.json: "validator": "validateUser" → OK, should be renamed
// README.md: "...validateUser function..." → Documentation, OK

// Step 3: Apply the rename
rename({
  symbol_name: "validateUser",
  new_name: "authenticateUser",
  dry_run: false
})

// Step 4: Verify impact
detect_changes({ scope: "all" })
// → Affected: LoginFlow, TokenRefresh
// → Risk: MEDIUM

​
Example 2: Class Rename

// Rename a class and all its references
rename({
  symbol_name: "UserService",
  new_name: "UserRepository",
  dry_run: false
})

// Updates:
// - Class definition
// - All import statements
// - All instantiations
// - Type annotations

​
Example 3: Method Rename

// Rename a method within a class
rename({
  symbol_name: "getData",
  file_path: "src/services/ApiService.ts",
  new_name: "fetchData",
  dry_run: false
})

// Updates:
// - Method definition
// - All method calls on that class
// - Preserves other getData methods in different classes

​
Best Practices

Never skip the preview. Review the changes, especially text_search edits, before applying.
If you have a symbol_uid from query() or context() results, use it to avoid ambiguity.
Graph edits are safe, but text_search edits may include false positives (comments, strings, unrelated code).
After applying the rename, run detect_changes() to verify only expected files were modified.
Before renaming widely-used symbols, run impact() to understand the blast radius.
Rename operations can touch many files. Commit immediately after a successful rename to isolate it from other changes.

​
Workflow Checklist

- [ ] Run rename with dry_run: true (preview)
- [ ] Review graph edits (high confidence)
- [ ] Carefully review text_search edits (lower confidence)
- [ ] Apply rename with dry_run: false
- [ ] Run detect_changes() to verify scope
- [ ] Run tests for affected processes
- [ ] Commit the rename as a standalone change

​
Use Cases

  • Function renaming: Better naming for clarity
  • Class renaming: Architecture refactoring
  • Method renaming: API improvements
  • Variable renaming: Code quality improvements
  • Refactoring prep: Rename before extracting modules

​
Limitations

String Literals and Dynamic ReferencesThe rename tool cannot detect:
  • Dynamic property access: obj["validateUser"]()
  • String literals in external configs
  • References in non-indexed files
Solution: Use text_search results and manual review to catch these cases.
  • impact - Analyze blast radius before renaming
  • detect_changes - Verify rename scope after applying
  • context - Understand symbol usage before renaming
  • gitnexus://repo/{name}/processes - See which flows use the symbol

Build docs developers (and LLMs) love

Get started for freeTalk to us