NoshBar's Dumping Ground

(Helper)MonkeyBot Python


(Helper)MonkeyBot is a free note-taker/reminder/download-helper program with an instant-messenger interface, avoiding opening firewall ports, or having to SSH in to start a download on your home PC.

You basically use Google Talk to tell a program on your home PC to store/retrieve information for you, or to download files.

MonkeyBot is written in Python and is open source under the ZLib license, using SQLite for its database and SleekXMPP for instant messaging functionality.

(For the original -and deprecated- C++ version, please see here)


  • Store messages with different built-in/custom categories, e.g.,
    todo:Kill everyone
  • Remotely set up downloads to occur at specified times, e.g.,
  • Set up reminders to be e-mailed and IM'd about, e.g.,
    remind@2 Jul@13h00:Satan's birthday
  • Show and delete existing messages
  • Do full text searches through messages, optionally showing only URLs from messages that return a match, e.g.,
  • Uses the widely-supported XMPP protocol (so Google Talk works like a charm)
  • No need to open an incoming port on your firewall, as the client connects out
  • Single-web-page PHP utility to view and filter messages in a browser

How to use


  • You will need a dedicated MonkeyBot chat account, so go ahead and create one e.g.,
  • Add the new account as a chat contact so that you can see the MonkeyBot account in your IM Client.
  • Download the (Helper)MonkeyBot script from here


  • Python 2.7
  • SQLite for Python with FTS4 support (OSX and Linux should be fine)
  • SleekXMPP

Starting the program:

  • Either double-click the MonkeyBot Python script, or run it from a command-line with
  • Enter the MonkeyBot username, in this case,
  • Enter the password for the MonkeyBot account
  • Enter your account address as the one to listen to (MonkeyBot will not obey anyone else)
  • Enter your secret handshake phrase. MonkeyBot will ignore anything until the magic phrase is typed.

Once that is done, you should see your GoMonkeyBotGo@gmail account come online in your chat window.
As soon as you type your magic phrase, you should see the MonkeyBot reply with a confirmation phrase, indicating it is ready for commands.

Note that the following command-line options are available:
-h show this help
-u monkeybot-username
-p monkeybot-password
-g monkeybot-owner
-k secret-handshake-phrase
-f download-folder
-s chat-server (if not
-d name-of-local-SQLite-database
-c handshake-confirm-message (if "Listening..." does not suit)

Viewing entries:

  • A PHP file called "monkeyview.php" is included to view the data in a browser.
  • A working PHP installation with PHPSqlite installed is required.
    (Ubuntu: sudo apt-get install php5 php5-sqlite)
  • To view and delete entries, you will need a web server installed. Assuming it shows pages from "/var/www/", you can put monkeyview.php and monkey.db in "/var/www/monkeybot", then browse to
  • To only view new entries, you do not need a web server installed, you can simply change to the folder containing monkey.db and run:
    php monkeyview.php > /tmp/out.html && firefox /tmp/out.html