| find_token_by_colorB | Reverse lookup: Find token(s) matching an exact hex color. |
| rollback_lastB | Reverts the LAST surgical edit made in the current session. |
| add_tokenA | 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.
|
| get_naming_conventionA | 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_tokensA | 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)
Use this to understand the project's design system
before making edits.
Args:
project_path: optional — explicit path to project root.
|
| set_tokenA | 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.
|
| set_textA | 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.
|
| list_orphansA | List all orphan tokens (registered but never used).
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_token_impactA | Get impact analysis for a specific token.
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.
|
| suggest_token_splitA | 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_conditional_variantsA | 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.
|
| replace_patternA | 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_applied_patternsA | List all applied patterns that can be rolled back. |
| rollback_patternA | Rolls back ALL changes made by a specific replace_pattern call.
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.
|
| get_token_siblingsA | 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.
|
| get_all_token_groupsA | 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.
|
| list_modified_filesA | 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.
|
| reject_file_changesA | 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.
|
| approve_file_changesA | 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.
|
| approve_all_filesA | 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.
|
| reject_all_filesA | 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.
|
| reject_all_files_forceA | 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.
|
| get_file_diffA | 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.
|
| run_gradle_buildA | Run a Gradle task and return structured result.
This lets the agent verify that code changes compile successfully
before continuing with more changes.
Args:
task: gradle task to run (whitelist enforced: assembleDebug, assembleRelease, test, lint, clean).
timeout_seconds: max execution time (default 5 min).
Returns:
JSON with {success, exit_code, duration_ms, errors, warnings}.
|
| list_allowed_gradle_tasksA | List gradle tasks that can be run via run_gradle_build. |
| trigger_user_syncA | Trigger user_sync on the Bridge Server.
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_sync_statusA | Get the current sync status from the Bridge Server:
agent_busy, queue_count, snapshot_version.
|
