Gaunt Sloth Documentation

Gaunt Sloth (gth) is a local-first, terminal-native AI assistant for code review, PR analysis, agentic coding, and agent evaluation. It runs on your machine against whatever model you point it at — Anthropic, Google, OpenAI, Groq, xAI, OpenRouter, or a local Ollama / LM Studio endpoint — with every prompt in plain markdown and no vendor lock-in.

Install

npm install -g gaunt-sloth@alpha
gth init

Set the provider’s key (ANTHROPIC_API_KEY, GEMINI_API_KEY, …) and you’re ready. The full setup — providers, MCP servers, tools, and identity profiles — lives in Configuration.

When called without parameters, Gaunt Sloth starts in interactive code mode, allowing you to chat and write code.

gth

If gth is called without parameters and neither a current project nor a global configuration is available, it starts an interactive initialization sequence.

Review code and pull requests

Reviews are stateless — nothing carries over between runs, so the verdict can’t be argued down — and can pull requirements straight from a GitHub or Jira issue. A failing review exits non-zero, so it drops cleanly into CI to post results as PR comments.

git --no-pager diff | gth review     # review the working diff
gth pr 42                            # review PR #42 (its linked issue becomes the requirements)
gth pr 42 PROJ-123 -p jira           # ...or pull requirements from a Jira issue

Ask, chat, and write code

A one-shot question, a running conversation, or a full interactive coding session with read access to your project files.

gth ask "what does this module do?" -f src/utils.js
gth code "refactor the auth module to use the new token store"

Guide: Work interactively.

Prove your agents actually work

gth eval grades a whole running agent, not a prompt in isolation, against YAML suites. The assertions are deterministic — which tools were must_called, whether a call must_errored, a tool_result_json_path over the returned payload, plus regex / JSON-path on the answer — with an optional LLM judge. One pass/fail exit code gates CI like any other test.

gth eval eval/authz-matrix.yaml      # exit 0 iff every case passed

Add an identities: matrix to run each case once per profile — the way to test authorization and data-isolation, asserting a privileged profile reaches a tool while a restricted one is denied.

Start with Evaluate your agent; the worked end-to-end example is Evals for MCP servers.

Make it yours

Swap models and providers from config with zero code changes, define named identity profiles (each with its own model, keys, and tools) and switch with -i, and extend the agent with custom shell tools, MCP servers, and A2A agents.

gth ask "summarize the architecture" -i review-gemini   # run under a named profile

See Commands for every verb and Configuration for the full config surface.