{"id":50444283,"url":"https://github.com/dotcommander/shoop","last_synced_at":"2026-05-31T20:32:06.177Z","repository":{"id":350575274,"uuid":"1204385473","full_name":"dotcommander/shoop","owner":"dotcommander","description":"A minimal agentic coding assistant in pure bash — zero dependencies beyond curl and jq","archived":false,"fork":false,"pushed_at":"2026-04-11T01:02:55.000Z","size":44,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-11T02:24:19.584Z","etag":null,"topics":["agent","ai-agent","bash","cli","coding-assistant","curl","llm","openai","shell","terminal"],"latest_commit_sha":null,"homepage":null,"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/dotcommander.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-08T00:53:18.000Z","updated_at":"2026-04-11T01:02:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dotcommander/shoop","commit_stats":null,"previous_names":["dotcommander/shoop"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/dotcommander/shoop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotcommander%2Fshoop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotcommander%2Fshoop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotcommander%2Fshoop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotcommander%2Fshoop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dotcommander","download_url":"https://codeload.github.com/dotcommander/shoop/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotcommander%2Fshoop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33748607,"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-31T02:00:06.040Z","response_time":95,"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","ai-agent","bash","cli","coding-assistant","curl","llm","openai","shell","terminal"],"created_at":"2026-05-31T20:32:03.381Z","updated_at":"2026-05-31T20:32:06.172Z","avatar_url":"https://github.com/dotcommander.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# shoop\n\nA coding agent in pure bash. Send a prompt, watch it execute shell commands, read and write files, and search code — looping until the task is done.\n\n```bash\nshoop \"add error handling to cmd/main.go\"\n```\n\n```\n--- shoop 20260410-185653-18845 (model: openai/gpt-5.4-mini) ---\n\n─── turn 1/25 · 312 tokens ───\n  [read_file] cmd/main.go\n...\n\n─── turn 4/25 · 1842 tokens ───\nDone. Added error handling to all three entry points.\n\n--- shoop done ---\n  4 turns, 1842 tokens\n```\n\nDependencies: `bash`, `curl`, `jq`\n\n---\n\n## Install\n\n```bash\ngit clone https://github.com/dotcommander/shoop\ncd shoop\nchmod +x shoop.sh\nln -sf \"$(pwd)/shoop.sh\" ~/bin/shoop\n```\n\n---\n\n## Quick Start\n\n```bash\n# Set your API key (OpenRouter, or any OpenAI-compatible provider)\nexport OPENROUTER_API_KEY=sk-or-...\n\n# Run a task\nshoop \"refactor the auth package\"\n\n# Pipe a prompt from stdin\necho \"fix the failing tests\" | shoop\n\n# Use a specific model\nshoop --model anthropic/claude-sonnet-4 \"add input validation\"\n\n# Resume a previous session\nshoop sessions                          # list saved sessions\nshoop resume 20260410-185653            # resume by ID prefix\nshoop resume \"fix the bug\"             # resume by prompt search\n```\n\n---\n\n## Commands\n\n| Command | Aliases | Description |\n|---------|---------|-------------|\n| `shoop \"prompt\"` | | Run a task |\n| `shoop sessions` | `list`, `ls`, `history` | List saved sessions |\n| `shoop resume \u003cid\u003e [\"prompt\"]` | | Resume a session (by ID, prefix, or prompt text) |\n| `shoop config show` | `config print` | Print current config (API key redacted) |\n| `shoop config edit` | | Open config in `$EDITOR` |\n| `shoop undo` | | Revert the last checkpoint commit |\n| `shoop help` | `--help`, `-h` | Show usage |\n| `shoop --version` | `version` | Print version |\n\n---\n\n## Flags\n\n| Flag | Description |\n|------|-------------|\n| `--model NAME` | Model to use |\n| `--api URL` | API endpoint |\n| `--key KEY` | API key (overrides config and env) |\n| `--zai` | Use z.ai coding API with `ZAI_API_KEY` |\n| `--no-rewrite` | Skip CRISP prompt enhancement |\n| `--no-confirm` | Skip confirmation for write/replace/fetch (`run_shell` always confirms) |\n| `--checkpoint` | Git-commit working tree before the agent runs |\n\n---\n\n## Config\n\nOn first run, shoop creates `~/.config/shoop/config`:\n\n```bash\nMODEL=openai/gpt-5.4-mini\nAPI=https://openrouter.ai/api/v1/chat/completions\nAPI_KEY=\nMAX_TURNS=25\nCONFIRM=1\nREWRITE=1\nFORMAT_CMD=\nCHECKPOINT=0\n```\n\nEdit directly, or use `shoop config edit`.\n\n| Key | Default | Description |\n|-----|---------|-------------|\n| `MODEL` | `openai/gpt-5.4-mini` | Model identifier |\n| `API` | OpenRouter endpoint | Chat completions URL |\n| `API_KEY` | *(empty)* | API key (stored in config) |\n| `MAX_TURNS` | `25` | Maximum agent loop iterations |\n| `CONFIRM` | `1` | Prompt before write/replace/fetch (`run_shell` always prompts) |\n| `REWRITE` | `1` | CRISP prompt enhancement before agent loop |\n| `FORMAT_CMD` | *(empty)* | Formatter run after every write (e.g. `prettier --write`) |\n| `CHECKPOINT` | `0` | Git-commit working tree before each run |\n\n### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `SHOOP_API_KEY` | API key (highest priority) |\n| `SHOOP_CONFIRM=0` | Skip confirmation prompts |\n| `SHOOP_REWRITE=0` | Skip CRISP prompt enhancement |\n| `SHOOP_CHECKPOINT=1` | Enable git checkpoints |\n| `OPENROUTER_API_KEY` | Fallback API key (OpenRouter) |\n| `ZAI_API_KEY` | Fallback API key (z.ai) |\n\n**API key precedence:** `SHOOP_API_KEY` \u003e config `API_KEY` \u003e `OPENROUTER_API_KEY` \u003e `ZAI_API_KEY`\n\n---\n\n## Tools\n\nThe agent has seven tools. Read-only tools run without confirmation. Write and execution tools prompt before acting.\n\n| Tool | Description | Confirmation |\n|------|-------------|--------------|\n| `run_shell` | Execute bash commands (output capped at 200 lines, timeout 1-300s) | Always |\n| `read_file` | Read file contents with optional line range (capped at 200 lines) | No |\n| `write_file` | Write file with diff preview, creates parent directories | Yes |\n| `replace_in_file` | Surgical text replacement via exact match (first occurrence) | Yes |\n| `search_files` | Grep with regex, glob filter, context lines (max 100 result lines) | No |\n| `list_dir` | Directory tree with depth control 1-10 (excludes dotfiles) | No |\n| `web_fetch` | Fetch URL content, converts HTML to text if `lynx`/`w3m` available | Yes |\n\n---\n\n## Providers\n\nWorks with any OpenAI-compatible chat completions API.\n\n**OpenRouter** (default):\n\n```bash\nexport OPENROUTER_API_KEY=sk-or-...\nshoop \"your prompt\"\n```\n\n**z.ai:**\n\n```bash\nexport ZAI_API_KEY=your-key\nshoop --zai \"your prompt\"\n```\n\n**Any compatible API:**\n\n```bash\nshoop --api https://your-api/v1/chat/completions --key sk-... --model your-model \"prompt\"\n```\n\n---\n\n## Sessions\n\nEvery tool result is saved atomically to `~/.local/share/shoop/sessions/`. If a run crashes mid-task, no progress is lost.\n\n```bash\n# List all sessions\nshoop sessions\n\n# Resume by session ID (or prefix)\nshoop resume 20260410-185653\n\n# Resume by searching prompt text\nshoop resume \"fix the auth bug\"\n\n# Resume with a new follow-up prompt\nshoop resume 20260410-185653 \"now add tests for that fix\"\n\n# Resume interactively (shows last response, prompts for input)\nshoop resume 20260410-185653\n```\n\nWhen message history exceeds 30 messages, shoop automatically summarizes older context via the LLM to stay within token limits.\n\n---\n\n## Features\n\n**CRISP Prompt Enhancement** — Before the agent loop, your prompt is rewritten by the LLM to add context, role, and structure. Disable with `--no-rewrite` or `REWRITE=0`.\n\n**Git Checkpoints** — Run with `--checkpoint` (or `CHECKPOINT=1`) to auto-commit the working tree before the agent starts. Revert with `shoop undo`.\n\n**Format Hooks** — Set `FORMAT_CMD` in config (e.g. `FORMAT_CMD=prettier --write`) and shoop runs it after every `write_file` and `replace_in_file`.\n\n**Typo Detection** — Mistyped commands like `sesions` or `confi` are caught and suggest the correct command instead of burning API tokens.\n\n**Path Security** — All file operations are sandboxed to the working directory. Symlink escapes, `.git`/`.env`/`.ssh` access, and path traversal are blocked.\n\n---\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotcommander%2Fshoop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdotcommander%2Fshoop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotcommander%2Fshoop/lists"}