Skip to content
This repository has been archived by the owner on May 15, 2021. It is now read-only.


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

frame-workflow.el: Per-Frame Workflow on Emacs

frame-workflow.el lets you define and organize per-frame workflow for Emacs. This is yet another workspace solution such as eyebrowse, perspective, and framegroups. It is frame-oriented and supports frame-specific states and actions. It is also designed to integrate with frame-purpose.el which lets you focus on particular things inside a frame.

For background on frame-workflow, see Inspirations in the Wiki.


This package requires Emacs 25.1.

The package is not available on MELPA at present, but it may be added in the future. Clone the repository and add the directory to load-path. Below is an example of MELPA-style recipe:

(frame-workflow :fetcher github
                :repo "akirak/frame-workflow"
                :branch "eieio")


(require 'frame-workflow)
(frame-workflow-mode 1)

;; If you use helm-frame-workflow
(autoload 'helm-frame-workflow "helm-frame-workflow")
;; Bind s-B on EXWM
(exwm-input-set-key (kbd "s-B") 'helm-frame-workflow)

Subjects (or workspaces)

A subject is a type of frame in frame-workflow. You can create one frame or multiple frames for a subject.

To define a subject, use frame-workflow-define-subject:

(frame-workflow-define-subject "emacs-lisp"
  :make-frame '(frame-purpose-make-mode-frame 'emacs-lisp-mode))

Every subject requires a name, which is a string to uniquely identify the subject.

For more examples, see a Wiki page.


Frame-workflow provides a prefix map named frame-workflow-prefix-map for commands in the package. It may be convenient to bind a key to this command:

(global-set-key "s-g" #'frame-workflow-prefix-map)

You can also define keybindings to switch to a particular subject on this prefix map, and there are two ways to do that:

  • Customize frame-workflow-prefix-subject-keys.
  • Set :key option when you define a subject.

The latter can be configured as in the following example:

(frame-workflow-define-subject "emacs-lisp"
  :key "e"

Then you can use s-g e to switch to emacs-lisp subject.

There is also a manual way. frame-workflow-switch-frame is a function that lets you switch to a frame for a given subject. You can use it to bind a key to switch to a particular workspace:

(global-set-key (kbd "s-g e")
                (lambda () (interactive) (frame-workflow-switch-frame "emacs-lisp")))

It is also a command that lets you select a subject via completing-read:

(global-set-key "s-s" 'frame-workflow-switch-frame)

Directory subjects and projectile integration

Frame-workflow provides a set of utilities to work with directory subjects. frame-workflow-switch-directory-frame function defines a subject for a directory and switches to a frame for the subject.

If you are using projectile package, it may be a good idea to use this function as projectile-switch-project-action:

(setq projectile-switch-project-action #'frame-workflow-switch-directory-frame)

Directory subjects integrate with frame-purpose.el. By default, frame-workflow uses frame-purpose to create a frame for a directory subject, so the frame becomes a purpose-specific frame for the directory. This means the buffer list on the frame is limited to buffers in the directory. If you want to turn off this feature, set frame-workflow-use-frame-purpose-for-directory to nil.

By default, if magit is installed, a new frame for a directory subject runs magit-status. This can be changed to another function by customizing frame-workflow-directory-frame-action. If it is nil, directory subjects do nothing on frame creation.



helm-frame-workflow in helm-frame-workflow.el is a command which lets you switch to a frame or create a new frame for a subject. It provides access to all the basic functionalities of frame-workflow.

Switching the context

You can use the following commands to switch the context:

  • frame-workflow-make-frame, which creates a new frame of a given subject.
  • frame-workflow-select-frame, which selects an existing frame of a given subject.
  • frame-workflow-switch-frame, which selects an existing frame of a given subject if there is one. Otherwise, it creates a new frame.
Select a frameCreate a frame

There is also frame-workflow-switch-directory-frame, which is like frame-workflow-switch-frame but switches to a frame for a directory subject.


Any comments and patches on this package are welcome. Create a ticket or a pull request on GitHub.


GPL v3