DESTRUCTIVE: Modifies .kt files. Surgically edit text content with automatic BridgeTextRegistry wrapping.

What it does: Modifies .kt files. Auto-migrates hardcoded text to BridgeTextRegistry for live preview.
When to use: When editing UI text strings, whether defined in AppStrings or hardcoded in Composable Text("...") elements.
When NOT to use: Do not use for colors or dimensions (use set_token or add_token).
Side effects: DESTRUCTIVE: Modifies source code on disk. Requires approve_file_changes before changes take effect in git. Can be reverted via reject_file_changes.
Parameters:
  - token_name: reference key (e.g., 'AppStrings.Dashboard.title') OR exact old text content to replace.
  - new_value: The new text string to set.
  - file_path: relative path to source file (e.g., 'QuickActionsWidget.kt' or 'ui/theme/AppStrings.kt').
  - line: optional line number for disambiguation if text appears multiple times.
Returns:
  JSON string with success status, old_text, new_text, and modified file location.

Convert a hardcoded value to a design token.

This tool:
1. Adds a new token definition to AppDimens.kt or AppColors.kt
2. Replaces ONLY the specified line with the new token
3. Does NOT touch any other line in the project

Use list_tokens() first to find hardcoded values that
could become tokens.

Args:
    file: File name (e.g., "DashboardPage.kt")
    line: Line number (1-indexed)
    value: Expected value (e.g., "16.dp" or "0xFF7C3AED")
    token_name: New token name (e.g., "padding_md")
    token_type: "dimension" or "color"
    preferred_token_file: Optional target token file (e.g. "Tokens.kt")
    force_create: ⚠️ force_create bypasses duplicate detection. Use ONLY for testing.

Returns:
    JSON with success status and details.

Read-only analysis. Detects if project uses camelCase, snake_case, or PascalCase for tokens.

What it does: Analyzes existing tokens to detect whether project uses camelCase, snake_case, or PascalCase.
When to use: Use BEFORE creating new tokens with add_token or replace_pattern to maintain project consistency.
When NOT to use: Do not use to inspect actual token values; use list_tokens instead.
Side effects: Read-only. No files modified.
Parameters:
  - token_type: 'dimension' (default) or 'color'.
Returns:
  JSON string with detected style (e.g. 'camelCase'), confidence score, examples, and recommendations.

List all design tokens in the project.

Returns a comprehensive report:
- Registered tokens (dimensions, colors)
- Hardcoded values that could become tokens
- Duplicate tokens (same value, different names)
- Orphan tokens (registered but unused)

When to use:
- Call to explore all existing design tokens (colors and dimensions) and hardcoded literals in the project.
- Call before adding or modifying tokens to understand the existing design system.

When NOT to use:
- Do not use for reverse hex lookup (use find_token_by_color instead).
- Do not use for editing token values (use set_token or add_token instead).

Side effects:
- None (strictly read-only design token inspection).

Args:
    project_path: optional — explicit path to project root.

DESTRUCTIVE: Modifies .kt files. Surgically edit a design token value in source code.

What it does: Modifies .kt files containing the token definition. Notifies phone via WebSocket (live preview).
When to use: When adjusting a design token (color or dimension) and immediately observing visual feedback.
When NOT to use: Do not use for text strings (use set_text). Do not use for converting hardcoded values to tokens (use add_token).
Side effects: DESTRUCTIVE: Modifies source code on disk. Requires approve_file_changes to commit changes or reject_file_changes to revert.
Parameters:
  - token_name: exact token name OR 'AppColors.TokenName' (e.g., 'Primary', 'cardCorner').
  - value: '#RRGGBB' for colors or numeric for dimensions (e.g., '#FF1122', '24.dp').
Returns:
  JSON string with update status, file path, and previous/new values.

List all orphan tokens (registered but never used).

When to use:
- Call during design system cleanup or dead code elimination.

When NOT to use:
- Do not use to delete tokens directly (must be removed manually or approved).

Side effects:
- None (strictly read-only orphan detection).

Orphan tokens are a sign of design system clutter.
Use this to identify tokens that can be safely removed
or that need to be used in the codebase.

Args:
    project_path: optional — explicit path to project root.

Returns:
    JSON with list of orphan tokens and their locations.

Get impact analysis for a specific token.

When to use:
- Call BEFORE modifying or deleting a token to see every file and line that references it.

When NOT to use:
- Do not use if you already intend to change all occurrences without impact inspection.

Side effects:
- None (strictly read-only impact analysis).

Shows:
- All places where the token is used (file:line)
- The enclosing @Composable for each usage
- Total number of affected UI elements

Use this BEFORE changing a token to understand the impact.

Args:
    token_name: "welcomeCardHeight" or "Primary"
    project_path: optional — explicit path to project root.

Returns:
    JSON with full impact analysis.

Read-only analysis. Suggests splitting tokens used in multiple contexts.

What it does: Detects if a token is used in different contexts (e.g. cards and buttons) and proposes contextual splits.
When to use: Use BEFORE replace_pattern.
When NOT to use: For token impact analysis use get_token_impact. For sibling tokens use get_token_siblings.
Side effects: Read-only. No files modified.
Parameters:
  - token_name: optional filter to analyze a specific token only.
  - project_path: optional override for project root path.
Returns:
  JSON string with split suggestions, proposed token names, and affected call sites.

Detect repeated patterns like:
if (isDark) Color(0xFF818CF8) else AppColors.Primary

Args:
    token_name: optional — filter by base token name.
    
Returns:
    JSON with detected patterns + occurrences + suggestions.

Read-only. Returns semantically related tokens (e.g., Primary → PrimaryDark, PrimaryLight).

What it does: Finds related variants of a token based on naming patterns and semantic links.
When to use: When exploring related tokens or checking which color variants already exist.
When NOT to use: Does NOT include the original token. Returns empty list if no siblings.
Side effects: Read-only. No files modified.
Parameters:
  - token_name: exact token name (e.g., 'Primary') or fully-qualified (e.g., 'AppColors.Primary').
Returns:
  JSON string with list of sibling token names and current values.

Read-only. Returns ALL semantic token groups in the project (e.g., 'Actions', 'Dashboard', 'Settings').

What it does: Lists all token groups discovered across design system objects.
When to use: To inspect the high-level semantic grouping of design tokens.
When NOT to use: Use list_tokens for individual tokens. Groups are based on object declarations in AppStrings/DesignSystem.
Side effects: Read-only. No files modified.
Parameters: None.
Returns:
  JSON string with group names, member token counts, and parent objects.

Read-only. Lists files modified by recent replace_pattern operations in the current session.

What it does: Queries the session journal to return all files currently in a modified state.
When to use: To see what files have unapproved changes before approving or rejecting.
When NOT to use: Does NOT persist across sessions. For git-based modifications use get_file_diff. Returns files in journal (not git status).
Side effects: Read-only. No files modified.
Parameters: None.
Returns:
  JSON string with list of relative file paths.

Destructive: Reverts pending changes for a SINGLE file using .bridge.bak backup.

What it does: Rolls back byte-for-byte to the state before the recent surgical edit or replace_pattern.
When to use: When modifications to a specific file are incorrect and need to be discarded.
When NOT to use: File must be currently modified. Use reject_all_files for all files.
Side effects: Destructive rollback. Overwrites file with original backup and removes entry from journal.
Parameters:
  - file_path: relative path to project root (e.g., 'QuickActionsWidget.kt' or 'ui/theme/AppStrings.kt').
Returns:
  JSON string confirming rollback of the file.

Approves pending changes for a SPECIFIC file. Removes its entry from journal.

What it does: Marks changes as accepted and discards the backup so the file is no longer in pending state.
When to use: When changes to a specific file have been inspected (via get_file_diff) and verified correct.
When NOT to use: File must be modified. To approve all files use approve_all_files.
Side effects: Clears the journal entry and backup for this file. Modifications remain permanently on disk.
Parameters:
  - file_path: relative to project root (e.g., 'QuickActionsWidget.kt' or 'ui/theme/AppStrings.kt').
Returns:
  JSON string confirming file approval.

Destructive: Approves ALL pending changes permanently. Removes them from journal.

What it does: Permanently accepts all pending changes in the journal across all modified files.
When to use: When all modifications from recent operations are verified and accepted.
When NOT to use: No rollback after this action. Use approve_file_changes for single files. Use reject_all_files to discard instead.
Side effects: Destructive: Permanently clears all backups and journal entries. Changes cannot be rolled back.
Parameters: None.
Returns:
  JSON string confirming all files approved.

Destructive: Reverts ALL pending changes using byte-level backup (.bridge.bak).

What it does: Rolls back byte-for-byte all files modified in the current journal session.
When to use: To completely discard all recent changes and return every file to its exact prior state.
When NOT to use: Use reject_file_changes for a single file. Use reject_all_files_force if some rollbacks may fail.
Side effects: Destructive rollback. Overwrites all modified files with their .bridge.bak backups and clears journal.
Parameters: None.
Returns:
  JSON string with list of reverted files and status.

Destructive + Forceful. Clears the entire journal EVEN IF some rollbacks fail.

What it does: Forcefully attempts rollback and clears the journal unconditionally.
When to use: Use only when reject_all_files fails due to missing backups or file corruption.
When NOT to use: May leave files in inconsistent state. For safe rollback use reject_all_files.
Side effects: Destructive + Forceful: Clears all journal tracking regardless of whether every file reverted cleanly.
Parameters: None.
Returns:
  JSON string with forced rollback results.

Read-only. Returns before/after content and unified diff for a specific modified file.

What it does: Computes unified diff comparing original backup (.bridge.bak) with current on-disk content.
When to use: To inspect exact changes before approving (approve_file_changes) or rejecting (reject_file_changes).
When NOT to use: Use list_modified_files first to get valid paths. file_path should match the entry from list_modified_files (relative to project root).
Side effects: Read-only. No files modified.
Parameters:
  - file_path: relative path to project root (e.g., 'QuickActionsWidget.kt' or 'ui/theme/AppStrings.kt').
Returns:
  JSON string with original content, modified content, and unified diff.

Approves a single granular change (hunk) in a file.

What it does: Incorporates the specific change into the file's baseline backup, leaving other changes pending.
When to use: When one specific change in a file is approved, but other changes need further inspection or rejection.
Parameters:
  - file_path: relative path to project root
  - change_id: hunk ID (e.g. "h1", "h2") or line number
Returns:
  JSON string with operation result and remaining changes.

Reverts a single granular change (hunk) in a file while keeping other changes intact.

What it does: Reverts only the specified hunk back to its original baseline on disk.
When to use: When one specific change in a file is unwanted, but other changes in the file should be kept.
Parameters:
  - file_path: relative path to project root
  - change_id: hunk ID (e.g. "h1", "h2") or line number
Returns:
  JSON string with operation result and remaining changes.

Safely cleans temporary cache, state files, and logs (.composebridge-state, .composebridge-journal.json, *.tmp)
without touching source code or .bridge.bak backups.

DESTRUCTIVE BATCH OPERATION: Replaces ALL occurrences of a pattern across the project.

What it does: Creates new token + replaces usages. Can be rolled back via rollback_pattern(pattern_id).
When to use: When replacing a recurring conditional or hardcoded pattern across all files.
When NOT to use: USE dry_run=True FIRST to preview affected files. pattern_id must come from detect_conditional_variants.
Side effects: DESTRUCTIVE: Modifies multiple .kt files simultaneously. Records changes in journal.
Parameters:
  - pattern_id: Unique pattern identifier from detect_conditional_variants.
  - dry_run: If True (recommended first), previews changes without writing to disk.
Returns:
  JSON string with replacements made, modified files, and created token name.

List all applied patterns that can be rolled back.

When to use:
- Call to inspect history of pattern refactorings before deciding to roll back.
- Call to retrieve valid pattern_ids for rollback_pattern.

When NOT to use:
- Do not use to revert changes (use rollback_pattern instead).

Side effects:
- None (strictly read-only journal lookup).

Rolls back ALL changes made by a specific replace_pattern call.

When to use:
- Call when a pattern replacement resulted in unexpected UI behavior or compilation issues.
- Call to safely undo all file changes associated with a pattern_id.

When NOT to use:
- Do not use to revert single token edits (use rollback_last or reject_change instead).
- Do not use without a valid pattern_id from list_applied_patterns.

Side effects:
- DESTRUCTIVE: Modifies source files on disk to restore their pre-replacement states.


What it does: Requires pattern_id from the original replace_pattern response. All files are reverted byte-for-byte.
When to use: When a replace_pattern operation caused regressions and needs complete reversal.
When NOT to use: Cannot undo if files were modified externally. Use rollback_last for single-edit undo.
Side effects: Destructive rollback. Modifies all files touched by the pattern back to their prior state.
Parameters:
  - pattern_id: The exact pattern_id from the original replace_pattern response.
Returns:
  JSON string with list of reverted files and status.

Run a Gradle task with async tracking support.

When to use:
- Call to verify that surgical edits or token refactorings compile without errors.
- Call after batch changes before approving or completing a task.

When NOT to use:
- Do not use for arbitrary shell execution; tasks are strictly whitelist-restricted.
- Do not use for simple file reading or AST validation (use check_syntax_cli or ast_finder instead).

Side effects:
- Executes a Gradle build process in background; may write build artifacts to build/ directories.


This lets the agent verify that code changes compile successfully
before continuing with more changes, without locking the MCP connection.

Args:
    task: gradle task to run (whitelist enforced: assembleDebug, assembleRelease, test, lint, clean, etc.).
    timeout_seconds: max execution time (default 5 min).
    async_mode: if true (default), returns job_id immediately so agent can poll with get_gradle_status.

Returns:
    JSON with job_id and status, or execution result if sync.

Check the status and result of a Gradle build job.

When to use:
- Call to poll background Gradle build status returned by run_gradle_build.

When NOT to use:
- Do not use if no Gradle job was started.

Side effects:
- None (strictly read-only job status query).


Args:
    job_id: ID returned by run_gradle_build.
    
Returns:
    JSON with {job_id, status: 'queued'|'running'|'completed'|'failed', result: {...}}.

List gradle tasks that can be run via run_gradle_build.

When to use:
- Call to check which Gradle tasks are whitelisted for safe execution.

When NOT to use:
- Do not use to run builds (use run_gradle_build instead).

Side effects:
- None (strictly read-only whitelist listing).

Trigger user_sync on the Bridge Server.

When to use:
- Call to flush and apply pending queued edits (dimensions and colors) from the Android device to source files.

When NOT to use:
- Do not use if the AI agent is actively modifying source files (agent_busy lock).

Side effects:
- Modifies source files on disk by applying pending changes from the queue.


Applies all queued edits (dimension + color) to the files.
Only works when the AI agent is not busy.

Returns:
    JSON with {success, applied, skipped, errors}.

Get the current sync status from the Bridge Server.

When to use:
- Call to inspect agent_busy, queue_count, and snapshot_version before running batch operations.

When NOT to use:
- Do not use to apply changes (use trigger_user_sync instead).

Side effects:
- None (strictly read-only state inspection).

Analyzes scattered hardcoded design tokens (colors, dimensions, strings) across the project.
Returns a compact, categorized report to avoid context window exhaustion.

When to use:
- Call during project onboarding, architecture audits, or before major UI refactorings.
- Call to locate hardcoded color literals, raw Dp values, and string literals across Jetpack Compose files.

When NOT to use:
- Do not use if you already know the exact token name or file (use find_token_by_color or list_tokens instead).
- Do not use for applying code changes directly (use set_token, add_token, or set_text instead).

Side effects:
- None (strictly read-only AST inspection, does not modify any source code or configuration).

Args:
    category: 'all', 'colors', 'dimensions', or 'strings'.
    limit: Maximum number of files to return per category (default: 10).
    project_root: Optional path to project root.

Sets a designated design/registry file in .composebridge/config.json for a token type.

When to use:
- Call when ComposeBridge stops with NEEDS_MANUAL_MAPPING because design system files are in non-standard paths.
- Call to lock designated target files for colors, dimensions, or strings.

When NOT to use:
- Do not use if the project uses standard design file locations (e.g., Color.kt, AppStrings.kt).
- Do not use for reading existing token mappings (use get_design_file_mappings instead).

Side effects:
- Modifies .composebridge/config.json on disk to persist file mappings.

Args:
    token_type: 'color', 'dimension', 'string', or 'all'.
    file_path: Relative path to the Kotlin file (e.g. 'composeApp/src/commonMain/kotlin/.../Color.kt').
    project_root: Optional path to project root.

Returns current design/registry file mappings configured in .composebridge/config.json.

When to use:
- Call before modifying design tokens to inspect which files are mapped for colors, dimensions, and strings.
- Call to verify current target files when debugging token resolution issues.

When NOT to use:
- Do not use to configure or modify file mappings (use set_design_file_mapping instead).
- Do not use to list token names and values (use list_tokens instead).

Side effects:
- None (strictly read-only configuration lookup, does not modify any files).

Args:
    project_root: Optional path to project root.