{"id":35182706,"url":"https://github.com/galvanized-pukeko/gaunt-sloth-assistant","last_synced_at":"2026-03-05T03:03:01.103Z","repository":{"id":288040948,"uuid":"966618770","full_name":"Galvanized-Pukeko/gaunt-sloth-assistant","owner":"Galvanized-Pukeko","description":"CLI AI assistant doing your code reviews","archived":false,"fork":false,"pushed_at":"2026-03-02T08:05:24.000Z","size":3271,"stargazers_count":12,"open_issues_count":17,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-02T10:46:03.305Z","etag":null,"topics":["ai","cli"],"latest_commit_sha":null,"homepage":"https://gaunt-sloth-assistant.github.io/","language":"TypeScript","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/Galvanized-Pukeko.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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-04-15T07:43:38.000Z","updated_at":"2026-03-02T08:04:05.000Z","dependencies_parsed_at":"2025-12-31T10:02:48.766Z","dependency_job_id":null,"html_url":"https://github.com/Galvanized-Pukeko/gaunt-sloth-assistant","commit_stats":null,"previous_names":["andruhon/gaunt-sloth-assistant","galvanized-pukeko/gaunt-sloth-assistant"],"tags_count":96,"template":false,"template_full_name":null,"purl":"pkg:github/Galvanized-Pukeko/gaunt-sloth-assistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Galvanized-Pukeko%2Fgaunt-sloth-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Galvanized-Pukeko%2Fgaunt-sloth-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Galvanized-Pukeko%2Fgaunt-sloth-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Galvanized-Pukeko%2Fgaunt-sloth-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Galvanized-Pukeko","download_url":"https://codeload.github.com/Galvanized-Pukeko/gaunt-sloth-assistant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Galvanized-Pukeko%2Fgaunt-sloth-assistant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30107642,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T01:39:18.192Z","status":"online","status_checked_at":"2026-03-05T02:00:06.710Z","response_time":93,"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":["ai","cli"],"created_at":"2025-12-29T03:30:48.909Z","updated_at":"2026-03-05T03:03:01.092Z","avatar_url":"https://github.com/Galvanized-Pukeko.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gaunt Sloth Assistant\n[![Tests and Lint](https://github.com/Galvanized-Pukeko/gaunt-sloth-assistant/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/Galvanized-Pukeko/gaunt-sloth-assistant/actions/workflows/unit-tests.yml) [![Integration Tests](https://github.com/Galvanized-Pukeko/gaunt-sloth-assistant/actions/workflows/integration-tests.yml/badge.svg?event=push)](https://github.com/Galvanized-Pukeko/gaunt-sloth-assistant/actions/workflows/integration-tests.yml)\n\nGaunt Sloth Assistant is a lightweight command-line AI code review tool that also provides general-purpose AI capabilities.\nBuilt with TypeScript and distributed via NPM, Gaunt Sloth maintains minimal dependencies for easy integration.\n\n![GSloth Banner](assets/gaunt-sloth-logo.png)\n\nBased on [LangChain.js](https://github.com/langchain-ai/langchainjs)\n\n[Documentation](https://gaunt-sloth-assistant.github.io/docs/) | [Official Site](https://gaunt-sloth-assistant.github.io/) | [NPM](https://www.npmjs.com/package/gaunt-sloth-assistant) | [GitHub](https://github.com/Galvanized-Pukeko/gaunt-sloth-assistant)\n\n## Why?\n\nGaunt Sloth's promise is that it is small, extendable, cross-platform and can itself be a dependency in your project.\n\nThe GSloth was initially built as a code review tool, fetching PR contents and Jira contents before feeding them to\nthe LLM, but we ourselves found many more use cases which we initially did not anticipate; for example,\nwe may have it as a dependency in an MCP project, allowing us to quickly spin it up to simulate or test some use cases.\n\nThe promise of Gaunt Sloth:\n\n- **Minimum dependencies**. Ideally, we aim to only have CommanderJS and some packages from LangChainJS and LangGraphJS.\n- **Extensibility**. Feel free to write some JS and create your Tool, Provider or connect to the MCP server of your choice.\n- **No vendor lock-in**. Just BYO API keys.\n- **Easy installation via NPM**.\n- **All prompts are editable** via markdown files.\n- **No UI**. Command Line only, with intent to be used in build pipeline, or as a dependency to help in nodejs projects.\n\n## What GSloth does:\n\n- Reviews code;\n  - Suggests bug fixes;\n  - Explains provided code\n- Reviews Diffs provided with pipe (|);\n  - You can ask GSloth to review your own code before committing (`git --no-pager diff | gsloth review`).\n- Reviews Pull Requests (PRs) (`gsloth pr 42`);\n  - Fetches descriptions (requirements) from Github issue or Jira (`gsloth pr 42 12`);;\n- Answers questions about provided code;\n- Writes code;\n- Connects to MCP server (including remote MCP with OAuth);\n- Executes custom shell commands (deployments, migrations, tests, etc.) with security validation;\n- Saves all responses in timestamped `.md` files (override with `-w/--write-output-to-file`);\n- Anything else you need, when combined with other command line tools.\n\n### To make GSloth work, you need an **API key** from some AI provider, such as:\n\n- OpenRouter\n- Groq;\n- DeepSeek;\n- Google AI Studio and Google Vertex AI;\n- Anthropic;\n- OpenAI (and other providers using OpenAI format, such as Inception);\n- Local AI: LM Studio, Ollama, llama.cpp (Via OpenAI compatibitlity)\n- Ollama with JS config (some of the models, see https://github.com/Galvanized-Pukeko/gaunt-sloth-assistant/discussions/107)\n- xAI;\n\n`*` Any other provider supported by LangChain.JS should also work with [JS config](./docs/CONFIGURATION.md#javascript-configuration).\n\n## Commands Overview\n\n`gth` and `gsloth` commands are used interchangeably, both `gsloth pr 42` and `gth pr 42` do the same thing.\n\nFor detailed information about all commands, see [docs/COMMANDS.md](./docs/COMMANDS.md).\n\n### Global Flags\n\nThese apply to every command:\n- `--config \u003cpath\u003e` – load a specific config file without moving directories\n- `-i, --identity-profile \u003cname\u003e` – switch to another profile under `.gsloth/.gsloth-settings/\u003cname\u003e/`\n- `-w, --write-output-to-file \u003cvalue\u003e` – control response files (`true` by default, use `-wn`/`-w0` for false, or pass a filename)\n- `--verbose` – enable verbose LangChain/LangGraph logs (useful when debugging prompts)\n\n### Available Commands:\n\n- **`init`** - Initialize Gaunt Sloth in your project (auto-detects API keys when called without arguments)\n- **`pr`** - ⚠️ This feature requires GitHub CLI to be installed. Review pull requests with optional requirement integration (GitHub issues or Jira).\n- **`review`** - Review any diff or content from various sources\n- **`ask`** - Ask questions about code or programming topics\n- **`chat`** - Start an interactive chat session\n- **`code`** - Write code interactively with full project context\n\n### Quick Examples:\n\n**Initialize project:**\n```bash\ngsloth init              # Auto-detect API keys and select provider\ngsloth init anthropic    # Or specify provider directly\n```\n\n**Review PR with requirements:**\n```bash\ngsloth pr 42 23  # Review PR #42 with GitHub issue #23\n```\n\n**Review local changes:**\n```bash\ngit --no-pager diff | gsloth review\n```\n\n**Review changes between a specific tag and the HEAD:**\n```bash\ngit --no-pager diff v0.8.3..HEAD | gth review\n```\n\n**Review diff between head and previous release and head using a specific requirements provider (GitHub issue 38), not the one which is configured by default:\n```bash\ngit --no-pager diff v0.8.10 HEAD | npx gth review --requirements-provider github -r 38\n```\n\n**Ask questions:**\n```bash\ngsloth ask \"What does this function do?\" -f utils.js\n```\n\n**Write release notes:**\n```bash\ngit --no-pager diff v0.8.3..HEAD | gth ask \"inspect existing release notes in assets/release-notes/v0_8_2.md; inspect provided diff and write release notes to v0_8_4.md\"\n```\n\nTo write this to filesystem, you'd need to add filesystem access to the *ask* command in `.gsloth.config.json`.\n\n```json\n{\"llm\": {\"type\": \"vertexai\", \"model\": \"gemini-2.5-pro\"}, \"commands\": {\"ask\": {\"filesystem\": \"all\"}}}\n```\n\n*You can improve this significantly by modifying project guidelines in `.gsloth.guidelines.md` or maybe with keeping instructions in file and feeding it in with `-f`.\n\n\n**Interactive sessions:**\n```bash\ngsloth chat  # Start chat session\ngsloth code  # Start coding session\n```\nRunning `gsloth` with no subcommand also drops you into `chat`.\n\n## Installation\n\nTested with Node 22 LTS.\n\n### NPM\n```bash\nnpm install gaunt-sloth-assistant -g\n```\n\n## Configuration\n\n\u003e Gaunt Sloth currently only functions from the directory which has a configuration file (`.gsloth.config.js`, `.gsloth.config.json`, or `.gsloth.config.mjs`) and `.gsloth.guidelines.md`. Configuration files can be located in the project root or in the `.gsloth/.gsloth-settings/` directory.\n\u003e\n\u003e You can also specify a path to a configuration file directly using the `-c` or `--config` global flag, for example `gth -c /path/to/your/config.json ask \"who are you?\"`\n\u003e Note, however, is that project guidelines are going to be used from current directory if they exist and simple install dir prompt is going to be used if nothing found.\n\nConfiguration can be created with `gsloth init [vendor]` command.\nCurrently, openrouter, anthropic, groq, deepseek, openai, google-genai, vertexai and xai can be configured with `gsloth init [vendor]`.\nFor OpenAI-compatible providers like Inception, use `gsloth init openai` and modify the configuration.\n\nMore detailed information on configuration can be found in [CONFIGURATION.md](./docs/CONFIGURATION.md)\n\nGaunt Sloth also supports `.aiignore` for excluding files from filesystem tools, with overrides via config.\n\n### Custom Tools\n\nGaunt Sloth supports defining custom shell commands that the AI can execute. These custom tools:\n- Work across all commands (`pr`, `review`, `code`, `ask`, `chat`)\n- Can be configured globally or per-command\n- Support parameters with security validation\n- Are useful for deployments, migrations, automation, and more\n\n**Example configuration:**\n```json\n{\n  \"llm\": {\"type\": \"vertexai\", \"model\": \"gemini-2.5-pro\"},\n  \"customTools\": {\n    \"deploy\": {\n      \"command\": \"npm run deploy\",\n      \"description\": \"Deploy the application\"\n    },\n    \"run_migration\": {\n      \"command\": \"npm run migrate -- ${name}\",\n      \"description\": \"Run a database migration\",\n      \"parameters\": {\n        \"name\": {\"description\": \"Migration name\"}\n      }\n    }\n  }\n}\n```\n\nSee [Custom Tools Configuration](./docs/CONFIGURATION.md#custom-tools-configuration) for complete documentation.\n\n### Google GenAI (AI Studio)\n\n```bash\ncd ./your-project\ngsloth init google-genai\n```\nMake sure you either define `GOOGLE_API_KEY` environment variable or edit your configuration file and set up your key.\nIt is recommended to obtain API key from Google AI Studio official website rather than from a reseller.\n\n### Google Vertex AI\n\n```bash\ncd ./your-project\ngsloth init vertexai\ngcloud auth login\ngcloud auth application-default login\n```\n\nAs of 19 Nov 2025, Gemini 3 on Vertex AI works with `global` and `us-central1` locations when using the default `aiplatform.googleapis.com` endpoint.\nHowever, regional endpoints (e.g., `us-central-aiplatform.googleapis.com`) currently return 404 for Gemini 3.\nExample config:\n```json\n{\n  \"llm\": {\n    \"type\": \"vertexai\",\n    \"model\": \"gemini-3-pro-preview\",\n    \"location\": \"global\"\n  }\n}\n```\n\n### Open Router\n\n```bash\ncd ./your-project\ngsloth init openrouter\n```\n\nMake sure you either define `OPEN_ROUTER_API_KEY` environment variable or edit your configuration file and set up your key.\n\n### Anthropic\n\n```bash\ncd ./your-project\ngsloth init anthropic\n```\n\nMake sure you either define `ANTHROPIC_API_KEY` environment variable or edit your configuration file and set up your key.\n\n### Groq\n```bash\ncd ./your-project\ngsloth init groq\n```\nMake sure you either define `GROQ_API_KEY` environment variable or edit your configuration file and set up your key.\n\n### DeepSeek\n```bash\ncd ./your-project\ngsloth init deepseek\n```\nMake sure you either define `DEEPSEEK_API_KEY` environment variable or edit your configuration file and set up your key.\nIt is recommended to obtain API key from DeepSeek official website rather than from a reseller.\n\n### OpenAI\n```bash\ncd ./your-project\ngsloth init openai\n```\nMake sure you either define `OPENAI_API_KEY` environment variable or edit your configuration file and set up your key.\n\n### LM Studio\nLM Studio provides a local OpenAI-compatible server for running models on your machine:\n```bash\ncd ./your-project\ngsloth init openai\n```\nThen edit your configuration file to point to LM Studio (default: `http://127.0.0.1:1234/v1`).\nUse any string for the API key (e.g., `\"none\"`) - LM Studio doesn't validate it.\n\n**Important:** The model must support tool calling. Tested models include gpt-oss, granite, nemotron, seed, and qwen3.\n\nSee [CONFIGURATION.md](./docs/CONFIGURATION.md#lm-studio) for detailed setup.\n\n### OpenAI-compatible providers (Inception, etc.)\nFor providers using OpenAI-compatible APIs:\n```bash\ncd ./your-project\ngsloth init openai\n```\nThen edit your configuration to add custom base URL and API key. See [CONFIGURATION.md](./docs/CONFIGURATION.md) for examples.\n\n### xAI\n```bash\ncd ./your-project\ngsloth init xai\n```\nMake sure you either define `XAI_API_KEY` environment variable or edit your configuration file and set up your key.\n\n### Other AI providers\nAny other AI provider supported by Langchain.js can be configured with js [Config](./docs/CONFIGURATION.md).\nFor example, Ollama can be set up with JS config (some of the models, see https://github.com/Galvanized-Pukeko/gaunt-sloth-assistant/discussions/107)\n\n### JavaScript Configuration with Custom Middleware and Tools\nJavaScript configs enable advanced customization including custom middleware and tools that aren't available in JSON configs. See the [JavaScript config example](./examples/js-config/README.md) for a complete demonstration of creating custom logging middleware and custom tools.\n\n## Integration with GitHub Workflows / Actions\n\nExample GitHub workflows integration can be found in [.github/workflows/review.yml;](.github/workflows/review.yml)\nthis example workflow performs AI review on any pushes to Pull Request, resulting in a comment left by,\nGitHub actions bot.\n\n## MCP (Model Context Protocol) Servers\n\nGaunt Sloth supports connecting to MCP servers, including those requiring OAuth authentication.\n\nThis has been tested with the Atlassian Jira MCP server.\nSee the [MCP configuration section](./docs/CONFIGURATION.md#model-context-protocol-mcp) for detailed setup instructions, or the [Jira MCP example](./examples/jira-mcp) for a working configuration.\n\nIf you experience issues with the MCP auth try finding `.gsloth` dir in your home directory,\nand delete JSON file matching the server you are trying to connect to,\nfor example for atlassian MCP the file would be `~/.gsloth/.gsloth-auth/mcp.atlassian.com_v1_sse.json`\n\n## A2A (Agent-to-Agent) Protocol Support (Experimental)\n\nGaunt Sloth supports the [A2A protocol](https://a2a-protocol.org/) for connecting to external AI agents. See [CONFIGURATION.md](./docs/CONFIGURATION.md#a2a-agent-to-agent-protocol-support-experimental) for setup instructions.\n\n## Uninstall\nUninstall global NPM package:\n```bash\nnpm uninstall -g gaunt-sloth-assistant\n```\n\nRemove global config (if any)\n```bash\nrm -r ~/.gsloth\n```\n\nRemove configs from project (if necessary)\n```bash\nrm -r ./.gsloth*\n```\n\n## Contributing\nContributors are needed! Feel free to create a PR.\nIf you are not sure where to start, look for issues with a \"good first issue\" label.\n\n## Building from repo\nSee [DEVELOPMENT.md](./docs/DEVELOPMENT.md)\n\n## License\nLicense is [MIT](https://opensource.org/license/mit). See [LICENSE](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgalvanized-pukeko%2Fgaunt-sloth-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgalvanized-pukeko%2Fgaunt-sloth-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgalvanized-pukeko%2Fgaunt-sloth-assistant/lists"}