`monocle` - a CLI for coding agents to inspect Swift symbols via SourceKit-LSP

Community Showcase
, ,
1

Hey,

I’ve been hacking on a small tool called monocle and thought I’d share it in case it’s useful for anyone working with coding agents like Codex or Claude Code.

monocle is a thin wrapper around SourceKit‑LSP. Given a file + line + column, it asks SourceKit‑LSP what lives at that location and prints:

  • the symbol’s signature
  • the definition location (file + line range — including things in DerivedData, Swift/SwiftUI SDK overlays, etc.)
  • a short code snippet
  • the doc comment (if available)

In other words: it’s a “ jump to definition + quick help” tool that coding agents can use to figure out what a symbol actually is and does.

Example

Say you have a call to withErrorReporting in your app (coming from a dependency pulled in via SPM; in this case it's from Point-Free's amazing SQLiteData package). Your coding agent sees this but has trouble figuring out how it works. It can then simply call monocle:

monocle inspect --file MyApp/Features/Home/Home.swift --line 125 --column 11

monocle queries SourceKit‑LSP and prints something like:

Signature:
func withErrorReporting<R>(
  _ message: @autoclosure () -> String? = nil,
  to reporters: [any IssueReporter]? = nil,
  fileID: StaticString = #fileID,
  filePath: StaticString = #filePath,
  line: UInt = #line,
  column: UInt = #column,
  isolation: isolated (any Actor)? = #isolation,
  catching body: () async throws -> sending R
) async -> R?

Definition:
file:///Users/you/Library/Developer/Xcode/DerivedData/MyApp-.../SourcePackages/checkouts/xctest-dynamic-overlay/Sources/IssueReporting/ErrorReporting.swift:103-103

Snippet:
  public func withErrorReporting<R>(

Documentation:
Evaluates a throwing closure and automatically catches and reports any error thrown.

- Parameters:
  - message: A message describing the expectation.
  - reporters: Issue reporters to notify during the operation.
  - fileID: The source `#fileID` associated with the error reporting.
  - filePath: The source `#filePath` associated with the error reporting.
  - line: The source `#line` associated with the error reporting.
  - column: The source `#column` associated with the error reporting.
  - isolation: The isolation associated with the error reporting.
  - body: An asynchronous operation.
- Returns: The optional result of the operation, or `nil` if an error was thrown.

There is also a --json option to print all this information in JSON format.

This works even when the symbol comes from:

  • external packages checked out in DerivedData
  • Swift / SwiftUI SDK headers
  • other modules that aren’t part of your current working directory
  • in general, anything that the lsp can resolve

Purpose

The main goal of monocle is to give coding agents a reliable way to look up Swift symbols:

  • Stable, machine‑readable output that agents can parse for signatures, locations, and doc comments.
  • No scraping of IDEs, or generated docs — everything comes straight from SourceKit‑LSP.
  • Works from anywhere you can run a process with access to the project and its build products (local dev, CI, remote workers, etc.).

If you’re working with agents that need to understand or refactor Swift code, monocle can be their “jump to definition + quick help” tool.

There might still be problems with this tool. It's a first version but I am already using it in my projects and it helps Codex quite well for me.

If you’re curious, the repo is here:
https://github.com/SwiftedMind/monocle

3 Likes