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 4mo 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

Monocle is a specialized CLI tool that enables coding agents to quickly resolve Swift symbols—including types, methods, and properties—from any location in your codebase or external dependencies. It queries SourceKit-LSP to return symbol definitions, signatures, rendered documentation, and precise file locations in stable JSON format. Agents benefit from fast, reliable symbol resolution without IDE overhead, making it ideal for understanding unfamiliar APIs and third-party packages during code analysis and development tasks. The tool supports both Swift packages and Xcode projects/workspaces, and includes optional daemon mode to eliminate cold starts during repeated lookups.

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."}]

Use Cases

Agents resolving symbol definitions and documentation across unfamiliar Swift codebases

Listing and inspecting SwiftPM dependencies for external package analysis

Retrieving signatures and doc comments for symbols involved in errors or warnings

Fast symbol lookup by name across project and package sources

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).