{"id":13451217,"url":"https://github.com/paperwm/gnome-shell-mode","last_synced_at":"2026-03-06T00:31:04.294Z","repository":{"id":52453958,"uuid":"85556007","full_name":"paperwm/gnome-shell-mode","owner":"paperwm","description":"Package for developing gnome-shell extensions","archived":false,"fork":false,"pushed_at":"2023-01-20T16:13:42.000Z","size":215,"stargazers_count":29,"open_issues_count":15,"forks_count":7,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-11-22T08:00:32.643Z","etag":null,"topics":["emacs-mode","emacs-package","emacs-packages","gjs","gnome-shell","spacemacs-layer"],"latest_commit_sha":null,"homepage":"","language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paperwm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-20T09:07:29.000Z","updated_at":"2025-04-05T22:04:59.000Z","dependencies_parsed_at":"2022-08-25T04:00:18.375Z","dependency_job_id":null,"html_url":"https://github.com/paperwm/gnome-shell-mode","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/paperwm/gnome-shell-mode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperwm%2Fgnome-shell-mode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperwm%2Fgnome-shell-mode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperwm%2Fgnome-shell-mode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperwm%2Fgnome-shell-mode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paperwm","download_url":"https://codeload.github.com/paperwm/gnome-shell-mode/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paperwm%2Fgnome-shell-mode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30156285,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T22:39:40.138Z","status":"ssl_error","status_checked_at":"2026-03-05T22:39:24.771Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["emacs-mode","emacs-package","emacs-packages","gjs","gnome-shell","spacemacs-layer"],"created_at":"2024-07-31T07:00:49.988Z","updated_at":"2026-03-06T00:31:04.246Z","avatar_url":"https://github.com/paperwm.png","language":"Emacs Lisp","funding_links":[],"categories":["Emacs Lisp"],"sub_categories":[],"readme":"## gnome-shell-mode - Looking Glass for Emacs\n\ngnome-shell-mode makes it easy to interactively explore and evaluate javascript in a [Gnome Shell](https://wiki.gnome.org/Projects/GnomeShell) session. It supports file local evaluation and auto-completion when working on a loaded Gnome Shell extension.\n\n## Installation\n\nThere's no melpa package yet, but it's quite easy to install the package(s) manually.\n\n### Doom emacs\n\nIn your `packages.el`:\n\n```emacs-lisp\n(package! gnome-shell-mode\n  :recipe (:host github :repo \"paperwm/gnome-shell-mode\"\n           :files (\"local/gnome-shell-mode/*\")))\n(package! company-gnome-shell\n  :recipe (:host github :repo \"paperwm/gnome-shell-mode\"\n           :files (\"local/company-gnome-shell/*.el\")))\n```\n\nand in your `config.el`:\n\n```emacs-lisp\n(use-package! gnome-shell-mode\n  :defer t\n  :commands (gnome-shell-mode)\n  :config\n  (setq-hook! 'gnome-shell-mode-hook\n    mode-name \"GJS\")\n\n  (map!\n   :map gnome-shell-mode-map\n   :v \"\u003creturn\u003e\" 'gnome-shell-send-region\n   :gvni \"C-\u003creturn\u003e\" 'gnome-shell-repl\n\n   :map gnome-shell-mode-map\n   :localleader\n   :gnv :desc \"Reload buffer\" \"r\" 'gnome-shell-reload\n   :desc \"Reload session\" \"R\" 'gnome-shell-restart\n   :desc \"Launch session\" \"l\" 'gnome-shell-launch-session\n   :desc \"Clear output\" \"c\" 'gnome-shell-clear-output-at-point\n\n   (:prefix (\"g\" . \"jump\")\n     :desc \"Jump to definition\" \"g\" '+lookup/definition)\n\n   (:prefix (\"s\" . \"eval in session\")\n     :desc \"Eval buffer\" \"b\" 'gnome-shell-send-buffer\n     :desc \"Eval function\" \"f\" 'gnome-shell-send-proc\n     :desc \"Eval function\" \"d\" 'gnome-shell-send-proc\n     :desc \"Eval line\" \"l\" 'gnome-shell-send-current-line\n     :desc \"Eval region\" \"r\" 'gnome-shell-send-region)\n\n   (:prefix (\"e\" . \"eval in session\")\n     :desc \"Eval buffer\" \"b\" 'gnome-shell-send-buffer\n     :desc \"Eval function\" \"f\" 'gnome-shell-send-proc\n     :desc \"Eval function\" \"d\" 'gnome-shell-send-proc\n     :desc \"Eval line\" \"l\" 'gnome-shell-send-current-line\n     :desc \"Eval region\" \"r\" 'gnome-shell-send-region)\n\n   (:prefix (\"o\" . \"output\")\n     :desc \"Clear all output\" \"c\" 'gnome-shell-clear-output\n     :desc \"Copy output\" \"y\" 'gnome-shell-copy-output)\n\n   (:prefix (\"h\" . \"help\")\n     :desc \"Lookup at point\" \"h\" 'gnome-shell-look-up-function-at-point\n     )\n   )\n  )\n\n(use-package! company-gnome-shell\n  :defer t\n  :commands (company-gnome-shell)\n  :init\n  (set-company-backend! 'gnome-shell-mode 'company-gnome-shell))\n```\n\n### Spacemacs \n\nClone the repo and create a symlink named `gnome-shell` in the spacemacs `private` folder:\n```shell\ngit clone https://github.com/paperwm/gnome-shell-mode.git ~/the/destination\nln -s ~/the/destination /.emacs.d/private/gnome-shell\n```\nAdd gnome-shell to your list of Spacemacs layers:\n\n```emacs-lisp\n   dotspacemacs-configuration-layers\n   '(\n     ...\n     gnome-shell\n     ...\n    )\n```\n\nRestart emacs and you're ready to go.\n\n### Vanilla emacs\n\nAdd both `local/gnome-shell-mode` and `local/company-gnome-shell` to the `load-path`.\n\nThen add this to `init.el`:\n\n```emacs-lisp\n    (require 'company)\n\n    (require 'gnome-shell-mode)\n    (require 'company-gnome-shell)\n    \n    ;; Most staight forward but might mess up company in other modes?\n    (eval-after-load \"company\"\n     (add-to-list 'company-backends 'company-gnome-shell))\n```\n\nSee `gnome-shell-mode-pkg.el` and `company-gnome-shell.el` for list of dependencies.\n\nNB: The rest of the readme describe the keybindings defined by the spacemacs layer. Some vanilla emacs bindings are also defined by default. See the bottom of `gnome-shell-mode.el`. \n\n## Usage\n\nMake sure you're in gnome-shell-mode (eg. by using \u003ckbd\u003eM-x gnome-shell-mode\u003c/kbd\u003e). All the actions will then be under the major-mode leader key (\u003ckbd\u003eM-m\u003c/kbd\u003e or \u003ckbd\u003e,\u003c/kbd\u003e).\n\nFor instance \u003ckbd\u003e,sf\u003c/kbd\u003e will evaluate the surrounding function and the evaluated region will pulse green or red depending on the success of the evaluation. If an error occurred, the position reported by gjs will be marked as a flycheck error.\n\nThere's two non-standard keybindings:\n- \u003ckbd\u003eReturn\u003c/kbd\u003e will evaluate the active region (if evil is used), the result will be shown in the minibuffer.\n- \u003ckbd\u003eC-Return\u003c/kbd\u003e will evaluate the active region, or the current line if there's no region active. The result will be added in an overlay ala. magit-blame. The overlay can be cleared by \u003ckbd\u003e,c\u003c/kbd\u003e or by deleting the input.\n\nThe global variable `$` contains the value of the most recent evaluation.\n\n### Launch session\n\nBy default gnome-shell-mode connects to the live Gnome Shell session. This can be a bit risky however, especially on Wayland where restart doesn't work.\n\nRun `M-x gnome-shell-launch-session`, (`, l` if using spacemacs), to launch and connect to a nested session, the session's log will popup in a new buffer too. When a session is already running `, l`  will simply take you to the log. To launch a clean session close the nested Gnome Shell window first.\n\nIf the nested session encounter runtime errors they will be reported as errors in the correct buffer (using flycheck).\n\n### Reload\n\nThe mode supports reloading buffers with \u003ckbd\u003e, r\u003c/kbd\u003e. This works by first disabling the extension, re-evaluating the whole buffer in the correct scope, and then enabling the extension again.\n\nTo get full use of this, `enable` and `disable` need to assemble and disassemble all the state in the extension. A good way to handle this is having `enable` and `disable` functions in every module, making the exension's `enable` and `disable` just call out to the module's functions.\n\n### Restart\n\nPressing \u003ckbd\u003e, R\u003c/kbd\u003e in spacemacs will disable the extension the current buffer is part of and then restart Gnome Shell. This gives the extension a change to clean up and save any state making the restart less disruptive. This can also be accessed through the interactive function `gnome-shell-restart`. Note that restart is only supported on X11.\n\n### Documentation lookup\n\nThere's basic support for documentation lookup using \u003ckbd\u003e, h h\u003c/kbd\u003e. This will prompt you with a list of known symbols matching the current word, selecting one will open the documentation of that symbol in your browser.\n\n### Gnome Shell extension support\n\nAuto-completion and evaluation happens in the file local scope when editing a loaded extension, or a file in the Gnome Shell source tree. When editing a file not part of an extension the system creates an ad-hoc scope for the file.\n\nMore specifically, if there's an `imports.some.path` object corresponding to the file being edited the scope of evaluation will be `imports.some.path` (or `someExtension.imports.some.path` in the case of extension code).\n\nA small example of how this works in practice. Lets say you have a successfully loaded extension in the directory `MyExtension/`and you have some silly functions in `MyExtension/functions.js`:\n\n```javascript\nfunction helloWorld (hello, world) {\n  return `${hello} ${world}`;\n}\n\nfunction printHelloWorld() {\n  print(helloWorld('hello', 'world'));\n}\n\n```\n\nNow yout want `helloWorld` to also add some exclamation marks:\n```javascript\nfunction helloWorld (hello, world) {\n  return `${hello} ${world}!!!`;\n}\n```\n\nAfter having made this change you can simply re-evaluate the function (eg. by \u003ckbd\u003e, s f\u003c/kbd\u003e) and `printHelloWorld` will pick up the change.\n\nThis is done by looking up the extension object through the `uuid` from the `metadata.json` file, and then looking up the module object through the extension relative file path:\n ```javascript\nlet Extension = imports.misc.extensionUtils.extensions[uuid];\nlet module = Extension.imports.path.to.current.file;\n```\n\nHaving the module object we can simply use ``eval(`with(module) { ${code} }`)`` so re-evaluated code will have the correct closure.\n\nReassignment relies on SpiderMonkey's built in parser. We traverse the top level statements, replacing all variable and function declarations. So eg. `function name () {}` gets translated to `module.name = function () {}` and `var foo = 'bar';` to `module.foo = 'bar';`. Having a proper parse tree means we can handle complex assignments with descructuring too (eg. 'let [foo, bar] = ...').\n\n## Caveats\n\nNot all methods of GObjects (g-object-introspected classes) complete before they're used the first time. This include a lot of classes you'll interact with. eg. `MetaWindow`. Fixed in [gjs 1.55.1](https://gitlab.gnome.org/GNOME/gjs/commit/8e982d37e9fd9adcf9e87573d91cbffaf1e7b509)\n\nWhile gnome-shell-mode shouldn't cause any crashes by itself, evaluating javascript in Gnome Shell is not completely safe, some code will result in a crash. Eg. looking up a non-existing dconf/schema name will cause a crash.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaperwm%2Fgnome-shell-mode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaperwm%2Fgnome-shell-mode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaperwm%2Fgnome-shell-mode/lists"}