toki

A deep work slackbot using Express to manage requests and serve webpages

Star Fork Watch Issue Download
4 months after

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

Focus sessions

Focus sessions
  • /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)

View your team's pulse

Team Pulse
  • 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

Send appropriate notifications

Collaborate Now
  • 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

Daily Reflection

Daily Reflection
  • 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.

Directory Structure

build/
├── app/                                  // Web server
│   ├── api/                                  // RESTful API endpoints
│   ├── migrations/                           // Sequelize DB migrations
│   ├── models/                               // Sequelize Models
│   ├── router/                               // Express routes
│   ├── cron.js/                              // Cron job functions
├── bot/                                  // Slackbot
│   ├── actions/                              // Bot initiates conversation
│   ├── controllers/                          // Botkit controllers to handle Slack events and conversations
│   ├── lib/                                  // Slackbot helpers
│   ├── middleware/                           // Botkit middleware functions
├── public/                               // Static assets
├── server.js/                            // App starting point

Notes:

Getting Started

First, fork the repository and install node dependencies by navigating to the root of your local repository and running npm install.

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:

  1. Create your two slack apps (one for development and one for production)
  2. 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
  5. 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
  6. 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:[email protected]:5432/dbname

Modules

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 .env file

Development

As mentioned above, Toki comes with a production bot and a development bot by default. You can name your development bot whatever you want. For reference, our production bot is named toki and our development bot is named dev_toki.

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.

Running on Production

For production, Toki uses Digital Ocean and pm2, a production process manager for Node.js applications.

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. Specify NODE_ENV=production on 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

Product Roadmap

Our ideas for the product roadmap are held in our public Trello board. We'd love to hear suggestions, and work together towards a better future! You can add comments directly in Trello.

Authors

Kevin Suh (@kevinsuh34) is the primary developer for Toki. Additional development from Chip Koziara (@chipkoziara). For inquiries, reach out at [email protected]. For issues related specifically to Toki's codebase, please post on our issues page.

Related Repositories

sniffjoke

sniffjoke

a client-only layer of protection from the wiretap/sniff/IDS analysis ...

spain-map

spain-map

Mapa vectorial de España interactivo creado a partir de un mapa SVG y la librerí ...

kohana-notice

kohana-notice

Simple and easy to use class for displaying notification messages to the user ...

visual-tokipona

visual-tokipona

Toki Pona Visual Dictionary with English, Italian and Russian translation in pic ...


Top Contributors

kevinsuh chipkoziara