Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…
Cannot retrieve contributors at this time
429 lines (313 sloc) 16.3 KB

% Kite - WebKit Remote Debugger Front-end % Julian Scheid % 2012-08-30

Kite is an Emacs front-end for the WebKit debugger. It enables inspecting, debugging, and live-editing Web pages and associated resources, such as scripts and stylesheets.


Kite is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Kite is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Kite. If not, see



Kite is known to be compatible with Emacs version 24.1. There are currently no plans for compatibility with older releases.

Automatic Installation

NOTE: Kite has not yet been uploaded to any package repository so these instructions do not apply.

Kite comes as a package conforming to Tromey's package.el. Ensure that an archive containing Kite is listed in package-archives and execute M-x package-install RET kite RET.

Manual Installation

Ensure that all kite source files as well as json.el and a recent version of websocket.el are on load-path and add (require 'kite) to your .emacs file.

Starting the Host Browser

Kite currently only supports the WebKit Remote Debugging API and thus won't work with browsers not based on WebKit, such as Firefox or Opera. Support for other remote debugging interfaces may be added in the future.

Many WebKit-based browsers do not yet expose the remote debugging interface and thus can't be used with Kite. At the time of this writing, the only browsers supported are recent versions of Chromium, Google Chrome, and Mobile Safari.

We are working on adding a remote debugging interface to WebKitGTK+. This will enable debugging of WebKit instances embedded via the Emacs xwidgets branch.

Enabling Remote Debugging on Chromium and Google Chrome

You can enable remote debugging for Chromium and Google Chrome by passing the --remote-debugging-port=<port> command line option. You may have to use the Google Chrome beta or development channel for this to work.

The recommended default port is 9222. Thus, to start Google Chrome with the default port on Mac OS X, you would execute the following command:

    open /Applications/Google\ --args --remote-debugging-port=9222

For more information, see here:

Enabling Remote Debugging on Mobile Safari

Remote debugging a Mobile Safari instance has not yet been tested by us. If you want to give it a try, follow the instructions here:

Kite Sessions

Kite's most fundamental concept is that of a debugging session, which corresponds to an open connection to the remote debugging API for one specific open browser tab. Kite supports multiple simultaneous debugging sessions, but usually you will only have a single session active.

A single WebKit tab can currently only be connected to one debugger, so if you are using the default WebKit debugging front-end you won't be able to use Kite, and vice versa.

Kite Buffers Overview

Kite provides a number of special buffers (major modes), each of which allows for interaction with one aspect of a debugging session.

Accessing a Kite buffer when there is no debugging session active yet will prompt you to establish a new one. See instructions on establishing a debugging session.

You can access Kite buffers using global key bindings or with an M-x incantation. The following buffers are available:

Key Binding Incantation Description

C-c C-k c kite-console View console messages C-c C-k d kite-debugger View and manage breakpoints C-c C-k h kite-heap Analyze heap usage C-c C-k s kite-scratch Evaluate JavaScript code in page context C-c C-k m kite-dom Inspect and manipulate the DOM C-c C-k n kite-network Analyze HTTP requests and responses

There are also secondary buffer types for inspection of JavaScript objects, stack frames, messages, per-DOM element CSS properties, and more. How such buffers are accessed depends on context, but is usually achieved by moving the point onto the textual representation of an entity and hitting RET.

Establishing a Debugging Session

When you access a Kite buffer and there is no debugging session active yet, an attempt will be made to establish a connection to a WebKit remote debugger interface on kite-default-remote-host (default: and kite-default-remote-port (default: 9222).

If the connection succeeds you will be presented with a prompt that allows you to choose which of the pages currently open in the WebKit instance you want to debug. You can enter either the page URL or its title, and there are completions available for both.

In case that the same page is open multiple times in the WebKit instance, the individual instances of the page are disambiguated using a numeric suffix derived from an internal WebKit identifier. Unfortunately, there is currently no easy way to know which suffix corresponds to which WebKit tab. However, pages opened later in time usually have higher suffix numbers.

Remote Sessions and Multiple Debugging Sessions

In some situations you might want to debug more than one page simultaneously. Use a prefix argument of (4) (the default when you use the C-u modifier key) for any of the Kite buffer commands and Kite will prompt you for a new session rather than using the existing one.

You might also want to connect to a remote WebKit instance, i.e. one not running on kite-default-remote-host or kite-default-remote-port. By giving a prefix argument of (16) (by using the C-u modifier key twice) you'll force Kite to ask you for the host and port to connect to.

Navigating Kite Buffers with Multiple Sessions

If you have multiple debugging sessions active, Kite will normally attempt to keep you within the current session. For example, if you have two session active and you are currently visiting the kite console buffer for the first session, then doing M-x kite-scratch will take you to the scratch buffer for the first session.

If you want to switch to a Kite buffer for a different session, there are three ways of doing so.

Firstly, you can simply use the mechanics afforded by M-x switch-to-buffer when multiple sessions are active, Kite buffer names carry a suffix derived from the (possibly disambiguated) page title.

Secondly, by using the Kite command to switch to a buffer while visiting a buffer of the same type, Kite will cycle through the buffers for all open debugging sessions. For example, if you are currently visiting the *kite console* buffer for the first session, then doing M-x kite-console will take you to the *kite console* buffer for the second session.

Finally, you can use a numeric prefix with the buffer access commands and Kite will take you straight to the buffer for the corresponding session, where the first session you opened is numbered 1, the second session 2, and so on. For example, M-2 C-c C-k c will take you to the console buffer for the second session. Note that numeric session designators will change as you close debugging sessions. Use the Kite Session List if you ever lose track.

Kite Buffers

Console Buffer

The console buffer shows any messages which scripts on the page have emitted using the console object.

The console buffer can be opened using M-x kite-console or by typing C-c C-k c with default key bindings.

Evaluating JavaScript code

You can type JavaScript code at the prompt and hit RET or C-j to send it to the remote debugger. The result of the evaluation or the stack trace (in case of error) will be displayed. The prompt supports basic identifier completion via the TAB key.

Special Items in Messages

Some parts of console messages have special key bindings:

Object representations are rendered with kite-object-face and show an abbreviated representation of a JavaScript object. Typing RET (M-x kite-inspect) with point over the object representation brings up an Object Inspector view for that object.

DOM node representation are rendered with kite-node-face and show an abbreviated representation of a DOM node. Typing RET (M-x kite-inspect) with point over the DOM node representation brings up the corresponding DOM view and moves point to the beginning of the node in question.

Message Details

In the console view, type C-c i to bring up an detail view for the message under point (kite-show-log-entry). The detail view show all available information on the log message, some of which is elided from the console view for brevity's sake.

Message Source

In the console view, type C-c g to go to the source location at which the message at point was emitted. If point is on a stack trace, go to the source location for the stack frame at point.

Tail Follow

If point is at the end of the console view buffer when a new message arrives, it will be moved to the end again. In other words, if point is at the end of the buffer it will stay at the end of the buffer. This allows you to always see the most recent messages, but at the same time leaves point alone when you examine other parts of the buffer.

Page Reloads

When the browser page is reloaded (either via kite-reload-page or by any other means, such as using the browser UI or by JavaScript code), kite-console-page-reloaded-function is executed with the console buffer current and point at the end of the buffer. By default, this function only inserts a page break followed by a line feed. In other words, messages from previous incarnations of the page are not cleared by default.

This default behaviour is useful because it gives convenient access to past messages. You can bind kite-console-page-reloaded-function to erase-buffer if you prefer the behaviour of the default Webkit Inspector Frontend, which clears past messages on page reload.

Debug Buffer

The debug buffer shows any breakpoints currently set and allows to clear breakpoints. It also shows whether JavaScript execution is currently paused.

Sorry, no further documentation available yet. Use M-x describe-mode in a Kite Debug buffer to learn about available key bindings.


  • Overall, the JavaScript debugger is not very usable yet.
  • When a breakpoint is hit, Emacs shows the source file and jumps to the break location; however, it doesn't show the stack trace or any variable bindings.
  • There should be a way to tell Emacs which local file corresponds to a network resource, so that Emacs can open the local file for editing. Source map support should also be implemented.
  • A number of basic debugger commands, such as "execute until here", are not yet implemented.

Scratch Buffer

Sorry, no documentation available yet. Use M-x describe-mode in a Kite Scratch buffer to learn about available key bindings.


  • This mode is currently very experimental.

Network Buffer

Sorry, no documentation available yet. Use M-x describe-mode in a Kite Network buffer to learn about available key bindings.


  • The Network inspector doesn't yet sorting the table by criteria other than resource load order.

  • The Network inspector doesn't provide access to request and response headers, cookies, etc.

  • The code for the Network inspector is pretty convoluted; it should be rewritten using CL structs so that the intermediate representation is less obtuse and can be more easily reused for alternate display representations.

DOM Buffer

Sorry, no documentation available yet. Use M-x describe-mode in a Kite DOM buffer to learn about available key bindings.


  • The DOM inspector doesn't support DOM mutation yet: although local modification is partially implemented, changes can not yet be sent to the remote debugger.

  • Likewise, CSS mutation isn't only partially implemented.

Heap Buffer

Sorry, no documentation available yet. Use M-x describe-mode in a Kite Heap buffer to learn about available key bindings.

Global Key Bindings

In addition to the key bindings listed in section Kite Buffers Overview, the following keys are bound by default:

Key Binding Incantation Description

C-c C-k ! kite-reload-page Reload the page; ignore cache with prefix

Jump to Line
Something went wrong with that request. Please try again.