Skip to content
Simple process manager written in Go-lang
Go Makefile
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
cmd Updated binary to latest version Jun 26, 2019
service Added makefile Jun 14, 2019
testdata Added a few Cmd tests Jun 19, 2019
.gitignore Implemented clone child. Some code cleanup. Jul 24, 2018
.travis.yml Updated go mods Jun 14, 2019 Created changelog Jun 26, 2019
LICENSE Initial commit Jul 24, 2018
Makefile Renamed the repo from overseer.go to overseer Jun 16, 2019
backoff_test.go Some code cleanup and a new test Jul 20, 2019
cmd_test.go Fixed Buffered:true option Jun 26, 2019
go.mod Added a readme for the app Jun 16, 2019
go.sum Added a readme for the app Jun 16, 2019
logo.png Added logo Jul 25, 2018
manager.go Some code cleanup and a new test Jul 20, 2019
state.go Code polishing Jun 26, 2019

Overseer logo


Project name Build status Coverage report Go Report Card

Simple process manager library.

  • Note: The master branch is the development branch. To make sure you use the correct version, use the repository tags.

At the heart of this library is the os/exec.Cmd from Go-lang and the first wrapper for that is the Cmd struct.
The Overseer struct can supervise one or more Cmds running at the same time.
You can safely run multiple Overseer instances at the same time.

It's recommended to use Overseer, instead of Cmd directly.
If you use Cmd directly, keep in mind that it is one use only. After starting a instance, it cannot be started again. However, you can Clone your instance and start the clone.
The Supervise method from the Overseer does all of that for you.

There are 3 states in the normal lifecycle of a proc: starting, running, finished.
If the process is killed prematurely, the states are: starting, running, interrupted.
If the process cannot start, the states are: starting, fatal.

The useful methods are:

  • NewOverseer() - Returns a new instance of a process manager.
  • Add(id string, exec string, args ...interface{}) - Register a proc, without starting it. The id must be unique. The name of the executable is exec. The args of the executable are args.
  • Remove(id string) - Unregister a proc, only if it's not running. The id must be unique.
  • SuperviseAll() - This is the main function. Supervise all processes and block until they finish. This includes killing all the processes when the main program exits. The status of the running processes can be watched live with the Watch() function.
  • Supervise(id string) - Supervise one registered process and block until it finishes. This includes checking if the process was killed from the outside, delaying the start and restarting in case of failure (failure means the program has an exit code != 0 or it ran with errors).
  • Watch(outputChan chan *ProcessJSON) - Subscribe to all state changes via the provided output channel. The channel will receive status changes for all the added procs, but you can easily identify the one your are interested in from the ID, Group, etc. Note that for each proc you will receive only 2 or 3 messages that represent all the possible states (eg: starting, running, finished).
  • Unwatch(outputChan chan *ProcessJSON) - Un-subscribe from the state changes, by un-registering the channel.
  • Stop(id string) - Stops the process by sending its process group a SIGTERM signal.
  • Signal(id string, sig syscall.Signal) - Sends an OS signal to the process group.
  • StopAll() - Cycles and stops all processes by sending SIGTERM.


  • real-time status
  • real-time stdout and stderr
  • complete and consolidated return
  • easy to track process state
  • proper process termination on program exit
  • portable command line binary for managing procs
  • heavily tested, very good test coverage
  • no race conditions

For examples of usage, please check the Examples folder, the manager tests, or the command line app.

Similar libraries

Icon is made by Freepik from and licensed by CC 3.0 BY.


MIT © Cristi Constantin.

You can’t perform that action at this time.