{"id":47269204,"url":"https://github.com/k4yt3x/agsh","last_synced_at":"2026-05-10T02:56:02.365Z","repository":{"id":342179367,"uuid":"1172634088","full_name":"k4yt3x/agsh","owner":"k4yt3x","description":"An agentic shell where you speak human, not bash.","archived":false,"fork":false,"pushed_at":"2026-04-20T04:40:37.000Z","size":1525,"stargazers_count":24,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-20T06:36:52.334Z","etag":null,"topics":["agent","shell"],"latest_commit_sha":null,"homepage":"https://docs.agsh.sh/","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/k4yt3x.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-04T14:29:20.000Z","updated_at":"2026-04-20T04:40:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/k4yt3x/agsh","commit_stats":null,"previous_names":["k4yt3x/agsh"],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/k4yt3x/agsh","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k4yt3x%2Fagsh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k4yt3x%2Fagsh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k4yt3x%2Fagsh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k4yt3x%2Fagsh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/k4yt3x","download_url":"https://codeload.github.com/k4yt3x/agsh/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k4yt3x%2Fagsh/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32161325,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T17:06:48.269Z","status":"ssl_error","status_checked_at":"2026-04-22T17:06:19.037Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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","shell"],"created_at":"2026-03-15T09:23:03.680Z","updated_at":"2026-05-10T02:56:02.358Z","avatar_url":"https://github.com/k4yt3x.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agsh\n\nA general-purpose AI agent runtime.\n\n\u003e [!CAUTION]\n\u003e Agents can perform potentially destructive actions. Exercise caution when granting write permissions. It is not recommended to run agsh on important systems with write permissions enabled.\n\n\u003e [!WARNING]\n\u003e Agents can consume a large number of tokens on complex tasks. If you're on a subscription, be prepared for quota exhaustion; if you are billed per token, it is recommended that you set a spending limit on the API key.\n\n![agsh Screenshot](https://github.com/user-attachments/assets/e94c40ee-76ae-4b00-bcfe-1c1d9d075a2b)\n\n## Overview\n\nagsh is a general-purpose AI agent runtime that provides LLMs with a rich set of tools — web search, shell execution, file editing, and more — to accomplish complex tasks. Use it as a natural-language shell, a system diagnostic helper, a research or data-analysis assistant, for general Q\u0026A, or to add agentic capabilities to other applications.\n\nSupported providers:\n\n- **OpenAI API** — bring your own API key. Also works with any OpenAI-compatible endpoint.\n- **OpenAI Codex** — authenticate with a ChatGPT subscription.\n- **Claude API** — bring your own API key.\n- **Claude OAuth** — authenticate with a Claude subscription.\n\n## Installation\n\nDownload a pre-built binary from [GitHub Releases](https://github.com/k4yt3x/agsh/releases/latest), or install with Cargo:\n\n```bash\ncargo install --locked --git https://github.com/k4yt3x/agsh.git\n```\n\n## Quick Start\n\nRun `agsh setup` for an interactive wizard that picks a provider, runs the OAuth login if applicable, and writes the config for you.\n\nTo configure manually, create `~/.config/agsh/config.toml`. For example, to use OpenRouter with a Claude model:\n\n```toml\n[provider]\nname = \"openai-api\"\nbase_url = \"https://openrouter.ai/api/v1\"\napi_key = \"sk-or-v1-...\"\nmodel = \"anthropic/claude-opus-4.6\"\n```\n\nRun `agsh` and start typing. Press Shift+Tab to cycle permissions (none, read, ask, write):\n\n```\nagsh [r] \u003e find all TODO comments in this project\nagsh [w] \u003e install and start nginx\n```\n\nSee the [documentation](https://k4yt3x.github.io/agsh) for the full usage guide.\n\n## Tools\n\nThe agent has access to the following built-in tools:\n\n- **Shell**: execute commands and read their output\n- **ReadFile / WriteFile / EditFile**: read, create, and modify files\n- **FindFiles**: find files by name or glob pattern\n- **SearchContents**: search file contents with regex (powered by ripgrep)\n- **FetchUrl**: fetch and read web page content\n- **WebSearch**: search the web for up-to-date information\n- **Scratchpad**: session-scoped working memory (write, read, edit, list, delete)\n- **TodoWrite**: structured task tracking for multi-step work\n- **SpawnAgent**: delegate research tasks to a read-only sub-agent\n- **Skill**: load reusable prompt templates on demand\n- **RenderImage**: render an image into the conversation for vision-capable models\n- **MCP resources / prompts**: read or render content from configured MCP servers\n\nLong-output tools support an optional `scratchpad` parameter to save output directly to the scratchpad.\n\n## Permissions\n\nThe prompt indicator shows the current permission mode. Press **Shift+Tab** to cycle between modes:\n\n- `[n]` **none**: no tools available, text-only responses\n- `[r]` **read**: read-only tools (file reading, searching, web, sandboxed shell); cannot modify anything\n- `[a]` **ask**: all tools available, but each call requires user approval\n- `[w]` **write**: all tools enabled, including shell execution and file writes\n\n## Sessions\n\nConversations are persisted in a local SQLite database and can be resumed:\n\n- `agsh -c` continues the last session\n- `agsh -c \u003cUUID\u003e` resumes a specific session by ID\n- `agsh list` lists past sessions\n- `agsh export \u003cUUID\u003e` exports a session as Markdown\n- `/export` exports the current session from within the shell\n- `/compact` summarizes and compacts the session history\n\n## Features\n\n- **Extended/adaptive thinking**: enabled by default for Claude models that support it\n- **Syntax-highlighted output**: bat-powered markdown rendering with code block highlighting\n- **Auto-compact**: automatically compacts the conversation when approaching the context limit\n- **MCP support**: extend the agent with tools from external MCP servers\n- **Skills**: load reusable prompt templates from `~/.config/agsh/skills/`\n\n## Shell Escape\n\nPrefix input with `!` to execute a command directly, bypassing the LLM:\n\n```\nagsh [r] \u003e !uname -a\nagsh [r] \u003e !docker ps\n```\n\nType `exit`, `quit`, or press **Ctrl+D** to leave the shell.\n\n## AI Use Declaration\n\nAI tools were used to assist the design and implementation of this project. All design decisions were made by humans, and every change was reviewed and approved by a human maintainer.\n\n## License\n\nThis project is licensed under the [MIT License](https://opensource.org/licenses/MIT).\\\nCopyright 2026 K4YT3X.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk4yt3x%2Fagsh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fk4yt3x%2Fagsh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk4yt3x%2Fagsh/lists"}