A literate, GTD-focused Emacs configuration emphasizing modern LSP tooling, comprehensive documentation, and keyboard-driven workflows. All configuration lives in gmacs.org with detailed explanations of not just what is configured, but why each choice was made.
This configuration prioritizes:
- Literate Programming - All configuration is documented in
gmacs.orgwith explanations of WHY choices were made, not just WHAT they do - GTD Workflow - Org-mode configured for Getting Things Done methodology with custom capture templates and agenda views
- Performance - Deferred loading, optimized startup time, tree-sitter for fast parsing
- Modern Tools - Built-in Emacs 29+ features (Eglot, tree-sitter) over third-party alternatives where possible
- Keyboard-driven - Extensive keybindings, minimal mouse usage
| Operating System | Emacs Version |
|---|---|
| macOS Tahoe | Emacs 30.2 |
- Eglot integration with tree-sitter for fast, accurate syntax parsing
- Python: basedpyright + ruff for type checking and linting, automatic formatting
- JavaScript/TypeScript: typescript-language-server with full IDE features
- Automatic formatting on save with format-all
- Flycheck integration for additional syntax checking
- Complete Getting Things Done implementation with custom agenda views
- Custom capture templates for todos, meetings, knowledge investments
- Desktop notifications for upcoming deadlines
- OmniFocus integration for task capture with context
- Vertico + Orderless for flexible, fast completion
- Corfu for in-buffer popup completion (IDE-like autocomplete)
- Embark for context-aware actions on completion targets
- Consult extensions for enhanced navigation and search
- Marginalia for rich annotations on completion candidates
- Magit for Git operations with integrated TODO tracking
- Projectile for project-aware navigation and commands
- Ripgrep integration for blazing-fast code search
- Docker management directly from Emacs
- Pyenv automatic virtual environment activation
- Doom themes (doom-dracula) with doom-modeline
- Git-gutter for visual diff indicators
- Rainbow-mode for color code visualization
- Indent-bars for visual code structure
- Winner-mode for window configuration undo/redo
- Emacs 30.0 or later (recommended: Emacs Plus with native compilation)
- Git
- Homebrew (for macOS)
Install required command-line tools:
# Core tools
brew install git ripgrep
# Python development
brew install pyenv
pip install basedpyright ruff
# JavaScript/TypeScript development
npm install -g typescript-language-server typescript
# Optional but recommended
brew install just # For Justfile support- Backup existing configuration (if any):
mv ~/.emacs.d ~/.emacs.d.backup
- Clone this repository:
git clone https://github.com/gregnewman/gmacs ~/.emacs.d - Start Emacs - packages will install automatically via Straight.el:
emacsFirst startup will take a few minutes as packages are downloaded and compiled.
- Customize personal settings in
gmacs.org:- User information (name, email)
- Calendar coordinates (for sunrise/sunset)
- Theme preferences (if desired)
- Font preferences (currently Fira Code)
This is a literate configuration written in Org-mode. The main file is gmacs.org, which contains all configuration with extensive documentation explaining each choice.
- Package management (Straight.el + use-package)
- Themes and visual appearance
- Fonts and typography
- Basic editor preferences
- Fontification and beautification
- Core configuration with performance optimization
- Alert notifications
- Custom TODO keywords and capture templates
- Advanced agenda commands
- Babel for executable code blocks
- Eglot/LSP: Tree-sitter, major mode remapping, Eglot configuration, Flycheck, Eldoc, format-all
- Completion: Vertico, Savehist, Orderless, Marginalia, Consult, Embark
- In-buffer completion: Cape backends, Corfu UI
- Magit (Git interface)
- Projectile (project management)
- Pyenv (Python environments)
- Navigation (Avy, imenu-list)
- Window management (Winner mode, Golden Ratio)
- File handling (bookmarks, recent files)
- Writing modes (Logos, Olivetti)
- And 20+ more utility packages
gmacs.org- Main literate configuration with comprehensive documentationinit.el- Bootstrap file that loads the configurationearly-init.el- Early initialization settings for performance
As a software craftsman, this config provides excellent support for:
- Python - Full LSP with basedpyright, ruff linting, automatic formatting, pyenv integration
- JavaScript/TypeScript - TypeScript language server, JSX/TSX support, formatting
- Lisp family - Emacs Lisp, Racket, Scheme with proper indentation and REPL support
- Web - HTML, CSS, Tailwind support
- Others - Markdown, YAML, JSON, Lua, shell scripts
C-c c- Quick capture (todos, meetings, notes, knowledge investments)C-c a- Open agenda- Custom agenda views:
c(simple),d(by due date),f.(today’s focus),fh(hotlist) C-c o- Capture to OmniFocus with context
C-c p- Projectile commands (find file, switch project, search, etc.)C-c lprefix - All LSP commands (code actions, rename, format, organize imports)C-x g- Magit statusM-s- Jump to any character with Avy
C-'- Toggle imenu-list sidebar (code outline)C-.- Embark actions on thing at point- Consult commands for enhanced search and navigation
| Key | Command |
|---|---|
| C-x g | Magit status |
| C-c o | OmniFocus capture |
| C-c p | Projectile command map |
| C-c d | Docker management |
| M-s | Avy jump to char |
| C-’ | Toggle imenu-list sidebar |
| C-. | Embark act |
| C-; | Embark dwim |
| F2 g/l | Zoom in/out (Hydra) |
| C-c t | Adjust transparency |
| Key | Command |
|---|---|
| C-c c | Org capture |
| C-c a | Org agenda |
| C-c l | Store link |
| C-c g | Grab Mac link |
| Key | Command |
|---|---|
| C-c l a | Code actions |
| C-c l r | Rename symbol |
| C-c l f | Format buffer |
| C-c l d | Show documentation |
| C-c l o | Organize imports |
| C-c l h | Toggle inlay hints |
| C-c l q | Shutdown LSP server |
| Key | Command |
|---|---|
| C-c left | Winner undo |
| C-c right | Winner redo |
| Key | Command |
|---|---|
| C-x n | Next hunk |
| C-x p | Previous hunk |
| C-x v = | Show hunk |
| C-x v r | Revert hunk |
Edit gmacs.org and search for these sections:
- Personal information: Search for “user-full-name” to set your name and email
- Theme: Search for “doom-dracula” to change color scheme
- Font: Search for “Fira Code” to change font family and size
- Calendar location: Search for “Charlotte, NC” to set your coordinates
Follow the use-package pattern found throughout gmacs.org:
(use-package package-name
:ensure t
:defer t ; Load lazily for better startup time
:config
;; your configuration here
)Document your additions with a descriptive paragraph explaining why the package is useful and how it’s configured.
Some features are disabled by default but available:
- Golden Ratio mode - Automatic window sizing (set mode to 1 to enable)
- System packages - Automatic binary verification (uncomment to enable)
- Run
M-x esupto profile startup and identify bottlenecks - Check for expensive operations in
*Messages*buffer - Consider deferring more packages or removing unused ones
- Ensure language servers are installed:
# Python pip install basedpyright ruff # JavaScript/TypeScript npm install -g typescript-language-server
- Check the LSP stderr buffer:
M-x eglot-stderr-buffer - Verify the server is running:
M-x eglot-events-buffer
- Try updating all packages:
M-x straight-pull-all - Rebuild packages:
M-x straight-rebuild-all - Check
*Messages*buffer for specific errors - Delete
~/.emacs.d/straight/and restart to rebuild from scratch
- Ensure
.python-versionfile exists in your project root - Verify pyenv is installed and configured
- Check that the Python version in
.python-versionis installed in pyenv
- Install Fira Code:
brew install --cask font-fira-code - Install all-the-icons fonts:
M-x all-the-icons-install-fonts - Restart Emacs after font installation
- Startup is optimized with deferred loading - first launch takes longer as packages compile
- Tree-sitter grammars are installed on-demand when first opening supported file types
- Org agenda file discovery is deferred until Org is actually used
- Use
M-x esupto profile and optimize further
Configuration inspired by and code borrowed from:
- Jeremy Friesen’s dotemacs - Consult-imenu Python configuration
- Aaron Bieber’s Org-mode workflow - Agenda command ideas
- bnbeckwith’s bnb-emacs - Additional agenda configurations
Built with excellent packages:
- Straight.el for reproducible package management
- Doom themes for beautiful aesthetics
- Vertico modern completion framework
- Magit the best Git interface ever created
The code provided here is licensed under a GPL v3 license: see license.txt for details.
Some smaller parts from other authors are included in this configuration with attribution in the source comments. These may have different licenses - please check the inline comments for specifics.