{"id":18221862,"url":"https://github.com/karlicoss/grasp","last_synced_at":"2025-04-08T01:39:47.588Z","repository":{"id":37677505,"uuid":"164203973","full_name":"karlicoss/grasp","owner":"karlicoss","description":"A reliable org-capture browser extension for Chrome/Firefox","archived":false,"fork":false,"pushed_at":"2024-10-01T20:50:43.000Z","size":250,"stargazers_count":355,"open_issues_count":13,"forks_count":21,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-02T20:05:08.396Z","etag":null,"topics":["annotation","browser-extension","capture","chrome-extension","firefox-extension","org-capture","org-mode","pkm","webext"],"latest_commit_sha":null,"homepage":"https://beepb00p.xyz/grasp.html","language":"Python","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/karlicoss.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-05T10:18:27.000Z","updated_at":"2025-03-30T12:53:50.000Z","dependencies_parsed_at":"2024-11-03T22:04:52.052Z","dependency_job_id":"3dc52f8a-9e58-4fcc-9a94-cf7aeb535a3c","html_url":"https://github.com/karlicoss/grasp","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karlicoss%2Fgrasp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karlicoss%2Fgrasp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karlicoss%2Fgrasp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karlicoss%2Fgrasp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/karlicoss","download_url":"https://codeload.github.com/karlicoss/grasp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247761049,"owners_count":20991532,"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":["annotation","browser-extension","capture","chrome-extension","firefox-extension","org-capture","org-mode","pkm","webext"],"created_at":"2024-11-03T22:04:48.795Z","updated_at":"2025-04-08T01:39:47.572Z","avatar_url":"https://github.com/karlicoss.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Grasp is a browser extension for [Chrome](https://chrome.google.com/webstore/detail/org-grasp/ohhbcfjmnbmgkajljopdjcaokbpgbgfa) and [Firefox](https://addons.mozilla.org/en-US/firefox/addon/grasp), which adds a button/keybinding to capture current page title and url,\npossibly selected text, additional comments or tags and adds it into your [Org Mode](https://orgmode.org/) file.\n\n[Screenshot](https://user-images.githubusercontent.com/291333/51799721-a984eb80-221c-11e9-9612-8eb7f553dc01.png), [short demo](https://www.youtube.com/watch?v=Z8Bk-IazdGo).\n\n- [Chrome](https://chrome.google.com/webstore/detail/org-grasp/ohhbcfjmnbmgkajljopdjcaokbpgbgfa)\n- [Firefox](https://addons.mozilla.org/en-US/firefox/addon/grasp)\n- or, install from a zip: [releases](https://github.com/karlicoss/grasp/releases).\n\n# Running\nIn the simplest setup, the server runs locally, and you can use 'localhost' version of the extension. If you have to work on a computer where you can't run python scripts,\nor your target capture file is just not there, you can selfhost the server part elsewhere. Don't forget to set the endpoint in extension settings!\n\n## Setup\n- install `grasp_backend` package: `pip3 install --user grasp-backend`\n- install systemd/launchd service to autorun grasp\n  \n  `python3 -m grasp_backend setup --path /path/to/your/capture.org [--port \u003ccustom port\u003e] [--template \u003ccustom org-capture template\u003e]`\n  \n  Or alternatively, just run it directly if you don't want to autostart `python3 -m grasp_backend serve --path /path/to/your/capture.org [--port \u003ccustom port\u003e] [--template \u003ccustom org-capture template\u003e]`\n\n- install chrome extension and configure hotkeys\n\nThat's it! If you're using custom port make sure it's the same as in the extension settings (default is `12212`).\n\n## Configuration\n\n[Here](https://github.com/karlicoss/grasp/blob/af24c991579986cec73695daa8318e7831049305/server/org_tools.py#L91-L109) you can find some references for the `--template` syntax.\n\nIf you are looking for more flexible formatting that's not supported by template syntax, see [config.py.example](misc/config.py.example).\nYou can modify it to your liking and pass as `--config` to `grasp_backend setup` command.\n\n# Motivation\nWhy use org-capture? Well, it's hard to explain, maybe some other time... However, if you do know you want to use it instead of/alongside your browser bookmarks, by default\nyou don't have much choice and have to copy everything manually. For an experienced enough org-mode user it's no less than a torture. \n\nThis tool:\n\n- \\+ shows a notification when capturing fails/succeeds, so you won't lose your notes\n- \\+ doesn't require always running Emacs, simply appends an org-mode text entry to a file\n- \\+ can capture things that org-protocol can't handle (e.g. extra comment or tags)\n- \\+ can potentially use any plaintext format as a storage.\n\n     E.g. you might be more of a Markdown or Todo.txt fan (let me know if you are interested in that!).\n- \\- doesn't talk to Emacs, so can't benefit from Emacs capture templates\n    \n     E.g. currently you can't point at a specific header in an org file, it would just append at the end.\n\n- \\- requires running a small HTTP server\n     \n     However, there are no dependencies apart from python3, so in many ways, it's even more portable than Emacs.\n\nComparison with similar tools:\n\n## [org-capture-extension](https://github.com/sprig/org-capture-extension)\n\n- \\- relies on [org-protocol](https://orgmode.org/worg/org-contrib/org-protocol.html) and MIME handler: flaky for many people and has no feedback whether capture failed or succeeded\n     \n     Losing few days of captured stuff due to MIME handler mysteriously not working was the main motivator for me to develop grasp.\n\n- \\- requires always running Emacs, which might not be the case for some people\n- \\+ relies on org-protocol, so can potentially be better integrated with Emacs and your org-mode files\n\n## [org-protocol-capture-html](https://github.com/alphapapa/org-protocol-capture-html)\n\nSame pros/cons as `org-capture-extension` as it's relying on org-protocol.\n\nIn addition:\n\n- \\+ using a bookmarklet, hence browser-agnostic\n- \\+ capable of on the fly HTML to org-mode markup conversion\n\n# Potential improvements\n* see [todos](./TODO.org)\n\n# Permissions used\n* `http://localhost/capture` for talking with the backend\n  \n   If you want to use an external URL as an endpoint, you will be prompted for a permission dynamically.\n  \n* `storage` for settings\n* `notifications` for showing notification\n* `activeTab` for requesting page info\n\n# Building \u0026 developing\nThe most up-to-date instructions should be in [CI config](./.circleci/config.yml).\n\nYou need `npm` for building the extension.\n\n    npm install\n    ./build --target \u003cbrowser\u003e # e.g. ./build --target chrome or ./build --target firefox\n    \nAfter that you can find the extension in `dist` directory and 'Load unpacked** if necessary. There is also Flow and Eslint set up.\n\n## testing and linting\nCheck [CI config](./.github/workflows/main.yml) to figure out all the checks I'm doing.\n\nThere are some end2end tests which check both web extension and the browser, but require GUI, so they can't run on github actions. You can run them manually though.\n\n- `pytest -s --pyargs tests.test_end2end`\n\n## publishing\n\n- run `./publish` to generate extension zip files\n\n- firefox: `./build --firefox --release --lint --sign`\n\n  After than, upload the signed `xpi` file on [AMO](https://addons.mozilla.org/en-GB/developers/addon/grasp/versions)\n  \n- chrome:  `./build --chrome  --release --lint`\n\n  After that, upload the zip (generated by publish script) on [Web store](https://chrome.google.com/webstore/developer/dashboard)\n\n# Credits\n* Icon made by \u003ca href=\"https://www.freepik.com/\" title=\"Freepik\"\u003eFreepik\u003c/a\u003e from \u003ca href=\"https://www.flaticon.com/\" \t\t\t    title=\"Flaticon\"\u003ewww.flaticon.com\u003c/a\u003e, licensed by \u003ca href=\"http://creativecommons.org/licenses/by/3.0/\" \t\t\t    title=\"Creative Commons BY 3.0\" target=\"_blank\"\u003eCC 3.0 BY\u003c/a\u003e\n* [Original Org Capture extension](https://github.com/sprig/org-capture-extension)\n* [Boilerplate for Webpack Chrome extension](https://github.com/samuelsimoes/chrome-extension-webpack-boilerplate)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarlicoss%2Fgrasp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkarlicoss%2Fgrasp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarlicoss%2Fgrasp/lists"}