Gumshoe is both a program and an architecture designed to allow access to multiple file sharing services (such as Napster and Gnutella) via a unified interface. Each service is implemented as a shared library which is dynamically loaded by the core program at run time. Any number of services can be loaded and used at the same time.

Gumshoe's home page on sourceforge is, unsurprisingly, There is also a Project page. You should go there to find developer info and the latest versions.

Documenation is somewhat lacking at present. From inside the program, you can type "help" for a list of commands. For a basic search, you do something like the following. Stuff you type is in bold.

Gumshoe>search favorite band
Hit 0: <> size: 1234567: Favorite Band - Favorite Song.mp3
[Hopefully many more hits displayed]
Gumshoe>download 0
Downloading Favorite Band - Favorite Song.mp3 using service xyz from

Other useful commands are:

  • hits Redisplay all current hits
  • fhits Redisplay hits, filtered by original search string (filters out gnutella hits that don't match, for example)
  • fhits [filter] Filter hits using [filter] as a filter string.
  • connections Show the status of all current service connections (not including file transfers)
  • services Show all loaded services
  • enable n
  • disable n Enable or disable service n (n is the number given by the services command
  • help Show a list of all commands. Probably a good idea to try this with any new version, as I probably won't update any other list religiously, but the commands are self-documenting, so the online help is always up to date.
  • All commands can be abbreviated. The first match found for an abbreviation is the command used (e.g. "s" will match "search" before "services", because search is first in the internal list.)

    You can edit various configuration options in the file ~/.gumshoe/config, which is automatically created the first time you run the program (and saved by the program every time you run it as well. Eventually this stuff will be configurable inside the program.) See the file README in the top directory for directions on some things you probably want to change the after first time you run it.


    File sharing is cool. Having to deal with lots of different, often poorly designed, interfaces isn't. While Gumshoe doesn't have much of an interface yet, my aim is to give it the best features found in the interfaces of any and all service-specific clients. When "complete" you will be able to transparently search any service you can think of and instantly know how to manipulate them all, because the interaces will be exactly the same.

    Before this can happen, however, I want a rock solid core. Another thing that's bugged me about many open source (And otherwise) clients for these kinds of services is a lack of stability. Robustness is one of my primary goals. I want to be able to leave this program running for weeks at a time without crashing. I think I'm doing a pretty good job so far, but there are still a lot of basic features left to be implemented, and it is already a fairly complex system.

    Once the core and all major features are implemented for at least two big services (Napster and Gnutella at the moment - though I had a *complete* Scour service implemented before they took Scour down! I'll resurrect it if Scour itself is brought back from the dead.) I'll start work on a GUI. I like command line programs too, but in this instance I would much prefere a GUI. There's simply too much information being presented to make a line oriented console interface practical for the long run. If you'd like to do a curses interface, feel free to get in touch. I am not planning one, but it could be useful. I do see a web interface as a practical solution (E.G. implement a small web server as part of the program that presents tables and forms to access all the services provided). That might even happen before the GUI version, it depends how I feel when the time comes.

    The program core and all plugins are released under the LGPL. You are able, maybe even encouraged, to write external programs that link with the core system to extend and enhance it's functionality. You must still release any modifications to the core and plugins in source form as well as binary, but your own added code can use any license you see fit. I believe you should use the LGPL or GPL too, but I am not forcing you to. I also believe if you come up with any good extensions and make them closed source, I'll add them to my own open source version just to annoy you as much as you will have annoyed me :-)

    Finally, this is a HOBBY. I'm not making any money from this, and I'm never going to. I'm working on it in my spare time. If someone else finds it useful (and I hope people do), that's great! But first and foremost, I'm doing it because I think it's fun. If it ever stops being fun, I will stop working on it. Being LGPL'ed means that if that ever happens, everything is there for anyone else to work on, forever.


    This section will contain a more detailed discussion of the technologies involved someday. For now, there are several things I'll mention:
  • Written entirely in C++. There is not currently any well defined way to implement services in any other language. I want to fix that, but it's not a priority. There are two options as I see it: 1) Write a wrapper plugin that provides a C++ interface to the core and calls out to whatever language you want. 2) Redefine the interface using COM or CORBA or something similar. This is more elegant, for people using other languages, but more annoying for me, so I prefer the first option.
  • Multi-threaded. This is a multi-threaded program. This adds complexity, but avoids long pauses due to expensive operations that some services need to implement. This was prompted by an earlier single-threaded version in which my scour plugin needed to spend several seconds setting up shared files, during which time everything else stopped. It was easy to see that things could have become unusable with enough services going. So I moved to multiple threads. The good news is that from any plugin's point of view there is only one thread. Every call into a plugin's space is made from the same thread for the lifetime of the plugin. So inside a plugin you can ignore the multi-threadedness of the system. This makes it much easier to add new services. You are still free to implement multiple threads inside a plugin should you feel the need, but you are not required to worry about it otherwise.
  • Shared libraries. Plugins are implemented as shared libraries and opened using dlopen/dlsym. This will translate fairly simply to DLLs under Windows whenever I get around to porting it. But Other Unixes have their own ways of dealing with this. If you have a system with dlopen, then hopefully libtool will take care of all the compilation/linkage oddities for you. If you have any trouble with this aspect of the system, and are able to fix it, please send me the patches and I'll include them. I don't have access to any Unix systems other than Linux. So I can't fix it for you.
  • This project is hosted at SourceForge
    Joe Rumsey
    Last modified: Sun Jan 7 01:00:53 PST 2001