===============
AFK Slack Agent
===============
.. image:: https://img.shields.io/pypi/v/afk_slack_agent.svg
:target: https://pypi.python.org/pypi/afk_slack_agent
Signal you A.F.K. (Away From Keyboard) status on Slack, automatically.
.. contents:: Table of Contents
.. warning::
This software is for MacOS only!
Installation
============
.. code-block:: bash
pip install afk_slack_agent
What it does?
=============
This software is distributed with an agent (``afk_agent``) and a client (``afk``, optional).
The agent is designed to be run in the background and stay active until you terminate it.
Features implemented by the agent
- waits for lock screen and unlock screen events (*very buggy* feature, due to changes in behavior in *every* MacOS release 😮💨)
- connects to a Slack workspace, and change user status on lock (clean it on unlock)
- optionally: write a message on a channel on lock/unlock
Prerequisites
=============
- you have to `create a Slack application <https://api.slack.com/apps?new_app=1>`_, and install it into your workspace
- the application should have at least the following `scope <https://api.slack.com/scopes>`_: ``users.profile:write``.
optionally, you could also enable ``chat:write`` and ``reactions:write``
- to run custom AFK commands from the client, you'll need to enable the agent to control your Mac (from "Privacy and Security" system settings)
How to use
==========
Run ``afk --help`` for a list of all commands.
In brief: when the agent is running, you can run ``afk <action>`` to interact with slack.
Actions must be customized in you ``.afk`` file (see below), apart for:
- ``terminate`` - kill the agent
- ``back``- signal Slack you are BTK
Configuration
=============
The first time the agent is run, a ``~/.afk.json`` file is created.
This is the default file created:
.. code-block:: json
{
"version": 1,
"token": "",
"status_text": "I need a break",
"status_emoji": ":coffee:",
"channel": null,
"away_message": "I'm going to take a coffee break",
"back_message": "I'm back",
"delay_for_reaction_emoji": 60,
"back_emoji": "back",
"agent_emoji": "robot_face",
"agent_active_start_time": null,
"agent_active_end_time": null,
"actions": [
{
"action": "lunch",
"status_text": "Lunch break",
"status_emoji": ":spaghetti:",
"away_message": "I'm going to take the lunch break",
"back_message": "I'm back and stuffed!",
"command": "lock"
}
]
}
The most important key is ``token``, which must contain the Slack User OAuth Token.
.. image:: https://raw.githubusercontent.com/keul/afk_slack_agent/main/docs/slack-key.png
:alt: Slack configuration, where to grab your token
Other settings
--------------
``status_text``
Status to be set when locking the screen
``status_emoji``
emoji to be set when locking the screen
``channel``
use this only if you want to write messages on a channel when going AFK and be back.
Put the channel id there. You can find it by right-clicking on the channel and clicking "View channel details".
It will be at the very bottom of the popup.
``away_message``
message to send when going AFK
``back_message``
message to send when back to keyboard
``delay_for_reaction_emoji``
in case you will be back before this amount of seconds, do not send a back message, but just react to your away message using a reaction emoji.
This will reduce noise in case of quick lock/unlock screen
``back_emoji``
emoji to be used for quick back reaction
``agent_emoji``
automatically adds this emoji at the end of every message sent or slack status set.
This helps others to know there's a bot that is acting for you.
``delay_after_screen_lock``
before starting interacting with Slack, wait this amount of seconds.
This will delay reactions to your lock screen status a while, so no Slack commands will be run if you unlock the screen before this time.
As example: you are reading a document and the screen locks for inactivity, but you are not AFK.
``agent_active_start_time`` and ``agent_active_end_time``
time range inside which agent is effectively working.
When provided (in the format as ``HH:MM``), the agent will only effectively works when current time is inside this (potentially open) time range.
This can be used to disable the agent when using your computer outside working hours.
This is not applied to explicit actions (``afk <command>``).
Custom actions
~~~~~~~~~~~~~~
The JSON configuration can contain an ``actions`` key, with an array of *custom actions*.
Custom actions can be sent to the agent using the client component:
.. code-block:: bash
afk lunch
A custom action is a way to perform something more than the standard lock/unlock monitor.
See the ``afk`` command line help for more.
An action interact with Slack in the same way the agent does, and inherit the same configuration, but it can override some of them like: ``status_text``, ``status_emoji``, ``away_message`` and ``back_message``.
Every of these settings can be ``null`` to explicitly inherit from the global settings.
``back_message`` can also be ``false``: this disables the back message for the action even if the global setting has a value.
Finally, a custom action can perform one of the following commands:
``lock``
Lock the screen manually
``sleep``
Put you computer to sleep
If no ``command`` is defined or it's ``null``, the interaction with Slack will be run immediately (same as providing the ``--no-command`` option at the command line).
Why?
====
To understand motivation about this tool, read `why I needed to join my lock screen activities with Slack <https://blog.keul.it/automate-slack-afk-status/>`_.
Raw data
{
"_id": null,
"home_page": "https://github.com/keul/afk_slack_agent",
"name": "afk-slack-agent",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "afk_slack_agent",
"author": "Luca Fabbri",
"author_email": "lucafbb@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/cb/13/b57404cc3f9319ec4aae5530b8acec77100792cd1a894dcd77adfdbf25ad/afk_slack_agent-0.3.0.tar.gz",
"platform": null,
"description": "===============\nAFK Slack Agent\n===============\n\n\n.. image:: https://img.shields.io/pypi/v/afk_slack_agent.svg\n :target: https://pypi.python.org/pypi/afk_slack_agent\n\nSignal you A.F.K. (Away From Keyboard) status on Slack, automatically.\n\n.. contents:: Table of Contents\n\n.. warning::\n This software is for MacOS only!\n\nInstallation\n============\n\n.. code-block:: bash\n \n pip install afk_slack_agent\n\nWhat it does?\n=============\n\nThis software is distributed with an agent (``afk_agent``) and a client (``afk``, optional).\n\nThe agent is designed to be run in the background and stay active until you terminate it.\n\nFeatures implemented by the agent\n\n- waits for lock screen and unlock screen events (*very buggy* feature, due to changes in behavior in *every* MacOS release \ud83d\ude2e\u200d\ud83d\udca8)\n- connects to a Slack workspace, and change user status on lock (clean it on unlock)\n- optionally: write a message on a channel on lock/unlock\n\nPrerequisites\n=============\n\n- you have to `create a Slack application <https://api.slack.com/apps?new_app=1>`_, and install it into your workspace\n - the application should have at least the following `scope <https://api.slack.com/scopes>`_: ``users.profile:write``.\n \n optionally, you could also enable ``chat:write`` and ``reactions:write``\n- to run custom AFK commands from the client, you'll need to enable the agent to control your Mac (from \"Privacy and Security\" system settings)\n\nHow to use\n==========\n\nRun ``afk --help`` for a list of all commands.\n\nIn brief: when the agent is running, you can run ``afk <action>`` to interact with slack.\n\nActions must be customized in you ``.afk`` file (see below), apart for:\n\n- ``terminate`` - kill the agent\n- ``back``- signal Slack you are BTK\n\nConfiguration\n=============\n\nThe first time the agent is run, a ``~/.afk.json`` file is created.\n\nThis is the default file created:\n\n.. code-block:: json\n \n {\n \"version\": 1,\n \"token\": \"\",\n \"status_text\": \"I need a break\",\n \"status_emoji\": \":coffee:\",\n \"channel\": null,\n \"away_message\": \"I'm going to take a coffee break\",\n \"back_message\": \"I'm back\",\n \"delay_for_reaction_emoji\": 60,\n \"back_emoji\": \"back\",\n \"agent_emoji\": \"robot_face\",\n \"agent_active_start_time\": null,\n \"agent_active_end_time\": null,\n \"actions\": [\n {\n \"action\": \"lunch\",\n \"status_text\": \"Lunch break\",\n \"status_emoji\": \":spaghetti:\",\n \"away_message\": \"I'm going to take the lunch break\",\n \"back_message\": \"I'm back and stuffed!\",\n \"command\": \"lock\"\n }\n ]\n }\n\nThe most important key is ``token``, which must contain the Slack User OAuth Token.\n\n.. image:: https://raw.githubusercontent.com/keul/afk_slack_agent/main/docs/slack-key.png\n :alt: Slack configuration, where to grab your token\n\nOther settings\n--------------\n\n``status_text``\n Status to be set when locking the screen\n\n``status_emoji``\n emoji to be set when locking the screen\n\n``channel``\n use this only if you want to write messages on a channel when going AFK and be back.\n \n Put the channel id there. You can find it by right-clicking on the channel and clicking \"View channel details\".\n It will be at the very bottom of the popup.\n\n``away_message``\n message to send when going AFK\n\n``back_message``\n message to send when back to keyboard\n\n``delay_for_reaction_emoji``\n in case you will be back before this amount of seconds, do not send a back message, but just react to your away message using a reaction emoji.\n This will reduce noise in case of quick lock/unlock screen\n\n``back_emoji``\n emoji to be used for quick back reaction\n\n``agent_emoji``\n automatically adds this emoji at the end of every message sent or slack status set.\n This helps others to know there's a bot that is acting for you.\n\n``delay_after_screen_lock``\n before starting interacting with Slack, wait this amount of seconds.\n\n This will delay reactions to your lock screen status a while, so no Slack commands will be run if you unlock the screen before this time.\n As example: you are reading a document and the screen locks for inactivity, but you are not AFK.\n\n``agent_active_start_time`` and ``agent_active_end_time``\n time range inside which agent is effectively working.\n\n When provided (in the format as ``HH:MM``), the agent will only effectively works when current time is inside this (potentially open) time range.\n This can be used to disable the agent when using your computer outside working hours.\n\n This is not applied to explicit actions (``afk <command>``).\n\nCustom actions\n~~~~~~~~~~~~~~\n\nThe JSON configuration can contain an ``actions`` key, with an array of *custom actions*.\n\nCustom actions can be sent to the agent using the client component:\n\n.. code-block:: bash\n \n afk lunch\n\nA custom action is a way to perform something more than the standard lock/unlock monitor.\n\nSee the ``afk`` command line help for more.\n\nAn action interact with Slack in the same way the agent does, and inherit the same configuration, but it can override some of them like: ``status_text``, ``status_emoji``, ``away_message`` and ``back_message``.\nEvery of these settings can be ``null`` to explicitly inherit from the global settings.\n``back_message`` can also be ``false``: this disables the back message for the action even if the global setting has a value.\n\nFinally, a custom action can perform one of the following commands:\n\n``lock``\n Lock the screen manually\n\n``sleep``\n Put you computer to sleep\n\nIf no ``command`` is defined or it's ``null``, the interaction with Slack will be run immediately (same as providing the ``--no-command`` option at the command line).\n\nWhy?\n====\n\nTo understand motivation about this tool, read `why I needed to join my lock screen activities with Slack <https://blog.keul.it/automate-slack-afk-status/>`_.\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "Signal your A.F.K. status on Slack automatically",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/keul/afk_slack_agent"
},
"split_keywords": [
"afk_slack_agent"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ed384f817b3666e411ede4df5db0eaad02a3aa7231a2f592479b6c5ac7cfd34e",
"md5": "0fffe2511f75066f8ce24769c56368f8",
"sha256": "702c3afc992e160a16a8edcdbf680c2d60c9529d969d9933d62129da2a2a1340"
},
"downloads": -1,
"filename": "afk_slack_agent-0.3.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "0fffe2511f75066f8ce24769c56368f8",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.10",
"size": 12119,
"upload_time": "2024-11-15T09:59:33",
"upload_time_iso_8601": "2024-11-15T09:59:33.916655Z",
"url": "https://files.pythonhosted.org/packages/ed/38/4f817b3666e411ede4df5db0eaad02a3aa7231a2f592479b6c5ac7cfd34e/afk_slack_agent-0.3.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cb13b57404cc3f9319ec4aae5530b8acec77100792cd1a894dcd77adfdbf25ad",
"md5": "e49dee0fabcb72616987e76b197398dc",
"sha256": "9663315d7066a577a7d11b58dbce2b6f7cb8fba81e05ae28fce144892eb1809f"
},
"downloads": -1,
"filename": "afk_slack_agent-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "e49dee0fabcb72616987e76b197398dc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 54303,
"upload_time": "2024-11-15T09:59:35",
"upload_time_iso_8601": "2024-11-15T09:59:35.648683Z",
"url": "https://files.pythonhosted.org/packages/cb/13/b57404cc3f9319ec4aae5530b8acec77100792cd1a894dcd77adfdbf25ad/afk_slack_agent-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-15 09:59:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "keul",
"github_project": "afk_slack_agent",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "afk-slack-agent"
}
JSON
