An experimental fork of brodie's MouseTerm.
Objective-C Makefile C AppleScript Python DTrace Shell
Pull request Compare This branch is 186 commits ahead of brodie:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

MouseTerm plus

MouseTerm plus is the provisional fork of brodie's MouseTerm. We want to push the fruits of this experimental project to the original MouseTerm, if possible.

MouseTerm is a SIMBL plugin for Mac OS X's that passes mouse events to the terminal, allowing you to use mouse shortcuts within applications that support them.


Installer package with source code is available:


MouseTerm-Plus added some fixes to original MouseTerm and implemented a lot of tweaks that includes various features unrelated to mouse emulation.

Original MouseTerm(version 1.0b1) does:

  • Mouse normal event reporting ( of OS X El Capitan supports this by default).
  • Mouse button event reporting ( of OS X El Capitan supports this by default).
  • Mouse scroll wheel reporting ( of OS X El Capitan supports this by default).
  • Simulated mouse wheel scrolling for programs like less (i.e. any fullscreen program that uses application cursor key mode).
  • Menu item integration.

Additionally, this project does:

  • Fix OS X Mavericks installation problem. On El Capitan, you have to disable System Integrity Protection(SIP) temporarily for the installation.
  • Fix some bugs around mouse event coordinate handling.
  • Performance improvement: filter out extra motion events during mouse dragging.
  • Handle RIS (hard reset) sequence correctly (reset(1) command works well).
  • Tested on OS X El Capitan.
  • Support URXVT 1015 styled mouse tracking(already backported into original source, of OS X El Capitan supports this by default). MinEd uses it.
  • Support SGR 1006 styled mouse tracking(already backported into original source, of OS X El Capitan supports this by default). Recent various terminal applications use it.
  • Support "DEC Locator mode". Vim optionally uses it(:set ttymouse=dec).
  • Support xterm's "Any Event Mouse" tracking mode (private mode 1003, of OS X El Capitan supports this by default). MinEd uses it.
  • Support xterm's "Focus Reporting Mode" (private mode 1004, of OS X El Capitan supports this by default). Used by MinEd.
  • Support xterm's "Title stacking" feature. Used by tmux, MinEd.
  • Support xterm's "tcap-query" feature. Vim uses it. You no longer need not set $TERM to 'xterm-256color' to use xterm's 256 color extension in vim.
  • Support xterm's palette operation sequences: OSC 4/104. This features complement missing terminfo capabilities 'ccc' and 'initc'. It is rude of to declare 'xterm-256color' although it does not have these capabilities. MinEd uses this feature.
  • Support xterm's foreground text color operation sequences: OSC 10/110. Used by MinEd.
  • Support xterm's background text color operation sequences: OSC 11/111. Used by Emacs, MinEd, Vim.
  • Support xterm's cursor color operation sequences: OSC 12/112. tmux uses it at startup time.
  • Support "PASTE64": OSC 52 clipboard accsess(get access/set access). tmux uses it by default for accessing to clipboard. Some terminal emulators such as iTerm2 also have this feature(set access only). But they have some problems caused by buffer size restriction. The OSC 52 implementation of MouseTerm-Plus does not have buffer size restriction, just like XTerm.
  • Report original DA1 response ("\033[?1;22;29c").
  • Report original DA2 response ("\033[>19796;10000;2c").
  • Eliminate ragel build dependency.
  • Parse control sequences with DEC VT/ECMA-48 compliant canonical parser.
  • Handle "multiple-parameterized" control sequences(e.g. "\e[?1000;1006h") correctly (The original mouseterm doesn't).
  • Ignore unhandled DCS/APC/PM/SOS control string, for compliance with ECMA-48.
  • Localization support of menu resource (French/Japanese).
  • Add extended private mode 8810: "Emoji width fix".
  • Support VT's DECSCUSR sequence.


Thanks to Brodie Rao(original developper) and contributors Tom Feist, Scott Kroll, and Enrico Ghirardi. Benoit Chesneau reported some bugs to MouseTerm-Plus.

Frequently Asked Questions

What programs can I use the mouse in?

This varies widely and depends on the specific program. less, Emacs, and Vim are good places to test out mouse reporting.

How do I disable mouse reporting temporarily?

Use "Send Mouse Events" in the Shell menu.

How do I configure mouse reporting on a profile basis?

In the preferences dialog under Settings, you can configure terminal profiles. Select the profile you want to configure, go to the Keyboard section, and click the "Mouse..." button to change what mouse buttons are reported to programs in the terminal.

How do I enable mouse reporting in Vim?

To enable the mouse for all modes add the following to your ~/.vimrc file:

if has("mouse")
    set mouse=a

Run :help mouse for more information and other possible values.

What about enabling it in Emacs?

By default MouseTerm will use simulated mouse wheel scrolling in Emacs. To enable terminal mouse support, add this to your ~/.emacs file:

(unless window-system
  (xterm-mouse-mode 1)
  (global-set-key [mouse-4] '(lambda ()
                               (scroll-down 1)))
  (global-set-key [mouse-5] '(lambda ()
                               (scroll-up 1))))


Download the development repository using Git:

git clone git://

Run make to compile the plugin, and make install to install it into your home directory's SIMBL plugins folder.

Visit GitHub if you'd like to fork the project, watch for new changes, or report issues.

JRSwizzle and some mouse reporting code from iTerm are used in MouseTerm.