Skewed Emacs is a containerized Emacs development environment with Model Context Protocol (MCP) integration, enabling AI agents to interact directly with Emacs and other Lisp REPLs for automated development workflows.
This README assumes that you have access to a system with a bash shell and docker available.
This Skewed Emacs repository houses essentially three things:
-
a ready-to-go Emacs configuration
-
a containerized emacs server with pre-configured skewed emacs user
-
a container orchestration to bring in supplemental compatible backend container services for e.g. Model Context Protocol and Knowledge Based Engineering.
-
A Sampling of Included Emacs Packages:
- Slime for Common Lisp / Swank
- Paredit-mode, Flycheck-mode, Company-mode
- Magit, Org-mode
- Doom Color Themes, theme switching functions
-
Lisply-MCP (Model Context Protocol) Backend:
- allows AI agents to drive your contained emacs.
- Defined in this repository and sideloaded from
dot-files/emacs.d/sideloaded/lisply-backend/
-
Docker Integration:
- Local container image defined in
docker/Dockerfileanddocker/build. Images are pushed to taggedgornskew/skewed-emacsversions at Dockerhub. - Docker Compose orchestration for running configured skewed-emacs with other helpful containers such as lisply-mcp for the Lisply-MCP compatible middleware.
- Local container image defined in
Skewed-emacs uses the traditional Emacs keybindings by default, which make heavy use of the Control key ("C-" in emacs parlance). For this reason, it can be convenient to bind a more ergonomic key such as CapsLock to Control, on modern keyboards. (Older keyboards had Control in the place of current CapsLock). The Skewed Emacs repository contains instructions for mapping CapsLock to Control (with or without WSL) using a free program called SharpKeys.
If you enjoy the traditional emacs keychords and want more of them in your life, you can replicate those across most Windows programs using the free AutoHotkey program, for which we bundle a config, also described in the instructions.
This is the easiest way to get everything started.
The steps below assume that you have access to a system with a bash shell and docker available.
- Make a
~/projects/directory if you don't already have one:
cd
mkdir -p projects/
cd projects/
- Clone this repo into
~/projects/:
git clone https://github.com/gornskew/skewed-emacs
cd skewed-emacs
- Start the default container orchestra:
./compose-dev up
This will pull and starts four containers:
- skewed-emacs: Emacs with Benefits
- gendl-ccl: Gendl system on Clozure CL
- gendl-sbcl: Gendl system on Steel Bank CL
- lisply-mcp: Node.js environment MCP & Claude
Now you can use the eskew or egskew aliases to launch a terminal-
or graphical-based emacs client. These aliases are defined in the
dot-files/bash_profile, so if you did not run the ~/.setup on your
host machine, you can quickly define thes aliases for yourself with
cd ~/projects/skewed-emacs/
source dot-files/bash_profile
You can then do eskew or egskew to get a client attached to the
containerized skewed emacs daemon.
After you are in, see the "Getting Started" section near the top of the default landing dashboard.
If you prefer to interact via Claude Desktop rather than directly with
Emacs, see Claude Desktop Integration for
setup instructions. The MCP configuration is automatically generated
when you run ./compose-dev up.
While the ./compose-dev up will pull fresh container images, it will
not automatically pull git updates to your local cloned skewed-emacs
repository. To do that:
cd ~/projects/skewed-emacs
./compose-dev down
git pull
./compose-dev up
As you can see, we bring down the docker composition before doing the git pull, just in case there is a change in docker compose configuration that might affect a shutdown.
Skewed Emacs includes a flexible icon system for the dashboard and org-mode agenda. By default we use colorful Unicode icons. If these do not work in your terminal, or you'd like a more muted experience, we recommend installing a Nerd Font in your terminal.
With a Nerd Font installed, you get flat professional looking icons rather than loud colorful gaudy ones.
-
Download a Nerd Font from nerdfonts.com
- Popular choices: Hack, FiraCode, JetBrainsMono, Meslo
- Download the "Nerd Font" version (not the regular font)
-
Install the font on your system:
- Windows: Right-click the
.ttffiles → "Install" - macOS: Double-click the
.ttffiles → "Install Font" - Linux: Copy to
~/.local/share/fonts/and runfc-cache -fv
- Windows: Right-click the
-
Configure your terminal to use the Nerd Font:
- Windows Terminal: Settings → Profiles → Defaults → Appearance → Font face
- iTerm2: Preferences → Profiles → Text → Font
- GNOME Terminal: Preferences → Profile → Custom font
- Alacritty: Edit
font.normal.familyin config
-
Enable nerd icons in Skewed Emacs by adding to your config or running:
(setq skewed-icons-style 'nerd)
Or interactively:
M-x skewed-icons-set-style RET nerd RET
| Style | Description | When to Use |
|---|---|---|
ascii |
Pure ASCII characters | Dumb terminals, serial consoles |
unicode |
Safe geometric symbols | Default, works everywhere |
unicode-fancy |
Colorful Unicode + VS15 | Experimental, terminal support varies |
nerd |
Nerd Font icons | Recommended with Nerd Font installed |
- Question marks in diamonds (�): Nerd Font not installed or not selected in terminal
- Misaligned columns: Switch from
unicode-fancytounicodeornerd - Icons look plain: Install a Nerd Font and set
skewed-icons-styleto'nerd
- Dangling Containers
If all containers do not shut down cleanly for some reason, you can list them with
docker ps
then forcibly remove one with
docker rm -f <container-name>
- Dangling Network
Sometimes a docker network "skewed-network" or "skewed-emacs-network"
can be left dangling, preventing a clean ./compose-dev up. Such
cases can be cleaned up with e.g.
cd ~/projects/skewed-emacs/
./compose-dev down
docker network rm skewed-emacs # if for some reason necessary
./compose-dev up
This section is for setting up the .emacs.d and other so-called "dot
files" in your home directory. It does not download or install or run
any of the systems discussed in the Containerized Runnings section
above.
- Make a
~/projects/directory if you don't already have one:
cd
mkdir -p projects/
cd projects/
- Clone this repo into
~/projects/:
git clone https://github.com/gornskew/skewed-emacs
cd skewed-emacs
-
Run the setup script:
cd ~/projects/skewed-emacs ./setup
The setup script will create symbolic links of the salient "dot-files" (hidden files starting with
.pointing to the corresponding files in the cloned repo, for example:~/.emacs.d -> ~/skewed-emacs/dot-files/emacs.dIf you already have any of these dot files existing (as links or actual files/directories), the existing files will be backed up with names appended with
-pre-skewed-emacs.
--dry-run: Shows what would happen without making any changes--shadow-suffix=NAMEor--shadow-suffix NAME: Creates symlinks with a "-NAME" suffix (e.g., with--shadow-suffix=testor--shadow-suffix testcreates ~/.emacs.d-test instead of ~/.emacs.d)--scrub-shadow-suffix=NAMEor--scrub-shadow-suffix NAME: Removes all symlinks with the "-NAME" suffix (e.g.,--scrub-shadow-suffix=testremoves ~/.emacs.d-test, ~/.bash_profile-test, etc.)--scrub-shadow-suffix=""or--scrub-shadow-suffix=: Removes all default symlinks without a suffix (e.g., removes ~/.emacs.d, ~/.bash_profile, etc.)
The setup script will automatically detect and replace broken symlinks
and handle existing dotfiles by backing them up with a
-pre-skewed-emacs suffix. It also skips backup files ending with
tilde (~) in the dot-files directory.
# Preview changes without modifying anything
./setup --dry-run
# Install configuration files with regular names
./setup
# Install configuration files with "-shadow" suffix
# (useful for testing or for maintaining multiple configurations)
./setup --shadow-suffix=shadow
# Install with a custom suffix
./setup --shadow-suffix=work
# Preview shadow installation without making changes
./setup --dry-run --shadow-suffix=shadow
# Preview custom suffix installation without making changes
./setup --dry-run --shadow-suffix=test
# Remove all symlinks with the "-test" suffix
./setup --scrub-shadow-suffix=test
# Preview removal of all symlinks with the "-shadow" suffix without making changes
./setup --dry-run --scrub-shadow-suffix=shadow
# Remove all symlinks with the "-test" suffix and create new ones with "-work" suffix
./setup --scrub-shadow-suffix=test --shadow-suffix=work
# Preview removing all symlinks with the "-test" suffix and creating
~/.emacs.d/ and ~/.bash_profile. It is designed to
back up this data, but in case of defects or failure it
would be wise to back up your existing dot files before
running the ./setup script.
- Bash
- Docker
- Git
dot-files/- all dotfiles that will end up symlinked to your home directoryemacs.d/- Emacs configuration, to be linked to ~/.emacs.d/init.el- Main Emacs configuration entry pointetc/- Modular configuration filessideloaded/- Second-party packages
bash_profile- Bash configurationtmux.conf- tmux configurationzshrc- ZSH configuration
For personal customizations that shouldn't be committed to this
repository, add them to a ~/.emacs-local file, which will be loaded
at the end of the Emacs initialization process.
This package is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) which presumably is compatible with Gnu Emacs's GPL.