Toki: deep work for collaborative teams
Toki is a Slack bot that helps individuals focus at work, track their productivity and stay in sync with their team. Its goal is to empower deep work for teams, through the benefits of Slack (collaboration, transparency and fun).
Toki enables you to /focus on [task] for [time]. This command turns on your Do Not Disturb (DND) mode in Slack and shares what you're working on to your team. You can see what teammates are focused on by checking /pulse @user. Toki will also store these focused sessions to provide daily reflections of how you spend your time. Think of /focus as an upgrade to /dnd that makes deep work more collaborative, transparent and informative.
Toki is written in Javascript and uses the excellent Botkit and Wit libraries. The Botkit + Express integration is inspired from this tutorial. If you are looking for a foundation to build your own Slack bot app with Botkit and Express, check out that tutorial.
- Main Features
- Directory Structure
- Getting Started
- Modules
- Development
- Running on Production
- Product Roadmap
- Authors
* `/focus [task] for [time]`
* Turns on your DND in Slack while in "focus" mode
* Shares what you are working on to your team
* Toki stores this information for daily reflection
* You can end your session at any point, which turns off your DND (via interactive button, or `/end`)
* Toki will dynamically update its channels whenever one of the channel members enters a focus session
* This allows you to create information channels (i.e. `#pulse-backend`) to get a snapshot of what teams are focused on
* See what an individual is up to with `/pulse @user`
* You are able to send notifications through each teammate's `Collaborate Now` button, through which Toki temporarily turns off the user's DND and sends a ping to start a conversation
* This helps segment notifications to be ones that preserve an individual's context or is actually urgent
* You are also able to `Collaborate Now` when you see a specific individual's `/pulse @user`
* Toki provides a daily cadence of how you spent your focused time
* This helps you build a habit of being intentional with your time, and get pictures of what you got done each day
Note: Toki has a web app interface in its roadmap. We plan this to be a React + Redux frontend hosted on a separate server that speaks to the API end points on this server in /app/api.
Notes:
- There are two main sub-directores:
appandbotappis for our Express web server, including routes, models that link up to our DB tables, and our API callsbotholds the functionality for Toki's existence in slackcontrollersare used to respond to user events, and engage them in conversationactionsare when Toki proactively reaches out
- Since Toki uses a compiler for both ES6 (Babel) and SCSS (node-sass), we have one directory for our source code
/src, and one directory for our deployment/build.- This means actual development is done in
/srcdirectory, which Babel uses to compile into the/builddirectory for deployment - Code that does need to be compiled is held at the root-level of our project. Currently, this only includes config files and our
/viewsdirectory- Our static assets are held in
/build/public
- Our static assets are held in
- This means actual development is done in
cron.jsis used for our focus sessions and daily reflections. It holds various functions that get run every 5 seconds (configured inserver.js)server.jsis where our Express server is created, and where Toki's installed bots are turned on to listen via Slack RTM
By default, Toki comes with configuration for a development bot and a production bot so that you can continue developing your bot and test new functionalities while it is live and on others' teams. This means you will have to create two separate Slack apps and do basic configuration for each. Here are the steps:
- Create your two slack apps (one for development and one for production)
- Set up your environment variables. You can modify and rename the provided .env-example file:
SLACK_ID=your.productionSlackId
SLACK_SECRET=yourProductionSlackSecret
SLACK_REDIRECT=https://yourproduction.site
DEV_SLACK_ID=your.developmentSlackId
DEV_SLACK_SECRET=yourDevelopmentSlackSecret
DEV_SLACK_REDIRECT=http://localhost:8080/
VERIFICATION_TOKEN=yourVerificationToken
WIT_TOKEN=yourWitToken
HTTP_PORT=8080
Make sure to put NODE_ENV=production as an environment variable on your production server. This allows Toki to know whether to start up the production bot or the development bot
3. Get your apps' verification tokens for Slash commands
4. Create a Wit.api app and set your wit token
- Wit token is located in settings of your Wit app under
Server Access Token
- Decide deployment strategy
- We used Digital Ocean for deployment
- Configure environment variables while SSH'd into the server. This is done by creating this same .env file on the server, but you must also configure DB_HOST in shell to connect to your prodution postgres DB
- For Heroku, you can use the Heroku dashboard to add these environment variables
- We use Postgres for storage with the Sequelize ORM
- Familiarize yourself with Sequelize and configure accordingly in
config.json - You will notice that for "production", we just look at DB_HOST. This is the connection uri to your production DB. An example format is
postgresql://user:password@example.com:5432/dbname
Toki is built on top of the Botkit framework and uses the following modules:
- cron: Allows you to run a cronjob
- botkit-middleware-witai: Forked version of Botkit's official middleware integration of Wit.ai
- ejs: Write embedded javascript templates for your views
- lodash: A powerful javascript utility library for arrays, objects, numbers, and more
- moment-timezone: For dealing with dates and timezones for your Slack users
- sequelize: Promise-based Node ORM, which we use for Postgres
- nlp_compromise: A javascript utility library for natural language
- babel: Compiler that transforms ES6 into javascript that can run in any browser
- node-sass: Compilers for .scss files to css
- dotenv: Allows you to load environment variables from a
.envfile
Actual development is done inside the /src directory, and its changes are compiled into the /build directory via babel and node-sass for deployment. This allows us to use ES6 and SCSS while developing.
Toki comes with the scripts npm run watch-css and npm run watch-babel to run in the background and compile a file from /src into its mirror location in /build each time you save a change.
Notes:
- Toki comes with a production bot and development bot by default
- Development environment triggers dev_toki and local postgres DB
- Production environment is identified via environment variable
NODE_ENV=production. Otherwise, it's assumed you are in development. SpecifyNODE_ENV=productionon your prodution server
- This project uses a forked version of botkit-middleware-witai for custom configuration
- Production server holds some env variables through shell, and some through .env file. DB_HOST is necessary to be updated on shell