{"id":28795920,"url":"https://github.com/nestordemeure/shelly","last_synced_at":"2026-05-20T05:06:56.121Z","repository":{"id":298769580,"uuid":"1001038763","full_name":"nestordemeure/shelly","owner":"nestordemeure","description":"An LLM based shell assistant that knows your usual shell commands.","archived":false,"fork":false,"pushed_at":"2025-07-12T00:24:49.000Z","size":219,"stargazers_count":14,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-12T02:22:08.810Z","etag":null,"topics":["agent","llm","shell"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nestordemeure.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-12T18:02:36.000Z","updated_at":"2025-06-18T23:57:43.000Z","dependencies_parsed_at":"2025-06-12T21:25:26.625Z","dependency_job_id":"6864b3ee-a0ea-4275-aded-01bb05f89d6b","html_url":"https://github.com/nestordemeure/shelly","commit_stats":null,"previous_names":["nestordemeure/shelly"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nestordemeure/shelly","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nestordemeure%2Fshelly","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nestordemeure%2Fshelly/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nestordemeure%2Fshelly/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nestordemeure%2Fshelly/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nestordemeure","download_url":"https://codeload.github.com/nestordemeure/shelly/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nestordemeure%2Fshelly/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274194970,"owners_count":25239146,"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","status":"online","status_checked_at":"2025-09-08T02:00:09.813Z","response_time":121,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["agent","llm","shell"],"created_at":"2025-06-18T03:10:43.914Z","updated_at":"2026-05-20T05:06:56.088Z","avatar_url":"https://github.com/nestordemeure.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Shelly 🐚\n\nA smart terminal assistant that translates natural language into shell commands.\n\nDescribe what you want in plain English, and Shelly will figure out the right commands, explain what they do, and run them for you.\n\n```sh\n# Instead of remembering complex commands...\n$ find . -type f -exec ls -la {} \\; | sort -k5 -rn | head -20\n\n# Just ask Shelly:\n$ shelly show me the 20 largest files in this directory tree\n```\n\n## Installation\n\nClone the repository and install dependencies:\n\n```sh\n# Clone and enter the repository\ngit clone https://github.com/nestordemeure/shelly.git\ncd shelly\n\n# Set up Python environment\npython3 -m venv shelly-env\nsource shelly-env/bin/activate\n\n# Install dependencies\npip install llm python-dotenv rich\n```\n\nTo add a `shelly` command to your terminal, add this function to your `.bashrc` or `.zshrc`:\n\n```sh\nshelly() {\n  local SHELLY_DIR=\"/path/to/shelly\"  # Update this path\n  source \"$SHELLY_DIR/shelly-env/bin/activate\"\n  set -a\n  [ -f \"$SHELLY_DIR/.env\" ] \u0026\u0026 source \"$SHELLY_DIR/.env\"\n  set +a\n  python3 \"$SHELLY_DIR/shelly.py\" \"$@\"  # Add --plugins default to auto-load your plugins/default.md\n  deactivate\n}\n```\n\nFinally, you will need to place your API key in your environment, in a `.env` file in the `shelly` folder, or [directly into llm](https://llm.datasette.io/en/latest/setup.html#api-keys):\n\n```sh\n# Optionally, register your API key\necho \"OPENAI_API_KEY=your-api-key-here\" \u003e .env\n```\n\nShelly defaults to OpenAI models, but you can easily switch to [most model providers](https://llm.datasette.io/en/latest/plugins/directory.html) ([Anthropic](https://github.com/simonw/llm-anthropic), [Gemini](https://github.com/simonw/llm-gemini), [local models](https://llm.datasette.io/en/latest/plugins/directory.html#local-models), etc.) by installing the corresponding [llm plugin](https://llm.datasette.io/en/latest/plugins/installing-plugins.html), changing the model name in [`config.json`](./config.json), and adding the proper API key (if any) to your environment.\n\n## Usage\n\nStart an interactive session:\n\n```sh\n$ shelly\n🐚 Shelly: Hi! I'm Shelly, your terminal assistant. Ask me to help you run any shell commands!\nYou: find all python files modified in the last week\n🐚 Shelly: I'll search for Python files modified in the last 7 days...\n```\n\nOr run one-off commands:\n\n```sh\n$ shelly find all Python files modified in the last week\n$ shelly what's eating up disk space in my home directory?\n$ shelly set up a new git repo with a Python .gitignore\n```\n\nSafe commands (`ls`, `cat`, `grep`, etc.) run automatically. Everything else asks for confirmation first. You can always say no and explain why, Shelly will adjust.\n\nShelly automatically looks up manual pages for complex commands to ensure accurate parameter usage, especially for system-specific tools like `ffmpeg`, `slurm`, and `docker`.\n\nYou can also provide Shelly with custom instructions (defined as markdown files in the [plugins/](./plugins/) directory) about your preferred tools and workflows, using the `--plugins` (or `-p`) flag:\n\n```sh\n# Use specific plugin\n$ shelly --plugins ffmpeg convert this video to mp4\n\n# Load multiple plugin files\n$ shelly --plugins git,docker,kubernetes set up a containerized app with CI/CD\n```\n\nEdit [`config.json`](./config.json) to change the model (defaults to `gpt-4.1-mini`) or customize which commands run without confirmation.\n\n\u003e ⚠️ **Privacy Note:** By default, Shelly processes your requests, which might include your recent shell history, through the model's API. If privacy is a concern, you will want to [switch to a local model](https://llm.datasette.io/en/latest/plugins/directory.html#local-models).\n\n## TODO\n\n* shelly seem to remove the current python env when started then killed, why?\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnestordemeure%2Fshelly","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnestordemeure%2Fshelly","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnestordemeure%2Fshelly/lists"}