{"id":19826908,"url":"https://github.com/sawsent/nelson","last_synced_at":"2025-05-01T14:31:51.896Z","repository":{"id":257651147,"uuid":"858782998","full_name":"sawsent/nelson","owner":"sawsent","description":"nelson is a Unix Command Line Tool written in Bash that allows for AI suggestions, error explanations, and more, all straight from the terminal. Currently using OpenAI API (because that's what I know), planning to move into an open source, local LLM in the future. ","archived":false,"fork":false,"pushed_at":"2024-10-21T16:01:12.000Z","size":438,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-06T14:43:07.908Z","etag":null,"topics":["ai","automation","bash","cli","contextual-help","customizable","developer-tools","shell-scripting","terminal","tool"],"latest_commit_sha":null,"homepage":"https://github.com/sawsent/nelson","language":"Shell","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/sawsent.png","metadata":{"files":{"readme":"README.md","changelog":"history.log","contributing":null,"funding":null,"license":"LICENSE","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":"2024-09-17T14:24:37.000Z","updated_at":"2024-10-29T20:54:53.000Z","dependencies_parsed_at":"2024-09-17T23:42:32.397Z","dependency_job_id":"44b7d8fd-bd13-4d2d-ba7b-2f5262028a16","html_url":"https://github.com/sawsent/nelson","commit_stats":null,"previous_names":["sawsent/nelsex"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sawsent%2Fnelson","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sawsent%2Fnelson/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sawsent%2Fnelson/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sawsent%2Fnelson/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sawsent","download_url":"https://codeload.github.com/sawsent/nelson/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251890107,"owners_count":21660449,"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":["ai","automation","bash","cli","contextual-help","customizable","developer-tools","shell-scripting","terminal","tool"],"created_at":"2024-11-12T11:11:59.570Z","updated_at":"2025-05-01T14:31:51.541Z","avatar_url":"https://github.com/sawsent.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nelson\nNelson is a Unix Command Line Tool written in Bash that allows for AI suggestions, error explanations, and more, all straight from the terminal. Currently using OpenAI API (because that's what I know), planning to move into an open source, local LLM in the future. \n\n---\n\n## Important\nThis tool uses OpenAI's ChatGPT models to generate responses via their API. In order to use this tool, you need to have a valid API key. **If you want to test out the tool, feel free to send me a message on Discord @sawsent , I might be able to provide one**.\n\n---\n\n## Dependencies\n#### Required:\n- [jq](https://github.com/jqlang/jq) \u003cbr\u003e\n#### Recommended:\n- [bat](https://github.com/sharkdp/bat)\n\n---\n\n## Instalation\n### Step 0: install dependencies with your favorite package manager\n### Step 1: clone repo wherever you'd like\n```sh\ngit clone https://github.com/sawsent/nelson.git\n```\n### Step 2: add your OpenAI key, folder location, and command alias to your shell config file\n```sh\n# .zshrc / .bashrc / .profile / ...\nexport OPENAI_API_KEY=\"your-openai-key\"\nexport NELSON_LOCATION=\"path/to/nelson\"\nalias nelson=\"$NELSON_LOCATION/src/main.sh\"\n```\n### Step 3: Change shell HISTFILE in [settings.sh](src/config/settings.sh)\n1. Find out where you Command History file is located\n```sh\necho $HISTFILE\n# My output: /Users/vicente.figueiredo/.zhistory\n``` \n2. Replace in [settings.sh](src/config/settings.sh)\n```sh\n# setings.sh\n\n# because we're using bash to run the script, it might be different than your main zsh or fish $HISTFILE (I think) \nexport HISTFILE=\"/Users/vicente.figueiredo/.zhistory\" # \u003c- replace with your $HISTFILE\n```\n### Step 4: Make the script executable! \nYou need to source your shell config file to access $NELSON_LOCATION\n```sh\nchmod +x $NELSON_LOCATION/src/main.sh\n```\n\n---\n\n## Usage\nYou can use this tool for as many reasons as you want. It's very easy to extend the functionality with custom system prompts and/or aliases. \n\n### Core features:\n1. Choose the model you want to use for the specific request _(ex: `--model=gpt-4o`)_\n2. Choose temperature you want to use _(ex: `--temp=0.5`)_\n3. Choose the max tokens you want to use _(ex: `--max-tokens=100`)_\n4. Choose the mode (System Prompt) to use with `--\\\u003cmode\u003e`\n5. **NEW:** Choose a one-time System Prompt with `--system-prompt=\"Custom Prompt\"`\n6. **NEW:** Ask nelson to explain the last error with `nelson --wtf`\n7. You can obviously change all defaults (see [settings.sh](src/config/settings.sh))\n8. Commands run and OpenAI responses (the whole JSON response) can be stored in an [history.log](history.log) file\n\n### Core modes \n(i didn't check if nelson was right btw, and Im using bat with some style opts for the output (see [settings.sh](src/config/settings.sh)))\n\n1. **--neat (-n):** Answers in the most concise way possible\n\u003cimg src=\"./resources/screenshot3.png\"\u003e\n\n2. **--long (-l):** Explains in more detail\n\u003cimg src=\"./resources/screenshot4.png\" width=600\u003e\n\n3. **--code (-c):** Simply codes what's requested. No comments and no explanations\n\u003cimg src=\"./resources/screenshot1.png\" width=600\u003e\n\n4. **--command (-com):** Provides a Shell command based on the given parameters\n**NEW:** copy the command to the clipboard with a single click!\n\u003cimg src=\"./resources/command_with_copy.png\"\u003e\n\n---\n\n### Nelson, wtf???\nYou can ask for clarification on your last command run by simply running `nelson --wtf`.\n\u003cimg src=\"./resources/preview-nelson-wtf2.png\" width=700\u003e\n\n### Customizability\nYou can easily change defaults, how the code is printed to the terminal in [settings.sh](src/config/settings.sh). \n\nYou can also easily add more modes (System Prompts) in the [system_prompts.sh](src/config/system_prompts.sh). Simply follow the pattern that's already there!\n\n```sh\ncase $1 in\n  default)\n    echo \"$DEFAULT_SYSTEM_PROMPT\"\n    ;;\n  # ...\n  # ...\n  your-custom-mode)\n    echo \"Your Custom System Prompt\"\n    ;;\n  # ...\n```\n\nOnce you do that, it will immediatly be available to use!\n```sh\nnelson --your-custom-mode Your question for nelson\n```\n(Keep in mind, you cant use any names that have already been defined as flags like --debug, --max-temperature, etc...). These take precedence in the flag hierarchy (they're evaluated first in the case block)\n\n---\n\n## Upcoming\n- [x] **Add A Way to override system prompts directly in the command line**: Instead of having to modify [system_prompts.sh](src/config/system_prompts.sh), you can simply do `nelson --system-prompt=\"Custom System Prompt\" question` for occasional System Prompt needs.\n- [x] **Add Context Support** (ex: `nelson --explain-error` / `nelson --wtf`): Automatically sends the last command run and the output for nelson to explain.\n- [ ] **Migrate / add support for locally-hosted LLMs (like Llama):** I have an API key because I put 10€ on a project once, but not everyone does so it would be better if you could use other APIs and self-hosted LLMs.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsawsent%2Fnelson","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsawsent%2Fnelson","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsawsent%2Fnelson/lists"}