monocle

🥈Silver

Monocle is a Swift symbol lookup CLI tool powered by SourceKit-LSP. It enables coding agents to quickly find and reference symbols in Swift codebases. Operations teams benefit from faster code navigation and reduced context-switching. It integrates with existing development workflows and connects to tools like Claude for enhanced coding assistance.

4730Updated 2mo ago

Intermediate30min to implementautomation

Saves ~45 min per use

Quick InstallView Source

git clone https://github.com/SwiftedMind/monocle.git

Works with:

Claude

Overview

About This Skill

How to Use

[{"step":"Install Monocle CLI if not already installed. Run `brew install monocle` or follow the [official installation guide](https://github.com/keith/monocle).","tip":"Ensure your Swift toolchain is up-to-date (Monocle relies on SourceKit-LSP)."},{"step":"Run Monocle with the required arguments. For example:\n```bash\nmonocle --project-path ./AcmeApp --symbol NetworkService --output json\n```","tip":"Use `--include-dependencies` to search through third-party libraries or frameworks."},{"step":"Pipe the output to your preferred tool for further analysis. For example, in Claude:\n```\nmonocle --project-path ./AcmeApp --symbol NetworkService | claude\n```","tip":"Use `--context-lines 3` to include more surrounding code for better context."},{"step":"Review the results and take action. Use the structured output to update code, refactor, or document changes.","tip":"Save frequently used Monocle queries as shell aliases or scripts for reuse."},{"step":"Integrate Monocle into your CI/CD pipeline to catch deprecated symbols or breaking changes early. Example:\n```yaml\n# In your GitHub Actions workflow\n- name: Check for deprecated symbols\n run: monocle --project-path ./AcmeApp --symbol UserDefaults --deprecated-only --output json > deprecated_symbols.json\n```","tip":"Use `--deprecated-only` to filter results and focus on critical updates."}]

Setup & Installation

Quick Install

No install command available. Check the GitHub repository for manual installation instructions.

Alternative Install (Git Clone)

git clone https://github.com/SwiftedMind/monocle

Requirements

Claude Code or compatible AI agent
Works with: Claude

Quick Start Guide

Install the Skill

Copy the install command above and run it in your terminal.

Open Your AI Agent

Launch Claude Code, Cursor, or your preferred AI coding agent.

Try It Out

Use the prompt template or examples below to test the skill.

Customize

Adapt the skill to your specific use case and workflow.

Usage Examples

Prompt Template

Use Monocle to analyze the Swift codebase in [PROJECT_PATH]. Find all references to the symbol [SYMBOL_NAME] (e.g., a class, struct, or function) across the entire codebase, including nested files and dependencies. For each reference, provide the file path, line number, and a brief context (2-3 lines of surrounding code). If the symbol is deprecated or marked with @available(*, unavailable), flag it explicitly. Output the results in a structured format suitable for quick review in [TOOL_NAME].

Example Output

```
Found 12 references to `NetworkService` in the 'AcmeApp' codebase:

1. **File:** Sources/Networking/NetworkService.swift
   **Line:** 42
   **Context:**
   ```swift
   final class NetworkService {
       private let session: URLSession
   ```
   **Status:** Active (no deprecation markers)

2. **File:** Sources/Features/Login/LoginViewModel.swift
   **Line:** 18
   **Context:**
   ```swift
   private let networkService = NetworkService()
   ```
   **Status:** Active

3. **File:** Sources/Utilities/Deprecated/OldNetworkLayer.swift
   **Line:** 25
   **Context:**
   ```swift
   @available(*, deprecated, message: "Use NetworkService instead")
   class OldNetworkLayer {
   ```
   **Status:** Deprecated (replace with NetworkService)

4. **File:** Tests/NetworkServiceTests.swift
   **Line:** 12
   **Context:**
   ```swift
   class NetworkServiceTests: XCTestCase {
       var sut: NetworkService!
   ```
   **Status:** Active

**Summary:**
- Total references: 12
- Active symbols: 10
- Deprecated symbols: 1
- Unavailable symbols: 1 (in LegacyCode.swift)
```

**Recommendations:**
- Replace `OldNetworkLayer` with `NetworkService` in all non-test files.
- Update `LegacyCode.swift` to use `NetworkService` or remove it.
- Review `LoginViewModel.swift` for potential optimizations (e.g., dependency injection).