{"id":13473518,"url":"https://github.com/cmacrae/spacebar","last_synced_at":"2025-05-16T09:03:12.409Z","repository":{"id":40430131,"uuid":"251004953","full_name":"cmacrae/spacebar","owner":"cmacrae","description":"A minimal status bar for macOS. Ideal for use with tiling window managers like yabai","archived":false,"fork":false,"pushed_at":"2023-02-16T20:33:45.000Z","size":133,"stargazers_count":1270,"open_issues_count":40,"forks_count":51,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-10-29T17:12:45.147Z","etag":null,"topics":["minimal","nix","nix-darwin","spacebar","status-bar","tiling-window-manager","yabai"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cmacrae.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null},"funding":{"github":["cmacrae"]}},"created_at":"2020-03-29T10:23:10.000Z","updated_at":"2024-10-28T15:54:58.000Z","dependencies_parsed_at":"2024-01-13T14:42:14.498Z","dependency_job_id":"9f873bf4-a3f6-4b70-b109-4e2537d3804c","html_url":"https://github.com/cmacrae/spacebar","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmacrae%2Fspacebar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmacrae%2Fspacebar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmacrae%2Fspacebar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmacrae%2Fspacebar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cmacrae","download_url":"https://codeload.github.com/cmacrae/spacebar/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254501555,"owners_count":22081528,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["minimal","nix","nix-darwin","spacebar","status-bar","tiling-window-manager","yabai"],"created_at":"2024-07-31T16:01:04.376Z","updated_at":"2025-05-16T09:03:12.389Z","avatar_url":"https://github.com/cmacrae.png","language":"C","funding_links":["https://github.com/sponsors/cmacrae"],"categories":["C"],"sub_categories":[],"readme":"\u003c!-- Please be careful editing the below HTML, as GitHub is quite finicky with anything that looks like an HTML tag in GitHub Flavored Markdown. --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eA minimal status bar for macOS\u003c/b\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/cmacrae/spacebar/actions/workflows/build-and-release.yaml\"\u003e\n    \u003cimg src=\"https://github.com/cmacrae/spacebar/actions/workflows/build-and-release.yaml/badge.svg\" alt=\"Build Status Badge\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/cmacrae/spacebar/blob/master/LICENSE.txt\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/cmacrae/spacebar.svg?color=a6dcef\" alt=\"License Badge\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/cmacrae/spacebar/blob/master/CHANGELOG.md\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/view-changelog-726a95.svg\" alt=\"Changelog Badge\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://builtwithnix.org\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Built_With-Nix-5277C3.svg?logo=nixos\u0026labelColor=73C3D5\" alt=\"Nix Badge\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/cmacrae/spacebar/projects/1\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Project-tasks-7fdbda.svg?logo=trello\" alt=\"GitHub Project Badge\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/cmacrae/spacebar/compare/v1.4.0...HEAD\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/commits-since/cmacrae/spacebar/latest.svg?color=ea907a\" alt=\"Version Badge\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/cmacrae/spacebar/discussions\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/GitHub-Discussions-a3ddcb.svg?labelColor=3b5360\" alt=\"Discussions Badge\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/sponsors/cmacrae\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Sponsor-f8f8f8.svg?logo=github-sponsors\" alt=\"Discussions Badge\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## About\nspacebar is a minimal status bar for macOS. Ideal for use with tiling window managers like [yabai](https://github.com/koekeishiya/yabai).\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://i.imgur.com/SFe0ifD.png\" alt=\"spacebar demo\"\u003e\n\u003c/p\u003e\n\n## Installation\nA package and service to install and manage spacebar is provided in two flavours: [Homebrew](https://brew.sh) \u0026 [Nix](https://nixos.org).  \nThere is also a precompiled binary archive available in [the latest release assets](https://github.com/cmacrae/spacebar/releases/tag/v1.4.0).  \n\n### Homebrew\nspacebar can be installed using Homebrew from the `cmacrae/formulae` tap\n```\nbrew install cmacrae/formulae/spacebar\nbrew services start spacebar\n```\n\n### Nix\nA package is generally available to Nix users on macOS in the various channels.  \nA [Flake](https://nixos.wiki/wiki/Flakes) is also available in this repository and can be used like so:\n```nix\n{\n  inputs.darwin.url = \"github:lnl7/nix-darwin\";\n  inputs.spacebar.url = \"github:cmacrae/spacebar/v1.4.0\";\n\n  outputs = { self, darwin, spacebar }: {\n    darwinConfigurations.example = darwin.lib.darwinSystem {\n      modules = [\n        {\n          nixpkgs.overlays = [\n            spacebar.overlay\n          ];\n        }\n      ];\n    };\n  };\n}\n```\nOr try it out with `nix run github:cmacrae/spacebar/v1.4.0`!\n\nspacebar can be configured and managed in a declarative manner using the `services.spacebar` module in [nix-darwin](https://github.com/LnL7/nix-darwin)\n\n### Accessibility Permissions\nspacebar makes use of the macOS Accessibility APIs -  after starting spacebar, you should be prompted to grant access.  \nOpen System Preferences.app and navigate to Security \u0026 Privacy, then Privacy, then Accessibility. Click the lock icon at the bottom and enter your password to allow changes to the list. Check the box next to spacebar to allow accessibility permissions.\n\n## Configuration\nspacebar is configured by setting `config` properties via its messaging socket. Not only does this mean you can try out config changes live, it also means spacebar's configuration file is simply a shell script - usually just a sequence of `spacebar -m config \u003coption\u003e \u003cvalue\u003e` statements.  \n\nspacebar's configuration file must executable and is looked for in the following locations (in this order) by default:\n* `$XDG_CONFIG_HOME/spacebar/spacebarrc`\n* `$HOME/.config/spacebar/spacebarrc`\n* `$HOME/.spacebarrc`\n\n### Getting started\nTo get started, create an empty configuration file and make it executable:\n```\nmkdir -p ~/.config/spacebar\ntouch ~/.config/spacebar/spacebarrc\nchmod +x ~/.config/spacebar/spacebarrc\n```\n\nHere's a configuration taken from [`examples/`](https://github.com/cmacrae/spacebar/blob/v1.4.0/examples/spacebarrc):\n```\n#!/usr/bin/env sh\n\nspacebar -m config position             top\nspacebar -m config height               26\nspacebar -m config title                on\nspacebar -m config spaces               on\nspacebar -m config clock                on\nspacebar -m config power                on\nspacebar -m config padding_left         20\nspacebar -m config padding_right        20\nspacebar -m config spacing_left         25\nspacebar -m config spacing_right        15\nspacebar -m config text_font            \"Helvetica Neue:Bold:12.0\"\nspacebar -m config icon_font            \"Font Awesome 5 Free:Solid:12.0\"\nspacebar -m config background_color     0xff202020\nspacebar -m config foreground_color     0xffa8a8a8\nspacebar -m config space_icon_color     0xff458588\nspacebar -m config power_icon_color     0xffcd950c\nspacebar -m config battery_icon_color   0xffd75f5f\nspacebar -m config dnd_icon_color       0xffa8a8a8\nspacebar -m config clock_icon_color     0xffa8a8a8\nspacebar -m config power_icon_strip      \nspacebar -m config space_icon_strip     I II III IV V VI VII VIII IX X\nspacebar -m config space_icon           \nspacebar -m config clock_icon           \nspacebar -m config dnd_icon             \nspacebar -m config clock_format         \"%d/%m/%y %R\"\nspacebar -m config right_shell          on\nspacebar -m config right_shell_icon     \nspacebar -m config right_shell_command  \"whoami\"\n\necho \"spacebar configuration loaded..\"\n\n```\n_Note: Ensure fonts are installed to use glyphs_\n\nFor further configuration documentation, please see [`man spacebar`](https://github.com/cmacrae/spacebar/blob/v1.4.0/doc/spacebar.asciidoc)\n\n### Declarative configuration with Nix\nIf you're using the `services.spacebar` module from [nix-darwin](https://github.com/LnL7/nix-darwin), you can configure spacebar like so:\n```nix\n{\n  services.spacebar.enable = true;\n  services.spacebar.package = pkgs.spacebar;\n  services.spacebar.config = {\n    position                   = \"top\";\n    display                    = \"main\";\n    height                     = 26;\n    title                      = \"on\";\n    spaces                     = \"on\";\n    clock                      = \"on\";\n    power                      = \"on\";\n    padding_left               = 20;\n    padding_right              = 20;\n    spacing_left               = 25;\n    spacing_right              = 15;\n    text_font                  = ''\"Menlo:Regular:12.0\"'';\n    icon_font                  = ''\"Font Awesome 5 Free:Solid:12.0\"'';\n    background_color           = \"0xff202020\";\n    foreground_color           = \"0xffa8a8a8\";\n    power_icon_color           = \"0xffcd950c\";\n    battery_icon_color         = \"0xffd75f5f\";\n    dnd_icon_color             = \"0xffa8a8a8\";\n    clock_icon_color           = \"0xffa8a8a8\";\n    power_icon_strip           = \" \";\n    space_icon                 = \"•\";\n    space_icon_strip           = \"1 2 3 4 5 6 7 8 9 10\";\n    spaces_for_all_displays    = \"on\";\n    display_separator          = \"on\";\n    display_separator_icon     = \"\";\n    space_icon_color           = \"0xff458588\";\n    space_icon_color_secondary = \"0xff78c4d4\";\n    space_icon_color_tertiary  = \"0xfffff9b0\";\n    clock_icon                 = \"\";\n    dnd_icon                   = \"\";\n    clock_format               = ''\"%d/%m/%y %R\"'';\n    right_shell                = \"on\";\n    right_shell_icon           = \"\";\n    right_shell_command        = \"whoami\";\n  };\n}\n```\n\n## Integration with yabai\nyabai provides the `external_bar` config option. This can be used so yabai plays nice with spacebar.  \nTake a look at this excerpt from the yabai man page\n\u003e       external_bar [\u003cmain|all|off\u003e:\u003ctop_padding\u003e:\u003cbottom_padding\u003e]\n\u003e           Specify top and bottom padding for a potential custom bar that you may be running.\n\u003e           main: Apply the given padding only to spaces located on the main display.\n\u003e           all:  Apply the given padding to all spaces regardless of their display.\n\u003e           off:  Do not apply any special padding.\n\n\nSo, if you like having spacebar at the bottom, you'd use `yabai -m config external_bar all:0:26`  \n\nYou can also use the command `spacebar -m config height` with no argument to get the current height, which you could then use in conjunction with `external_bar`:\n```\nSPACEBAR_HEIGHT=$(spacebar -m config height)\nyabai -m config external_bar all:0:$SPACEBAR_HEIGHT\n```\n\n## Debug output and error reporting\nIn the case that something isn't working as you're expecting, please make sure to take a look in the output and error log. To enable debug output make sure that your configuration file contains `spacebar -m config debug_output on` or that spacebar is launched with the `--verbose` flag.\n\n### Homebrew\nIf you're using the Homebrew service, the log files can be found in the following directory:\n```\n# directory containing log files (HOMEBREW_PREFIX defaults to /usr/local unless you manually specified otherwise)\n$HOMEBREW_PREFIX/var/log/spacebar/\n\n# view the last lines of the error log \ntail -f /usr/local/var/log/spacebar/spacebar.err.log\n\n# view the last lines of the debug log\ntail -f /usr/local/var/log/spacebar/spacebar.out.log\n```\n\n### Nix\nIf you're using the Nix service, you can set up debugging like so:\n```nix\n{\n  services.spacebar.config.debug_output = \"on\";\n  launchd.user.agents.spacebar.serviceConfig.StandardErrorPath = \"/tmp/spacebar.err.log\";\n  launchd.user.agents.spacebar.serviceConfig.StandardOutPath = \"/tmp/spacebar.out.log\";\n}\n```\n\n## Upgrading\nTo upgrade the Homebrew package, run\n```\nbrew services stop spacebar\nbrew upgrade spacebar\nbrew services start spacebar\n```\n\nIf you're using the Nix package form the nixpkgs collection and keeping your channels up to date, package upgrades will roll in as you command.  \nIf you're using the Nix Flake, you can update your `input.spacebar.url` to point to the latest release tag and update your lockfile.\n\n## Requirements and Caveats\nPlease read the below requirements carefully.  \nMake sure you fulfil all of them before filing an issue.\n\n|Requirement|Note|\n|-:|:-|\n|Operating System|macOS Catalina 10.15.0+ is supported.|\n|Accessibility API|spacebar must be given permission to utilize the Accessibility API and will request access upon launch. The application must be restarted after access has been granted.|\n\nPlease also take note of the following caveats.\n\n|Caveat|Note|\n|-:|:-|\n|Code Signing|When building from source (or installing from HEAD), it is recommended to codesign the binary so it retains its accessibility and automation privileges when updated or rebuilt.|\n|Mission Control|In the Mission Control preferences pane in System Preferences, the setting \"Automatically rearrange Spaces based on most recent use\" should be disabled.|\n\n## Releases and branches\nMain work for this project is conducted on the `master` branch, and thus it should be considered unstable (expect bugs!).  \nThere is no particular release cycle, just as and when features/fixes are ready :)\n\n## License and Attributions\nspacebar is licensed under the [MIT License](LICENSE.txt), a short and simple permissive license with conditions only requiring preservation of copyright and license notices.\nLicensed works, modifications, and larger works may be distributed under different terms and without source code.\n\nMany thanks to [@koekeishiya](https://github.com/koekeishiya) for creating yabai, and providing the codebase for an example status bar, from which this project was born.\n\n## Disclaimer\nUse at your own discretion.  \nI take no responsibility if anything should happen to your machine while trying to install, test or otherwise use this software in any form.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmacrae%2Fspacebar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcmacrae%2Fspacebar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmacrae%2Fspacebar/lists"}