TBNL: Rule your Android, as the Root, fully programmable, in Clojure
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Table of Contents generated with DocToc

TBNL: Rule your Android, as the Root, fully programmable, in Clojure

Copyright © Wei Peng

The tag line above says it all.

If you are a hacker, who wants to own your rooted Android 4.3/SDK18+ devices in something nicer than Android's native tongue (i.e., Java) or the command-line power tools (e.g., am and pm), say, Clojure...

This is my gift to you.

TBNL (To Be Named Later) is a pun on the framework's open & exploratory nature, inspired by Edi Weitz's TBNL.

see it in action

Video demos.

try it

First, make sure to satisfy the build/runtime dependencies.

You may first want to try the Figurehead Android app in Google Play Store on your rooted "SDK 18/Android 4.3"+ smartphones/tablets/emulators. For emulator, Genymotion is recommended.

To try out the full TBNL, you have 2 options:

In both case, ensure that:

  • Have a sole (in the sense that adb can unambiguously find it) Android device/emulator with Android SDK 18 running.

Then, you can run the tools.

All tested on Arch Linux.

annotated source in Marginalia

The ultimate truth lies in the code.

This is probably what you are looking for.

  • figurehead: Clojure REPL on your rooted Android device plus more.
  • messenger: Unix-style command-line interface to your Figurehead REPL.

The other components.

  • core: the shared underlying framework.
  • mastermind: a single central server that brokers figureheads and C&Cs communication (and more).
  • C&C: C&C controls figurehead through mastermind.

See also the project Wiki.


I am no legal expert, and I am confused by the plethora of Open Source licenses, so let me explain what I have in mind in plain words.

You are free to use and adapt this work in any way you want, with 2 overall principles:

  • Do not hold me or any contributors liable for your actions of using this software.
  • Please do the courtesy of fair acknowledgments if you derive works from it.

Please consider:

  • Improving the core framework and contributing plug-ins;
  • Contributing constructive criticisms: What is working, and what could be improved;
  • Reporting issues and sending in patches;
  • Staring this project on GitHub;
  • Citing this work if you publish a paper using it;
  • Letting me know if you use or extend it: I'd love to hear about your work and your use cases.


  • Dr. Feng Li and Dr. Xukai Zou, who advise and support my research into Android system security that begets TBNL.
  • The Clojure community.
  • In choosing an icon for the Figurehead app, I come across the wonderful The Digital Michelangelo Project. I take the liberty of using a meshed(figure)head of David as the icon of Figurehead, in homage of their work. I hope the authors would not mind.