{"id":25913454,"url":"https://github.com/zaydek/grokker","last_synced_at":"2025-07-09T04:05:29.101Z","repository":{"id":280103326,"uuid":"940645888","full_name":"zaydek/grokker","owner":"zaydek","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-01T09:16:25.000Z","size":46,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-01T09:22:42.290Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","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/zaydek.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":"2025-02-28T14:43:53.000Z","updated_at":"2025-03-01T09:16:29.000Z","dependencies_parsed_at":"2025-03-01T09:34:10.357Z","dependency_job_id":null,"html_url":"https://github.com/zaydek/grokker","commit_stats":null,"previous_names":["zaydek/grokker"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zaydek/grokker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaydek%2Fgrokker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaydek%2Fgrokker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaydek%2Fgrokker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaydek%2Fgrokker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zaydek","download_url":"https://codeload.github.com/zaydek/grokker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaydek%2Fgrokker/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264390709,"owners_count":23600561,"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":[],"created_at":"2025-03-03T10:20:05.907Z","updated_at":"2025-07-09T04:05:29.083Z","avatar_url":"https://github.com/zaydek.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- https://grok.com/chat/81e884f7-4ee3-4283-9a5d-f2e6c11bf9d0 --\u003e\n\n# `grokker` - A Command-Line Tool for Grokking Files\n\n`grokker` is a command-line tool intended to be used in conjunction with AI models like Grok 3 to make it easier to give eyes to the directory structure and files you are working with. It is akin to `grep` but offers a streamlined set of flags to make it easier to just get at the folders and files you are looking for.\n\nUse `grokker` to save you time and energy wrestling with convoluted Unix commands like `find . -type f -name \"*.js\" | grep \"store\" | xargs -I {} bash -c 'echo \"# {}\"; cat {}'`.\n\nFor example:\n\n- **Scan all files and folders in the current directory**:\n  ```bash\n  grokker\n  ```\n- **Scan all files and folders in the current directory up to one level deep**:\n  ```bash\n  grokker --dir-depth=1\n  ```\n- **Scan all files and folders in the current directory with file extensions `.ts`, `.tsx`**:\n  ```bash\n  grokker --ext=.ts,.tsx\n  ```\n- **Scan all files and folders in the current directory with file names and contents that match substrings `foo`, `bar`**:\n  ```bash\n  grokker --substring=foo,bar\n  ```\n\nOne of the neat features of `grokker` is the `format` and `action` flags.\n\n- The `format` flag allows you to specify the output format of the files and folders you are scanning.\n\n  The available formats are:\n\n  - `tree`: A directory tree of the files and folders.\n  - `list`: A list of file paths.\n  - `contents`: The contents of the files.\n\n  Formats can also be used in combination, for example:\n\n  - Show the tree and file contents:\n    ```bash\n    grokker --format=tree,contents\n    ```\n\n- The `action` flag allows you to specify what you want to do with the output.\n\n  The available actions are:\n\n  - `print`: Print the output to the console.\n  - `copy`: Copy the output to the clipboard. **Note**: At present this depends on `pbcopy` which is only available on macOS.\n\n  Actions can also be used in combination, for example:\n\n  - Print and copy the output:\n    ```bash\n    grokker --action=print,copy\n    ```\n\n## Install Grokker\n\n**Note**: `grokker` is written in Go and assumes you have Go installed on your system. If you do not already have Go installed, you can download it from the [official website](https://golang.org/dl/).\n\nTo install `grokker`, use the following command:\n\n```bash\ngo install github.com/zaydek/grokker@latest\n```\n\nOnce installed, you should be able to invoke `grokker` from anywhere even without calling `source` or other shell commands.\n\n## How to use Grokker effectively\n\nI wrote `grokker` to help me with the following use case: **I am working in a complicated codebase and do not trust VS Code Copilot or Cursor to make significant changes**. Additionally, I want to use a frontier model like Grok 3 and its web interface. So, I use `grokker` to quickly grep for all semantically relevant files and folders, get the text buffer of their tree representation, copy their filenames and contents to the clipboard, and paste that as input to Grok 3.\n\nI have found that this approach, combined with some preamble about what I am attempting to do, has consistently given me extremely high-quality results. I also much prefer this workflow over `#` or `@` in VS Code and Cursor because it allows me to multitask. But the point overall is that it does not matter whether you want to use Grok 3, ChatGPT 4.5, or Claude 3.7—this tool helps you effectively sift for relevant context and does not bind you to any one model or interface.\n\n### Flags\n\n- **`--dir=[string,...string]`**\n  Specifies the directories to search. Multiple directories can be provided as a comma-separated list such as `--dir=path/to/dir1,path/to/dir2`.\n\n  - **Default**: `--dir=.` (current directory)\n  - **Note**: Syntax expansion is supported for:\n    - `~` (home directory)\n    - `./` (current directory)\n    - `../` (parent directory)\n\n- **`--dir-depth=int`**\n  Sets the maximum recursion depth for directories. If you specify `1`, `grokker` will only search the top-level directory. You should generally not need to manually set this unless you have an arbitrarily deep directory structure.\n\n  - **Default**: `--dir-depth=-1` (unlimited depth)\n\n- **`--ext=[string,...string]`**\n  Specifies the file extensions to include. Extensions must include the leading dot (e.g., `.ts`, `.tsx`). Multiple extensions can be provided as a comma-separated list such as `--ext=.ts,.tsx`.\n\n  - **Default**: `--ext=[]` (include all files, does not filter by extension)\n\n- **`--substring=[string,...string]`**\n  Specifies substrings to filter file names or contents by. Multiple substrings can be provided as a comma-separated list such as `--substring=foo,bar,\"hello world\"`.\n\n  - **Default**: `[]` (all files)\n  - **Note**: Substring matching is case-sensitive.\n  - **Note**: Substrings may be unquoted. If the substring uses special characters, use double quotes or single quotes (recommended). For example, `--substring=\"hello world\"` and `--substring='hello world'`.\n\n- **`--action=[action,...action]`**\n  Specifies the actions to perform on the output. Multiple actions can be provided as a comma-separated list such as `--action=print,copy`.\n\n  - **Valid actions**: `print`, `copy`\n    - **`print`**: Prints the output to the console.\n    - **`copy`**: Copies the output to the clipboard.\n  - **Default**: `\"print,copy\"`\n\n- **`--format=[format,...format]`**\n  Specifies the output formats to generate. Multiple formats can be provided as a comma-separated list, and they will be concatenated in the output such as `--format=tree,contents`.\n  - **Valid formats**: `tree`, `list`, `contents`\n    - **`tree`**: Generates a hierarchical directory tree. Use `tree` when you want to visualize the directory structure.\n    - **`list`**: Generates a flat list of file paths. Use `list` when you want to list files akin to `ls -1`.\n    - **`contents`**: Generates the contents of the files.\n  - **Default**: `\"tree,contents\"`\n  - **Note**: `tree` prints file paths hierarchically but the output is not identical to the `tree` command. For example:\n    - `tree`:\n      ```\n      .\n      ├── app\n      │   └── store.js\n      └── lib\n          └── storeUtils.js\n      ```\n    - `grokker`:\n      ```\n      ./\n        app/\n          store.js\n        lib/\n          storeUtils.js\n      ```\n\n## Examples\n\n- **Process all files in the current directory and print+copy the contents**:\n\n  ```bash\n  grokker --dir=.\n  ```\n\n- **Print the list of files with \"store\" in the path**:\n\n  ```bash\n  grokker --substring=store --action=print --format=list\n  ```\n\n- **Copy the contents of `.js` files in `app/` to clipboard**:\n\n  ```bash\n  grokker --dir=app --ext=.js --action=copy --format=contents\n  ```\n\n- **Print and copy the tree and contents of `.ts`/`.tsx` files with \"bar\" or \"baz\"**:\n  ```bash\n  grokker --dir=foo,bar --substring=bar,baz --ext=.ts,.tsx --action=print,copy --format=tree,contents\n  ```\n\n## Usage\n\nTo see the usage information, run any one of the following commands:\n\n```bash\ngrokker\n```\n\n```bash\ngrokker -h\n```\n\n```bash\ngrokker --help\n```\n\nScreenshots of the usage information:\n\n\u003cimg width=\"965\" alt=\"Screenshot 2025-03-01 at 2 12 34 AM\" src=\"https://github.com/user-attachments/assets/e4dc9e75-7a8e-4901-84c8-117f9d3f1c88\" /\u003e\n\nTerminal output of the usage information:\n\n```bash\ngrokker is a command-line tool for grokking files (https://github.com/zaydek/grokker)\n\nUsage: grokker [flags]\n\nFlags:\n  --dir        Directories to search (comma-separated, default [.])\n  --dir-depth  Maximum directory depth to search (default -1, meaning infinite)\n  --ext        File extensions to include with leading dot (comma-separated, default []). Example: .ts, .tsx\n  --substring  Substrings to filter by (comma-separated, default [])\n  --action     Actions to perform: print, copy (comma-separated, default print,copy)\n  --format     Output formats: tree, list, contents (comma-separated, default tree,contents)\n\nExamples:\n  grokker                                                                                              Process all files in the current directory and print+copy the contents\n  grokker --substring=store --action=print --format=list                                               Print the list of files with \"store\" in the path\n  grokker --dir=app --ext=.js --action=copy --format=contents                                          Copy the contents of .js files in app/ to clipboard\n  grokker --dir=foo,bar --substring=bar,baz --ext=.ts,.tsx --action=print,copy --format=tree,contents  Print and copy the tree and contents of .ts/.tsx files with \"bar\" or \"baz\"\n```\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE.md](LICENSE.md) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzaydek%2Fgrokker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzaydek%2Fgrokker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzaydek%2Fgrokker/lists"}