Guide · Open source

How to use Hubot: create, customize and run a chat bot

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Hubot is an open-source JavaScript framework for building chat bots, modeled after GitHub's original Campfire bot. It is distributed as an npm library, so you create your own bot, extend it with scripts and connect it to a chat service through an adapter. This guide shows you how to create an instance, add scripts, and use the command system with permissions and confirmations.

Hubothubotio/hubot · ★ 16.8k · MIT Install options & downloads

Quick start

1Install Node.js. Make sure Node.js is installed, since Hubot is distributed as an npm library and the install step uses npx.
2Create your instance. Run npx hubot --create myhubot --adapter with the adapter for your chat service. The README gives Slack, Discord, MS Teams and IRC options.
3Review the example script. Open scripts/example.mjs in your new myhubot directory to see how a script is written.
4Add your own scripts. Create more script files in the scripts folder, exporting a function that receives the robot object.
5Register a command. Call robot.commands.register with an id, description, arguments and handler. Declare sideEffects if the action changes anything outside the bot.
6Set permissions. Add room-based permissions to restrict where a command runs. Add role-based permissions and a permissionProvider if you need role checks.
7Test with help. Mention the bot with help to confirm your commands are listed, and use help search to check aliases.

What you need before you start

Hubot is a framework you run yourself. The README's install step relies on npx, so you need Node.js installed on your machine.

You also need a chat service that has a Hubot adapter. The README lists Slack, Discord, MS Teams and IRC as examples.

Node.js (required)
A chat service with a Hubot adapter, such as Slack, Discord, MS Teams or IRC

Create your own Hubot instance

Run npx with the hubot package and a name for your bot. This creates a directory with that name in the current working directory. The README gives one command per supported adapter; the example below uses Slack.

After creation, the README suggests reviewing scripts/example.mjs and adding more scripts in the scripts folder.

npx hubot --create myhubot --adapter @hubot-friends/hubot-slack

Add scripts to extend your bot

Hubot is extended with scripts. Put your script files in the scripts folder of your instance. The README points to scripts/example.mjs as a starting point.

The command system uses a default export that receives the robot object. You register commands on robot.commands inside that function.

export default (robot) => {
	robot.commands.register({
		id: 'tickets.create',
		description: 'Create a ticket',
		aliases: ['ticket new', 'new ticket'],
		args: {
			title: { type: 'string', required: true },
			priority: { type: 'enum', values: ['low', 'medium', 'high'], default: 'medium' }
		},
		sideEffects: ['creates external ticket'],
		handler: async (ctx) => {
			return `Created ticket: ${ctx.args.title}`
		}
	})
}

Run commands and confirm actions with side effects

You address the bot by mentioning it and then give the command ID and arguments. The README shows two argument styles: flags with dashes, and key:value pairs.

Commands that declare side effects require confirmation before they run. The user replies with yes, no or cancel. Aliases are for discovery and search only; they do not execute commands.

Flag style: @hubot tickets.create --title "VPN down" --priority high
Key-value style: @hubot tickets.create title:"VPN down" priority:high
Confirm with @hubot yes, decline with @hubot no, or stop with @hubot cancel

@hubot tickets.create --title "VPN down" --priority high
@hubot yes
@hubot no
@hubot cancel

Control who can run commands

Room-based permissions restrict a command to specific chat rooms, and they are always enforced. Role-based permissions restrict a command to users with certain roles, but they need a permissionProvider. Without one, role-based permissions are ignored and commands are allowed by default.

To check roles, you pass a permissionProvider with a hasRole function when creating a CommandBus.

Room check: users in other rooms get "Permission denied: command not allowed in this room"
Role check: requires a permissionProvider; otherwise it is ignored

robot.commands.register({
	id: 'deploy.production',
	description: 'Deploy to production',
	permissions: {
		roles: ['admin', 'devops']
	},
	handler: async (ctx) => {
		return 'Deploying...'
	}
})

Use built-in help and search

Hubot registers a help command automatically. You can list all commands, filter them by prefix, or search by keyword, alias, description or example. The robot.commands.search method returns matches with a score and the field that matched.

@hubot help                          # List all commands
@hubot help tickets                  # Filter commands by prefix
@hubot help search "create ticket"   # Search by keyword, alias, description, or example

Configure the command bus

When you create a CommandBus instance, you can set several options. Event logging is disabled by default, so you must turn it on if you want a record of command events.

prefix: command prefix (default: empty)
proposalTTL: timeout for pending confirmations in milliseconds (default: 300000, which is 5 minutes)
logPath: path to the NDJSON event log (default: .data/commands-events.ndjson)
disableLogging: disables event logging to disk (default: true)
permissionProvider: custom permission checking handler (optional)

What people use it for

Create tickets in an external system from a chat room, with a confirmation step before the action runs
Restrict an admin action to a specific chat room, such as #admin or #ops
Run deployment commands only for users with an admin or devops role, using a custom permissionProvider
Expose internal workflow commands in Slack, Discord, MS Teams or IRC through an existing adapter

Frequently asked questions

Is Hubot free to use?

Hubot is released under the MIT licence, as stated in the README. The README points to the LICENSE file for the full rights and limitations. Check that file for the exact terms.

What do I need to install Hubot?

The README lists Node.js as the prerequisite. You create a bot instance with npx hubot --create and pick an adapter for your chat service.

Can I use Hubot with Slack or Discord?

Yes. The README gives create commands for the Slack, Discord, MS Teams and IRC adapters, and the Slack example uses @hubot-friends/hubot-slack.

Does Hubot have AI features built in?

The README does not describe built-in AI features. Hubot's documented features are scripts, adapters, the command system, permissions and built-in help.

How is Hubot different from Botkit, Probot or Errbot?

This guide does not compare them in detail. Hubot is a self-hosted JavaScript framework connected to chat services through adapters. Botkit, Probot and Errbot are alternatives you can evaluate against your chat service and language needs.

Why does my command ask for confirmation?

Commands that declare side effects require confirmation before they run. Reply with yes to proceed, no to decline, or cancel to stop.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Hubot suits developers who want a self-hosted, JavaScript-customizable chat bot connected through an adapter for their chat service. It is a poor fit if you want a ready-made bot with no coding, a hosted chatbot service, or an AI assistant out of the box.

Install options & downloads