https://github.com/cristianoliveira/aerospace-marks
Vim like marks for Aerospace WM
https://github.com/cristianoliveira/aerospace-marks
command-line-tool golang macos productivity socket tiling-window-manager vim-like windows-manager
Last synced: 4 months ago
JSON representation
Vim like marks for Aerospace WM
- Host: GitHub
- URL: https://github.com/cristianoliveira/aerospace-marks
- Owner: cristianoliveira
- License: mit
- Created: 2025-05-14T20:56:23.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-06-18T19:08:47.000Z (4 months ago)
- Last Synced: 2025-06-18T20:21:14.587Z (4 months ago)
- Topics: command-line-tool, golang, macos, productivity, socket, tiling-window-manager, vim-like, windows-manager
- Language: Go
- Homepage:
- Size: 214 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# aerospace-marks
[Vim-like marks](https://i3wm.org/docs/userguide.html#vim_like_marks) for [AeroSpace WM](https://github.com/nikitabobko/AeroSpace)
**Beta**: I use this daily, but it's still a work in progress. Please report any issues or ideas in the [issues](https://github.com/cristianoliveira/aerospace-marks/issues) section.
## Demo
https://github.com/user-attachments/assets/cfd84749-c436-465d-8f66-486eb2303e30
## Description
Allows you to add custom marks to windows and use them to set focus or summon to the current workspace.
It’s heavily inspired by [sway marks](https://man.archlinux.org/man/sway.5.en), but follows the `aerospace` style of commands
```text
mark --add|--replace [--toggle]
Marks are arbitrary labels that can be used to identify certain
windows and then jump to them at a later time. Each identifier
can only be set on a single window at a time since they act as
a unique identifier. By default, mark sets identifier as the only
mark on a window. --add will instead add identifier to the list
of current marks for that window. If --toggle is specified mark will
remove identifier if it is already marked.
```
### Why not use named workspaces?
> TL;DR: Dynamic mappings to specific windows, not workspaces.
I wanted something more granular than workspaces — I want to jump to a specific window, given a context.
Sometimes my "video" context means YouTube, sometimes it’s a video player, sometimes a browser. I want to be able to jump to the right window, regardless of which workspace it's on.
Also, by pairing with [aerospace-scratchpad](https://github.com/cristianoliveira/aerospace-scratchpad) allows me to send away windows, mark then with a key for later bring then back!
## Basic Usage
Allow one to mark the current focused window with the given identifier.
```text
aerospace-marks mark [--add|--replace] [--toggle]
```
And then focus to a window with the given mark.
```text
aerospace-marks focus
```
Or summon a marked window to the current workspace.
```text
aerospace-marks summon
```
## Advanced Usage
See more in [documentation](docs/aerospace-marks)
Check [vim-like marks](https://i3wm.org/docs/userguide.html#vim_like_marks) for a more advanced usage.
### Config Usage
```toml
# ~/.config/aerospace/config.toml
[mode.main.binding]
# Vim's like marks, similar to i3-input
# cmd + ctrl + m and -- mark a window with a given
cmd-ctrl-m = """
exec-and-forget aerospace-marks mark \
$(osascript -e 'text returned of (display dialog "mark" default answer "")')
"""
# cmd + ctrl + ' and -- set focus on the window marked with
cmd-ctrl-quote = """
exec-and-forget aerospace-marks focus \
$(osascript -e 'text returned of (display dialog "focus" default answer "")')
"""
# Mark current window with a given identifier
cmd-shift-h = ["exec-and-forget aerospace-marks mark h"]
cmd-shift-j = ["exec-and-forget aerospace-marks mark j"]
cmd-shift-k = ["exec-and-forget aerospace-marks mark k"]
cmd-shift-l = ["exec-and-forget aerospace-marks mark l"]
cmd-shift-b = ["exec-and-forget aerospace-marks mark browser", "mode main"]
# Focus to a window with the given identifier
cmd-ctrl-h = ["exec-and-forget aerospace-marks focus h"]
cmd-ctrl-j = ["exec-and-forget aerospace-marks focus j"]
cmd-ctrl-k = ["exec-and-forget aerospace-marks focus k"]
cmd-ctrl-l = ["exec-and-forget aerospace-marks focus l"]
cmd-ctrl-b = ["exec-and-forget aerospace-marks focus browser", "mode main"]
```
## Installation
### Using Homebrew
If you have Homebrew installed, you can install `aerospace-marks` using the following command:
```bash
brew install cristianoliveira/tap/aerospace-marks
```
### Using Nix
If you have Nix installed, you can build and install `aerospace-marks` using the following command:
```bash
nix profile install github:cristianoliveira/aerospace-marks
```
You can also run without installing it by using:
```bash
nix run github:cristianoliveira/aerospace-marks
```
This will build the default package defined in `flake.nix`.
### Installing with Go
If you have Go installed, you can install `aerospace-marks` directly using:
```bash
go install github.com/cristianoliveira/aerospace-marks@latest
```
This will download and install the latest version of `aerospace-marks` to your `$GOPATH/bin`.
#### Post installation
After installing, you may need to include aerospace-marks in aerospace context.
Check where the binary is installed, run:
```bash
echo $(which aerospace-marks) | sed 's/\/aerospace-marks//g'
```
And in your config add:
```toml
[exec]
inherit-env-vars = true
# OR
[exec.env-vars]
# Replace 'aerospace-marks/install/path' with the actual path from the above command
PATH = 'aerospace-marks/install/path/bin:${PATH}'
```
### Building from Source
To build from source, ensure you have Go installed. Then, clone the repository and run:
```bash
git clone https://github.com/cristianoliveira/aerospace-marks.git
cd aerospace-marks
go build -o aerospace-marks
```
This will create an executable named `aerospace-marks` in the current directory.
## Troubleshooting
If you encounter issues while using `aerospace-marks`, you can use the following environment variables to help diagnose the problem:
- `AEROSPACE_MARKS_DB_PATH`: This variable sets the path for the AeroSpace marks database. By default, it is set to `$HOME/.local/state/aerospace-marks`. (You can connect with sqlite client)
- `AEROSPACE_MARKS_LOGS_PATH`: This variable specifies the path for the AeroSpace marks logs. The default path is `/tmp/aerospace-marks.log`. (use `tail -f `)
- `AEROSPACE_MARKS_LOGS_LEVEL`: This variable determines the logging level for AeroSpace marks. The default level is `DISABLED`.
These environment variables can be set directly in the AeroSpace configuration file to ensure they are available whenever AeroSpace is running. Add the following to your [AeroSpace config](https://nikitabobko.github.io/AeroSpace/guide#config-location)
```toml
[exec.env-vars]
# Path for the AeroSpace marks database
AEROSPACE_MARKS_DB_PATH = "$HOME/.local/state/aerospace-marks"
# Path for the AeroSpace marks logs
AEROSPACE_MARKS_LOGS_PATH = "/tmp/aerospace-marks.log"
# Logging level for AeroSpace marks
AEROSPACE_MARKS_LOGS_LEVEL = "DEBUG"
```
Replace the paths and values with your desired settings.
### Packages
- AeroSpace Socket IPC - [aerospace-ipc](https://github.com/cristianoliveira/aerospace-ipc)
## License
This project is licensed under the terms of the LICENSE file.