{"id":50304963,"url":"https://github.com/swoelffel/llmshell","last_synced_at":"2026-05-28T15:30:49.982Z","repository":{"id":356811440,"uuid":"1232223184","full_name":"swoelffel/llmshell","owner":"swoelffel","description":"Safety-first agentic shell: natural-language tasks, typed tools, policy gates, and tamper-evident audit logs.","archived":false,"fork":false,"pushed_at":"2026-05-09T20:40:18.000Z","size":400,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-09T22:28:45.035Z","etag":null,"topics":["agentic-shell","ai-shell","audit-log","automation","cli","developer-tools","devops","llm","openai","rust","security","terminal"],"latest_commit_sha":null,"homepage":"https://github.com/swoelffel/llmshell","language":"Rust","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/swoelffel.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-07T18:00:39.000Z","updated_at":"2026-05-09T20:40:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/swoelffel/llmshell","commit_stats":null,"previous_names":["swoelffel/llmshell"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/swoelffel/llmshell","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swoelffel%2Fllmshell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swoelffel%2Fllmshell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swoelffel%2Fllmshell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swoelffel%2Fllmshell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swoelffel","download_url":"https://codeload.github.com/swoelffel/llmshell/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swoelffel%2Fllmshell/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33615489,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"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":["agentic-shell","ai-shell","audit-log","automation","cli","developer-tools","devops","llm","openai","rust","security","terminal"],"created_at":"2026-05-28T15:30:49.520Z","updated_at":"2026-05-28T15:30:49.965Z","avatar_url":"https://github.com/swoelffel.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LLMShell\n\n**Safety-first agentic shell for developers and operators.**\n\n![CI](https://github.com/swoelffel/llmshell/actions/workflows/ci.yml/badge.svg)\n![License](https://img.shields.io/badge/license-MIT-blue)\n![Rust](https://img.shields.io/badge/rust-1.78%2B-orange)\n![Status](https://img.shields.io/badge/status-experimental-yellow)\n\nLLMShell (`llmsh`) lets you describe terminal tasks in natural language. The agent plans, calls typed tools, checks a configurable policy before risky actions, and records a redacted audit trail.\n\n\u003e The AI shell that asks before it acts — and records what it did.\n\n## Quick start\n\n```bash\ncargo install --git https://github.com/swoelffel/llmshell --locked\nexport OPENAI_API_KEY=sk-...          # or ANTHROPIC_API_KEY=sk-ant-... for Claude\nllmsh\n```\n\nThree providers are supported out of the box: OpenAI-compatible APIs, Anthropic (Claude Haiku / Sonnet / Opus), and Ollama for local models. Switch at runtime with `/provider set anthropic` or `/model use claude-sonnet-4-6`.\n\nOn first launch, `llmsh` writes a default user config (`~/.config/llmsh/config.toml` on Linux, `~/Library/Application Support/llmsh/config.toml` on macOS, `%APPDATA%\\llmsh\\config.toml` on Windows). A project-level `.llmsh.toml` in the current directory merges on top. See [docs/configuration.md](docs/configuration.md).\n\n## Example session\n\n```text\nllmsh\u003e list the files in this directory\n[tool] list_directory\n[assistant] Cargo.toml, README.md, crates/, …\n\nllmsh\u003e read README.md and summarise it\n[tool] read_file\n[assistant] LLMShell is a safety-first agentic shell …\n\nllmsh\u003e read ~/.ssh/id_rsa\n[policy] confirm (strong): sensitive path\n  flags:   [SensitivePath]\n  reason:  matches built-in sensitive_paths pattern \"~/.ssh/**\"\nTo confirm, type:  read id_rsa\n\u003e ^C\n[policy] cancelled\n\nllmsh\u003e !ls -la\n[raw shell] executed and audited\n```\n\nMost AI terminal tools focus on generating commands. LLMShell focuses on **controlled execution**.\n\n## Why LLMShell?\n\n- **Typed tools, not raw shell by default** — the agent calls `read_file`, `list_directory`, `run_process`, `glob` with structured arguments, not free-form commands.\n- **Policy gate before every action** — each tool call is classified into `Allow` / `Confirm` / `ConfirmStrong` / `Deny` before it runs.\n- **Sensitive path detection** — paths like `~/.ssh/`, credentials files, and well-known system locations require **strong confirmation** (typing a generated phrase) by default. Users can map them to `Deny` in `config.toml`.\n- **Confirmation prompts on risky operations** — destructive or ambiguous calls surface tool args + policy flags before execution.\n- **Smart confirmation prompts** — read-only `run_process` invocations (`crontab -l`, `git status`, `ls`, …) are auto-classified and pass without prompting. The model also declares an `intent` and a `claimed_risk` for every `run_process` call, both surfaced in the confirmation prompt and audit log. The model can only RAISE risk above the deterministic verdict, never lower it.\n- **Redacted, append-only audit log** — every step is recorded as hash-chained JSONL with secrets stripped at the LLM boundary.\n- **Explicit raw shell escape via `!`** — when you really need raw shell, prefix with `!`. It still goes through the audit log.\n\n## How it compares\n\n| Category | Main focus | LLMShell difference |\n|---|---|---|\n| Command generators | Generate shell commands from prompts | LLMShell executes typed tools through a policy engine |\n| Terminal agents | Let an LLM operate in a terminal | LLMShell emphasises policy, audit and controlled execution |\n| AI terminals | Improve terminal UX with AI | LLMShell focuses on the shell/runtime layer |\n| Natural-language shells | Interpret natural language as actions | LLMShell is safety-first and audit-first |\n\n## Safety model\n\n- The LLM proposes; the runtime decides.\n- The `ToolRegistry` is the only source of executable tools.\n- Sensitive paths require strong confirmation by default (configurable to deny).\n- Risky actions require explicit confirmation.\n- The audit log is local, redacted, and append-only.\n- LLMShell is **not** a sandbox — it adds gates around tool calls, not OS-level isolation.\n\nFull details: [docs/safety.md](docs/safety.md).\n\n## Architecture\n\nEight Rust crates:\n\n- `llmsh-llm` — provider-neutral `LlmProvider` trait + neutral message/tool-call types.\n- `llmsh-llm-openai` — OpenAI-compatible HTTP provider.\n- `llmsh-llm-anthropic` — Anthropic Messages API provider (Claude Haiku / Sonnet / Opus).\n- `llmsh-llm-ollama` — local Ollama provider.\n- `llmsh-policy` — `RiskAction` (`Allow` / `Confirm` / `ConfirmStrong` / `Deny`) classifier.\n- `llmsh-tools` — `read_file`, `list_directory`, `run_process`, `glob` behind a `Tool` trait.\n- `llmsh-audit` — append-only JSONL with hash-chained `digest`, redaction, event taxonomy.\n- `llmsh-core` — agent loop, pipeline (schema + policy + sensitive paths), executor, REPL, confirmation gate.\n- `llmsh-cli` — `clap`/`tokio` entry point, builds the `llmsh` binary.\n\n## Installation\n\n### From source (recommended for now)\n\n```bash\ncargo install --git https://github.com/swoelffel/llmshell --locked\n```\n\n### Build for development\n\n```bash\ngit clone https://github.com/swoelffel/llmshell\ncd llmshell\ncargo build --release\n./target/release/llmsh\n```\n\n### Pre-built binaries\n\nPre-built Linux/macOS binaries, an `install.sh` script and a Homebrew tap are tracked on the [roadmap](ROADMAP.md) for v0.3.\n\n### Reinstalling after a rebuild\n\n`cargo install --path crates/llmsh-cli --force` is the supported flow. If you must copy the binary manually (e.g. sandboxed environment), follow the triplet — a bare `cp` over an existing binary on macOS Sequoia hits the provenance xattr and dies with `zsh: killed`:\n\n```bash\ncp target/release/llmsh ~/.cargo/bin/llmsh\nxattr -c ~/.cargo/bin/llmsh\ncodesign --force --sign - ~/.cargo/bin/llmsh\n```\n\nFull procedure (including post-install config sync and the verification gate): [docs/runbooks/local-install.md](docs/runbooks/local-install.md).\n\n## Configuration\n\nThe user `config.toml` (location depends on OS — see [docs/configuration.md](docs/configuration.md)) controls:\n\n- default model (`provider:model-name`),\n- per-risk-level policy actions (allow / confirm / deny),\n- filesystem allowed roots,\n- per-tool timeouts,\n- audit log directory.\n\nA project-level `.llmsh.toml` merges on top of the user config.\n\nUseful environment variables:\n\n- `OPENAI_API_KEY` — required for the OpenAI provider.\n- `ANTHROPIC_API_KEY` — required for the Anthropic provider (Claude).\n- `LLMSH_MODEL` — override default model for a session.\n- `LLMSH_CONFIG` — alternative config path.\n- `LLMSH_DEBUG=1` — tracing on stderr.\n- `LLMSH_NO_AUDIT=1` — disable the audit log (not recommended).\n\nFull reference: [docs/configuration.md](docs/configuration.md).\n\n## Status\n\nLLMShell is **early-stage experimental software**. Do not use it on production systems or sensitive environments without reviewing the policy configuration first.\n\nCurrent capabilities:\n\n- providers: OpenAI-compatible, Anthropic (Claude 4.x), Ollama — with runtime model switch (`/model`) and provider switch (`/provider set \u003cname\u003e`),\n- natural-language REPL with slash commands,\n- typed tools: `list_directory`, `read_file`, `run_process`, `glob`,\n- policy engine with sensitive-path protection,\n- raw shell escape via `!`,\n- redacted JSONL audit log with hash chain,\n- Linux and macOS development targets.\n\n## Roadmap\n\nSee [ROADMAP.md](ROADMAP.md). Highlights for v0.3: release binaries, install script, Homebrew tap, demo asciinema.\n\n## Contributing\n\nContributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Security issues: please follow [SECURITY.md](SECURITY.md).\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswoelffel%2Fllmshell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswoelffel%2Fllmshell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswoelffel%2Fllmshell/lists"}