facebook/chisel: LLDB commands for iOS app debugging

What Chisel solves for iOS debuggers

LLDB ships with breakpoints, expression evaluation and memory inspection, but it has no built-in vocabulary for UIKit objects. If you want to know which view is on screen, where it sits in the hierarchy, or why a border is invisible, you either write an expression by hand or add temporary code and rebuild. Chisel fills that gap with named commands that operate on live objects. The README describes the project as "a collection of LLDB commands to assist in the debugging of iOS apps", and the command table makes the intent concrete: pviews prints the recursive view description for the key window, fv finds a view whose class name matches a regex, border adds a border to a view or layer, and caflush flushes the render server. The audience is narrow by design. These commands talk to UIKit and Core Animation classes, so they matter to engineers debugging an app that is already running under LLDB, usually from Xcode. The compatibility column is worth reading before you plan around a command: pviews and border work on both iOS and OS X, while pvc, visualize, fv, fvc, mask and unmask are marked iOS only. That asymmetry is not explained in the README, and it is the first thing to check when a command silently does nothing on a Mac target.

How the command layer is wired into LLDB

Chisel is a Python package that LLDB imports at startup. The entry point is fbchisellldb.py at the repository root, and the ~/.lldbinit line uses the LLDB command script import to load it. Once loaded, the module registers user-defined commands, which is why the README points at the second list in LLDB's help output: the bottom list contains all the commands sourced from Chisel. The repository layout shows how the code is split. fbchisellldbbase.py holds the base command class, fbchisellldbinputhelpers.py handles argument and option parsing, and separate modules cover view helpers, view controller helpers, object helpers and Objective-C runtime helpers. The commands/ directory holds the individual command implementations. That structure matters if you plan to extend the tool: a custom command subclasses fb.FBCommand, implements name, description and run, and returns itself from a module-level lldbcommands() function. The run method receives arguments and options, and the README's example dispatches straight to lldb.debugger.HandleCommand with an expression string. LLDB does not always infer types on its own, so the example casts return values and arguments explicitly. There is also a loader function, loadCommandsInDirectory, in the fbobjclldb.py module, which sources every command in a directory. That is the mechanism behind local command sets.

Installing Chisel and running a first command

The documented install path is Homebrew. Two commands update the formula index and install the package.

brew update
brew install chisel

After that, LLDB needs to import the module. If ~/.lldbinit does not exist, the README shows creating and opening it, then adding an import line. On an Intel Mac the path is /usr/local/opt/chisel/libexec/fbchisellldb.py. On an M1 Mac the README says to use /opt/homebrew/opt/chisel/libexec/fbchisellldb.py instead.

# ~/.lldbinit
command script import /usr/local/opt/chisel/libexec/fbchisellldb.py

The README states the commands will be available the next time Xcode starts, so an already-running Xcode session will not pick them up. If you prefer not to use Homebrew, the alternative is to download Chisel and import the file from wherever you put it.

# ~/.lldbinit
command script import /path/to/fbchisellldb.py

Once LLDB has the commands, the first useful check is help. Running help with no argument prints the built-in commands and then your user-defined commands, and the bottom list is where Chisel's commands appear. To inspect one command, pass its name.

(lldb) help border

The README states that all commands come with verbose help, and the border entry documents its arguments and options: a viewOrLayer argument typed as UIView*, plus --color/-c for a color name and --width/-w for a CGFloat width. The first real use is to pause a running app, then run pviews to print the key window's recursive view description. If nothing prints, check the import path for your architecture before assuming the command failed.

Visual commands and the repaint workflow

The commands that change what you see are the ones that separate Chisel from plain expression evaluation. show and hide toggle a view or layer, and the README makes a specific claim about them: you do not have to continue the process to see the changes. border and unborder add or remove a border around a view or layer, which answers the question of where a view actually is when its frame is not obvious. mask and unmask overlay a transparent rectangle for the same purpose, though the compatibility table marks them iOS only. caflush is the command that ties these together. It flushes the render server, which the README equates to a repaint when no animations are in flight. If a visual change does not appear, caflush is the documented way to force it. visualize is the most platform-dependent command in the set: it opens a UIImage, CGImageRef, UIView, CALayer, NSData containing an image, UIColor, CIColor, CIImage, CGColorRef or CVPixelBuffer in Preview.app on your Mac. That list is long and specific, and it is also the clearest example of a command that only makes sense when the debugger host is a Mac. Two other commands are worth knowing for non-visual work. bmessage sets a symbolic breakpoint on a class method or an instance method without requiring you to know which class in the hierarchy implements it, and wivar sets a watchpoint on an instance variable. Both avoid the usual guesswork about where a method is actually implemented.

The limits of a debugger-side command set

Chisel is not a profiler, an allocation tracker or a crash reporter. It operates on objects that are alive in the process you are attached to, which means every command depends on a valid debugging session and, for most commands, on UIKit being loaded. The compatibility table already rules out part of the set on OS X targets, and the README does not explain why pvc or fv would not apply there. A second limit is the install path. The M1 note in the README exists because the Homebrew prefix changed, and a wrong path in ~/.lldbinit produces no obvious error at Xcode startup: the commands simply are not there. A third limit is version drift. The most recent release listed is 2.0.1 from 2020-08-17, and the last push to the repository was on 2026-03-15, so the code has moved since the last tagged release. Anyone pinning to 2.0.1 is not running the current main branch. Finally, these commands are invasive by nature: show, hide, border and mask mutate the running app's view state. That is useful while paused, and it is a reason not to run them against a build you cannot restart.

Chisel against writing raw LLDB expressions

The real alternative is not another package. It is the expression command you would otherwise type by hand. LLDB can evaluate Objective-C expressions, and the README's own custom command example ends in exactly that: a call to lldb.debugger.HandleCommand with a cast expression that reads the key window's windowLevel. Writing that expression yourself gives you full control and no dependency, and it works on any LLDB session without an import line in ~/.lldbinit. What Chisel adds is packaging: argument and option parsing through fbchisellldbinputhelpers.py, a shared base class, verbose help text per command, and a loader for local command directories. For a one-off inspection, a hand-written expression is faster. For a command you will run on every bug, the Chisel structure pays for itself, and the README explicitly asks for generic commands to be contributed back. The trade-off is that you inherit the project's compatibility matrix and its install path, including the architecture-specific Homebrew prefix.

Licence, maintenance and what to verify

Chisel is MIT-licensed, with the licence text in the LICENSE file at the repository root. MIT is permissive: it allows use, modification and redistribution with the licence and copyright notice retained. That is a statement about the licence text, not legal advice, and if you vendor the code into a product you should read LICENSE yourself rather than rely on a summary. On maintenance, the facts are mixed and worth separating. The repository is not archived, and the last push was on 2026-03-15. The most recent tagged release, 2.0.1, is from 2020-08-17, and 2.0.0 before it is titled "Python 3, At Last". So the tagged releases lag the branch by a wide margin. If you install through Homebrew you get whatever the formula ships, which may not match either the latest tag or main. The README does not document a rollback procedure, and it does not state which LLDB or Xcode versions are supported. Before relying on it, confirm that the import path matches your Mac, then run pviews and one visual command such as border followed by caflush on a throwaway build to see the documented behaviour for yourself.

Editorial conclusion

Chisel suits iOS engineers who already debug in LLDB and want to inspect the view hierarchy without pausing to add code. It is the wrong tool for anyone who does not attach LLDB to an iOS process, and it does not help with non-Apple platforms. Before adopting it, check that your ~/.lldbinit imports the correct path for your Mac architecture, and confirm on a running app that pviews prints the key window, since the README does not document a rollback path.

Frequently asked questions

Official sources

1. facebook/chisel on GitHub
2. Issues
3. License: MIT
4. README
5. Releases