gaunt-sloth-assistant 0.7.1 → 0.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/.gsloth.config_.json +7 -0
  2. package/.gsloth.config_.mjs +15 -0
  3. package/README.md +162 -153
  4. package/assets/release-notes/v0_7_2.md +14 -0
  5. package/dist/config.d.ts +1 -1
  6. package/dist/config.js +3 -3
  7. package/dist/config.js.map +1 -1
  8. package/dist/{configs → presets}/anthropic.js +2 -1
  9. package/dist/{configs → presets}/anthropic.js.map +1 -1
  10. package/dist/presets/deepseek.d.ts +4 -0
  11. package/dist/presets/deepseek.js +33 -0
  12. package/dist/presets/deepseek.js.map +1 -0
  13. package/dist/{configs → presets}/fake.js.map +1 -1
  14. package/dist/{configs → presets}/groq.js +4 -5
  15. package/dist/presets/groq.js.map +1 -0
  16. package/dist/{configs → presets}/vertexai.js +2 -3
  17. package/dist/presets/vertexai.js.map +1 -0
  18. package/docs/CONFIGURATION.md +468 -437
  19. package/it.js +15 -0
  20. package/package.json +13 -14
  21. package/src/config.ts +3 -3
  22. package/src/{configs → presets}/anthropic.ts +4 -1
  23. package/src/presets/deepseek.ts +46 -0
  24. package/src/{configs → presets}/groq.ts +5 -6
  25. package/src/{configs → presets}/vertexai.ts +2 -3
  26. package/vitest-it.config.ts +1 -1
  27. package/dist/configs/groq.js.map +0 -1
  28. package/dist/configs/vertexai.js.map +0 -1
  29. package/dist/core/AgentInterface.d.ts +0 -36
  30. package/dist/core/AgentInterface.js +0 -2
  31. package/dist/core/AgentInterface.js.map +0 -1
  32. package/dist/core/HuggingFaceAgentWrapper.d.ts +0 -20
  33. package/dist/core/HuggingFaceAgentWrapper.js +0 -148
  34. package/dist/core/HuggingFaceAgentWrapper.js.map +0 -1
  35. package/dist/core/LangChainAgentWrapper.d.ts +0 -17
  36. package/dist/core/LangChainAgentWrapper.js +0 -70
  37. package/dist/core/LangChainAgentWrapper.js.map +0 -1
  38. package/examples/huggingface/gth_2025-06-29_01-11-51_ASK.md +0 -1
  39. package/examples/huggingface/gth_2025-06-29_01-17-11_CHAT.md +0 -16
  40. /package/dist/{configs → presets}/anthropic.d.ts +0 -0
  41. /package/dist/{configs → presets}/fake.d.ts +0 -0
  42. /package/dist/{configs → presets}/fake.js +0 -0
  43. /package/dist/{configs → presets}/groq.d.ts +0 -0
  44. /package/dist/{configs → presets}/vertexai.d.ts +0 -0
  45. /package/src/{configs → presets}/fake.ts +0 -0
package/docs/CONFIGURATION.md CHANGED
@@ -1,437 +1,468 @@
1
- # Configuration
2
-
3
- Populate `.gsloth.guidelines.md` with your project details and quality requirements.
4
- A proper preamble is paramount for good inference.
5
- Check [.gsloth.guidelines.md](../.gsloth.guidelines.md) for example.
6
-
7
- Your project should have the following files in order for gsloth to function:
8
- - Configuration file (one of):
9
- - `.gsloth.config.js` (JavaScript module)
10
- - `.gsloth.config.json` (JSON file)
11
- - `.gsloth.config.mjs` (JavaScript module with explicit module extension)
12
- - `.gsloth.guidelines.md`
13
-
14
- > Gaunt Sloth currently only functions from the directory which has one of the configuration files and `.gsloth.guidelines.md`.
15
- > Global configuration to invoke gsloth anywhere is in [ROADMAP](../ROADMAP.md).
16
-
17
- ## Using .gsloth Directory
18
-
19
- For a tidier project structure, you can create a `.gsloth` directory in your project root. When this directory exists, gsloth will:
20
-
21
- 1. Write all output files (like responses from commands) to the `.gsloth` directory instead of the project root
22
- 2. Look for configuration files in `.gsloth/.gsloth-settings/` subdirectory
23
-
24
- Example directory structure when using the `.gsloth` directory:
25
-
26
- ```
27
- .gsloth/.gsloth-settings/.gsloth-config.json
28
- .gsloth/.gsloth-settings/.gsloth.guidelines.md
29
- .gsloth/.gsloth-settings/.gsloth.review.md
30
- .gsloth/gth_2025-05-18_09-34-38_ASK.md
31
- .gsloth/gth_2025-05-18_22-09-00_PR-22.md
32
- ```
33
-
34
- If the `.gsloth` directory doesn't exist, gsloth will continue writing all files to the project root directory as it did previously.
35
-
36
- **Note:** When initializing a project with an existing `.gsloth` directory, the configuration files will be created in the `.gsloth/.gsloth-settings` directory automatically. There is no automated migration for existing configurations - if you create a `.gsloth` directory after initialization, you'll need to manually move your configuration files into the `.gsloth/.gsloth-settings` directory.
37
-
38
- ## Configuration Object
39
-
40
- It is always worth checking sourcecode in [config.ts](../src/config.ts) for more insightful information.
41
-
42
- | Parameter | Required | Default Value | Description |
43
- |------------------------------------------|-----------------------------------|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
44
- | `llm` | Required | - | An object configuring LLM. In JS config could be actual instance of LangChainJS [BaseChatModel](https://v03.api.js.langchain.com/classes/_langchain_core.language_models_chat_models.BaseChatModel.html), allowing to use LLMs which do not have a preset. |
45
- | `llm.type` | Required (when using JSON config) | - | LLM type or provider. Options currently available are `anthropic`, `groq` and `vertexai`. To use other models supported by LangChainJS, please use JavaScript config. |
46
- | `llm.model` | Optional | - | Particular LLM model string (Check in your provider documentation). |
47
- | `llm.apiKey` | Optional | - | API key for the LLM provider. You can either use this parameter or use environment variable. |
48
- | `contentProvider` | Optional | `file` | Default content provider used to get content for review. Options available are `github`, `file` and `text` (`text` provides text as it is). |
49
- | `requirementsProvider` | Optional | `file` | Default requirements provider used to get requirements for review. Options available are `jira`, `jira-legacy`, `github`, `file` and `text`. |
50
- | `projectGuidelines` | Optional | `.gsloth.guidelines.md` | Path to the file containing project guidelines. |
51
- | `projectReviewInstructions` | Optional | `.gsloth.review.md` | Path to the file containing project review instructions. |
52
- | `streamOutput` | Optional | `true` | When set to `true`, AI responses are streamed to the console in real-time. When `false`, responses are displayed only after completion. |
53
- | `filesystem` | Optional | See note | File system access configuration. Options: `'all'`, `'none'`, or an array of specific file operation names. Default is an array of read-only operations: `['read_file', 'read_multiple_files', 'list_directory', 'directory_tree', 'search_files', 'get_file_info', 'list_allowed_directories']`. |
54
- | `commands` | Optional | - | Configuration for specific commands. |
55
- | `commands.pr` | Optional | - | Configuration for the PR command. |
56
- | `commands.pr.contentProvider` | Optional | `github` | Content provider used for PR review (`gsloth pr`). |
57
- | `commands.pr.requirementsProvider` | Optional | `github` | Requirements provider used for PR review. If not specified, falls back to the global `requirementsProvider`. |
58
- | `commands.pr.filesystem` | Optional | - | File system access configuration for PR command. Options: `'all'`, `'none'`, or specific file patterns for read-only access. |
59
- | `commands.review` | Optional | - | Configuration for the review command. |
60
- | `commands.review.contentProvider` | Optional | - | Content provider specifically for the review command. If not specified, falls back to the global `contentProvider`. |
61
- | `commands.review.requirementsProvider` | Optional | - | Requirements provider specifically for the review command. If not specified, falls back to the global `requirementsProvider`. |
62
- | `commands.review.filesystem` | Optional | - | File system access configuration for review command. Options: `'all'`, `'none'`, or specific file patterns for read-only access. |
63
- | `commands.ask` | Optional | - | Configuration for the ask command. |
64
- | `commands.ask.filesystem` | Optional | - | File system access configuration for ask command. Options: `'all'`, `'none'`, or specific file patterns for read-only access. |
65
- | `commands.chat` | Optional | - | Configuration for the chat command (interactive chat sessions). |
66
- | `commands.chat.filesystem` | Optional | - | File system access configuration for chat command. Options: `'all'`, `'none'`, or specific file patterns for read-only access. |
67
- | `commands.code` | Optional | - | Configuration for the code command (interactive coding sessions with file system access). |
68
- | `commands.code.filesystem` | Optional | `all` | File system access configuration for code command. Options: `'all'`, `'none'`, or specific file patterns. Default is `'all'` for full file system access. |
69
- | `requirementsProviderConfig` | Optional | - | Configuration for requirements providers. Contains provider-specific configurations. |
70
- | `requirementsProviderConfig.jira` | Optional | - | Configuration for the Jira requirements provider (Atlassian REST API v3 with Personal Access Token). |
71
- | `requirementsProviderConfig.jira.username` | Optional | - | Jira username (email). Can also be set via JIRA_USERNAME environment variable. |
72
- | `requirementsProviderConfig.jira.token` | Optional | - | Jira Personal Access Token. Can also be set via JIRA_API_PAT_TOKEN environment variable. |
73
- | `requirementsProviderConfig.jira.cloudId` | Required for `jira` | - | Atlassian Cloud ID. Can also be set via JIRA_CLOUD_ID environment variable. |
74
- | `requirementsProviderConfig.jira.displayUrl` | Optional | - | Optional URL for displaying Jira issues (e.g., "https://yourcompany.atlassian.net/browse/"). |
75
- | `requirementsProviderConfig.jira-legacy` | Optional | - | Configuration for the Jira Legacy requirements provider (Atlassian REST API v2 with Legacy API Token). |
76
- | `requirementsProviderConfig.jira-legacy.username` | Optional | - | Jira username (email). Can also be set via JIRA_USERNAME environment variable. |
77
- | `requirementsProviderConfig.jira-legacy.token` | Optional | - | Jira Legacy API Token. Can also be set via JIRA_LEGACY_API_TOKEN environment variable. |
78
- | `requirementsProviderConfig.jira-legacy.baseUrl` | Required for `jira-legacy` | - | Base URL for the Jira API (e.g., "https://yourcompany.atlassian.net/rest/api/2/issue/"). |
79
- | `requirementsProviderConfig.jira-legacy.displayUrl` | Optional | - | Optional URL for displaying Jira issues (e.g., "https://yourcompany.atlassian.net/browse/"). |
80
- | `contentProviderConfig` | Optional | - | Configuration for content providers. Currently, the available content providers (`github`, `file`, and `text`) don't require specific configuration. |
81
- | `tools` | Optional (JS config only) | - | Array of LangChain tools that can be used by the LLM. This option is only available when using JavaScript configuration, allowing you to extend functionality with custom tools. |
82
- | `mcpServers` | Optional | - | Configuration for Model Context Protocol (MCP) servers. This allows for enhanced context management. |
83
-
84
- ## Config initialization
85
- Configuration can be created with `gsloth init [vendor]` command.
86
- Currently, vertexai, anthropic and groq can be configured with `gsloth init [vendor]`.
87
-
88
- ### Google Vertex AI
89
- ```shell
90
- cd ./your-project
91
- gsloth init vertexai
92
- gcloud auth login
93
- gcloud auth application-default login
94
- ```
95
-
96
- ### Anthropic
97
- ```shell
98
- cd ./your-project
99
- gsloth init anthropic
100
- ```
101
- Make sure you either define `ANTHROPIC_API_KEY` environment variable or edit your configuration file and set up your key.
102
-
103
- ### Groq
104
- ```shell
105
- cd ./your-project
106
- gsloth init groq
107
- ```
108
- Make sure you either define `GROQ_API_KEY` environment variable or edit your configuration file and set up your key.
109
-
110
- ## Examples of configuration for different providers
111
-
112
- ### JSON Configuration (.gsloth.config.json)
113
-
114
- JSON configuration is simpler but less flexible than JavaScript configuration. It should directly contain the configuration object.
115
-
116
- **Example of .gsloth.config.json for Anthropic**
117
- ```json
118
- {
119
- "llm": {
120
- "type": "anthropic",
121
- "apiKey": "your-api-key-here",
122
- "model": "claude-3-5-sonnet-20241022"
123
- }
124
- }
125
- ```
126
-
127
- **Example of .gsloth.config.json for VertexAI**
128
- ```json
129
- {
130
- "llm": {
131
- "type": "vertexai",
132
- "model": "gemini-2.5-pro-preview-05-06",
133
- "temperature": 0
134
- }
135
- }
136
- ```
137
-
138
- **Example of .gsloth.config.json for Groq**
139
- ```json
140
- {
141
- "llm": {
142
- "type": "groq",
143
- "model": "deepseek-r1-distill-llama-70b",
144
- "apiKey": "your-api-key-here"
145
- }
146
- }
147
- ```
148
-
149
- ### JavaScript Configuration
150
-
151
- (.gsloth.config.js or .gsloth.config.mjs)
152
-
153
- JavaScript configuration provides more flexibility than JSON configuration, allowing you to use dynamic imports and include custom tools.
154
-
155
- **Example with Custom Tools**
156
- ```javascript
157
- import { tool } from '@langchain/core/tools';
158
- import { z } from 'zod';
159
-
160
- const parrotTool = tool((s) => {
161
- console.log(s);
162
- }, {
163
- name: 'parrot_tool',
164
- description: `This tool will simply print the string`,
165
- schema: z.string(),
166
- });
167
-
168
- export async function configure() {
169
- const anthropic = await import('@langchain/google-vertexai');
170
- return {
171
- llm: new anthropic.ChatVertexAI({
172
- model: 'gemini-2.5-pro',
173
- }),
174
- tools: [
175
- parrotTool
176
- ]
177
- };
178
- }
179
- ```
180
-
181
- **Example of .gsloth.config.js for Anthropic**
182
- ```javascript
183
- export async function configure() {
184
- const anthropic = await import('@langchain/anthropic');
185
- return {
186
- llm: new anthropic.ChatAnthropic({
187
- apiKey: process.env.ANTHROPIC_API_KEY, // Default value, but you can provide the key in many different ways, even as literal
188
- model: "claude-3-5-sonnet-20241022"
189
- })
190
- };
191
- }
192
- ```
193
-
194
- **Example of .gsloth.config.js for VertexAI**
195
- VertexAI usually needs `gcloud auth application-default login`
196
- (or both `gcloud auth login` and `gcloud auth application-default login`) and does not need any separate API keys.
197
- ```javascript
198
- export async function configure() {
199
- const vertexAi = await import('@langchain/google-vertexai');
200
- return {
201
- llm: new vertexAi.ChatVertexAI({
202
- model: "gemini-2.5-pro-preview-05-06", // Consider checking for latest recommended model versions
203
- // API Key from AI Studio should also work
204
- temperature: 0,
205
- //// Other parameters might be relevant depending on Vertex AI API updates.
206
- //// The project is not in the interface, but it is in documentation and it seems to work.
207
- // project: 'your-cool-google-cloud-project',
208
- })
209
- }
210
- }
211
- ```
212
-
213
- **Example of .gsloth.config.js for Groq**
214
- ```javascript
215
- export async function configure() {
216
- const groq = await import('@langchain/groq');
217
- return {
218
- llm: new groq.ChatGroq({
219
- model: "deepseek-r1-distill-llama-70b", // Check other models available
220
- apiKey: process.env.GROQ_API_KEY, // Default value, but you can provide the key in many different ways, even as literal
221
- })
222
- };
223
- }
224
- ```
225
-
226
- ## Using other AI providers
227
-
228
- The configure function should simply return instance of langchain [chat model](https://v03.api.js.langchain.com/classes/_langchain_core.language_models_chat_models.BaseChatModel.html).
229
- See [Langchain documentation](https://js.langchain.com/docs/tutorials/llm_chain/) for more details.
230
-
231
- ## Model Context Protocol (MCP)
232
-
233
- Gaunt Sloth Assistant supports the Model Context Protocol (MCP), which provides enhanced context management.
234
- The `@modelcontextprotocol/server-filesystem` package is included as a dependency, allowing you to easily configure file system access for your LLM.
235
-
236
- ### MCP Filesystem Server Configuration
237
-
238
- To configure the MCP filesystem server, add the `mcpServers` section to your configuration file:
239
-
240
- ```json
241
- {
242
- "llm": {
243
- "type": "vertexai",
244
- "model": "gemini-2.5-pro-preview-05-06",
245
- "temperature": 0
246
- },
247
- "mcpServers": {
248
- "filesystem": {
249
- "transport": "stdio",
250
- "command": "npx",
251
- "args": [
252
- "-y",
253
- "@modelcontextprotocol/server-filesystem",
254
- "/home/path/to/your/files"
255
- ]
256
- }
257
- }
258
- }
259
- ```
260
-
261
- This configuration launches the MCP filesystem server using npx, providing the LLM with access to the specified directory. The server uses stdio for communication with the LLM.
262
-
263
- ## Content providers
264
-
265
- ### GitHub Issues
266
-
267
- Gaunt Sloth supports GitHub issues as a requirements provider using the GitHub CLI. This integration is simple to use and requires minimal setup.
268
-
269
- **Prerequisites:**
270
-
271
- 1. **GitHub CLI**: Make sure the official [GitHub CLI (gh)](https://cli.github.com/) is installed and authenticated
272
- 2. **Repository Access**: Ensure you have access to the repository's issues
273
-
274
- **Usage:**
275
-
276
- The command syntax is `gsloth pr <prId> [githubIssueId]`. For example:
277
-
278
- ```shell
279
- gsloth pr 42 23
280
- ```
281
-
282
- This will review PR #42 and include GitHub issue #23 as requirements.
283
-
284
- To explicitly specify the GitHub issue provider:
285
-
286
- ```shell
287
- gsloth pr 42 23 -p github
288
- ```
289
-
290
- **Configuration:**
291
-
292
- To set GitHub as your default requirements provider, add this to your configuration file:
293
-
294
- ```json
295
- {
296
- "llm": {"type": "vertexai", "model": "gemini-2.5-pro-preview-05-06"},
297
- "commands": {
298
- "pr": {
299
- "requirementsProvider": "github"
300
- }
301
- }
302
- }
303
- ```
304
-
305
- ### JIRA
306
-
307
- Gaunt Sloth supports two methods to integrate with JIRA:
308
-
309
- #### 1. Modern Jira REST API (Scoped Token)
310
-
311
- This method uses the Atlassian REST API v3 with a Personal Access Token (PAT). It requires your Atlassian Cloud ID.
312
-
313
- **Prerequisites:**
314
-
315
- 1. **Cloud ID**: You can find your Cloud ID by visiting `https://yourcompany.atlassian.net/_edge/tenant_info` while authenticated.
316
-
317
- 2. **Personal Access Token (PAT)**: Create a PAT with the appropriate permissions from `Atlassian Account Settings -> Security -> Create and manage API tokens -> [Create API token with scopes]`.
318
- - For issue access, the recommended permission is `read:jira-work` (classic)
319
- - Alternatively granular access would require: `read:issue-meta:jira`, `read:issue-security-level:jira`, `read:issue.vote:jira`, `read:issue.changelog:jira`, `read:avatar:jira`, `read:issue:jira`, `read:status:jira`, `read:user:jira`, `read:field-configuration:jira`
320
-
321
- Refer to JIRA API documentation for more details [https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-get](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-get)
322
-
323
- **Environment Variables Support:**
324
-
325
- For better security, you can set the JIRA username, token, and cloud ID using environment variables instead of placing them in the configuration file:
326
-
327
- - `JIRA_USERNAME`: Your JIRA username (e.g., `user@yourcompany.com`).
328
- - `JIRA_API_PAT_TOKEN`: Your JIRA Personal Access Token with scopes.
329
- - `JIRA_CLOUD_ID`: Your Atlassian Cloud ID.
330
-
331
- If these environment variables are set, they will take precedence over the values in the configuration file.
332
-
333
- JSON:
334
-
335
- ```json
336
- {
337
- "llm": {"type": "vertexai", "model": "gemini-2.5-pro-preview-05-06"},
338
- "requirementsProvider": "jira",
339
- "requirementsProviderConfig": {
340
- "jira": {
341
- "username": "username@yourcompany.com",
342
- "token": "YOUR_JIRA_PAT_TOKEN",
343
- "cloudId": "YOUR_ATLASSIAN_CLOUD_ID"
344
- }
345
- }
346
- }
347
- ```
348
-
349
- Optionally displayUrl can be defined to have a clickable link in the output:
350
-
351
- ```json
352
- {
353
- "llm": {"type": "vertexai", "model": "gemini-2.5-pro-preview-05-06"},
354
- "requirementsProvider": "jira",
355
- "requirementsProviderConfig": {
356
- "jira": {
357
- "displayUrl": "https://yourcompany.atlassian.net/browse/"
358
- }
359
- }
360
- }
361
- ```
362
-
363
- JavaScript:
364
-
365
- ```javascript
366
- export async function configure() {
367
- const vertexAi = await import('@langchain/google-vertexai');
368
- return {
369
- llm: new vertexAi.ChatVertexAI({
370
- model: "gemini-2.5-pro-preview-05-06"
371
- }),
372
- requirementsProvider: 'jira',
373
- requirementsProviderConfig: {
374
- 'jira': {
375
- username: 'username@yourcompany.com', // Your Jira username/email
376
- token: 'YOUR_JIRA_PAT_TOKEN', // Your Personal Access Token
377
- cloudId: 'YOUR_ATLASSIAN_CLOUD_ID' // Your Atlassian Cloud ID
378
- }
379
- }
380
- }
381
- }
382
- ```
383
-
384
- #### 2. Legacy Jira REST API (Unscoped Token)
385
-
386
- This uses the Unscoped API token (Aka Legacy API token) method with REST API v2.
387
-
388
- A legacy token can be acquired from `Atlassian Account Settings -> Security -> Create and manage API tokens -> [Create API token without scopes]`.
389
-
390
- Example configuration setting up JIRA integration using a legacy API token for both `review` and `pr` commands.
391
- Make sure you use your actual company domain in `baseUrl` and your personal legacy `token`.
392
-
393
- **Environment Variables Support:**
394
-
395
- For better security, you can set the JIRA username and token using environment variables instead of placing them in the configuration file:
396
-
397
- - `JIRA_USERNAME`: Your JIRA username (e.g., `user@yourcompany.com`).
398
- - `JIRA_LEGACY_API_TOKEN`: Your JIRA legacy API token.
399
-
400
- If these environment variables are set, they will take precedence over the values in the configuration file.
401
-
402
- JSON:
403
-
404
- ```json
405
- {
406
- "llm": {"type": "vertexai", "model": "gemini-2.5-pro-preview-05-06"},
407
- "requirementsProvider": "jira-legacy",
408
- "requirementsProviderConfig": {
409
- "jira-legacy": {
410
- "username": "username@yourcompany.com",
411
- "token": "YOUR_JIRA_LEGACY_TOKEN",
412
- "baseUrl": "https://yourcompany.atlassian.net/rest/api/2/issue/"
413
- }
414
- }
415
- }
416
- ```
417
-
418
- JavaScript:
419
-
420
- ```javascript
421
- export async function configure() {
422
- const vertexAi = await import('@langchain/google-vertexai');
423
- return {
424
- llm: new vertexAi.ChatVertexAI({
425
- model: "gemini-2.5-pro-preview-05-06"
426
- }),
427
- requirementsProvider: 'jira-legacy',
428
- requirementsProviderConfig: {
429
- 'jira-legacy': {
430
- username: 'username@yourcompany.com', // Your Jira username/email
431
- token: 'YOUR_JIRA_LEGACY_TOKEN', // Replace with your real Jira API token
432
- baseUrl: 'https://yourcompany.atlassian.net/rest/api/2/issue/' // Your Jira instance base URL
433
- }
434
- }
435
- }
436
- }
437
- ```
1
+ # Configuration
2
+
3
+ Populate `.gsloth.guidelines.md` with your project details and quality requirements.
4
+ A proper preamble is paramount for good inference.
5
+ Check [.gsloth.guidelines.md](../.gsloth.guidelines.md) for example.
6
+
7
+ Your project should have the following files in order for gsloth to function:
8
+ - Configuration file (one of):
9
+ - `.gsloth.config.js` (JavaScript module)
10
+ - `.gsloth.config.json` (JSON file)
11
+ - `.gsloth.config.mjs` (JavaScript module with explicit module extension)
12
+ - `.gsloth.guidelines.md`
13
+
14
+ > Gaunt Sloth currently only functions from the directory which has one of the configuration files and `.gsloth.guidelines.md`.
15
+ > Global configuration to invoke gsloth anywhere is in [ROADMAP](../ROADMAP.md).
16
+
17
+ ## Using .gsloth Directory
18
+
19
+ For a tidier project structure, you can create a `.gsloth` directory in your project root. When this directory exists, gsloth will:
20
+
21
+ 1. Write all output files (like responses from commands) to the `.gsloth` directory instead of the project root
22
+ 2. Look for configuration files in `.gsloth/.gsloth-settings/` subdirectory
23
+
24
+ Example directory structure when using the `.gsloth` directory:
25
+
26
+ ```
27
+ .gsloth/.gsloth-settings/.gsloth-config.json
28
+ .gsloth/.gsloth-settings/.gsloth.guidelines.md
29
+ .gsloth/.gsloth-settings/.gsloth.review.md
30
+ .gsloth/gth_2025-05-18_09-34-38_ASK.md
31
+ .gsloth/gth_2025-05-18_22-09-00_PR-22.md
32
+ ```
33
+
34
+ If the `.gsloth` directory doesn't exist, gsloth will continue writing all files to the project root directory as it did previously.
35
+
36
+ **Note:** When initializing a project with an existing `.gsloth` directory, the configuration files will be created in the `.gsloth/.gsloth-settings` directory automatically. There is no automated migration for existing configurations - if you create a `.gsloth` directory after initialization, you'll need to manually move your configuration files into the `.gsloth/.gsloth-settings` directory.
37
+
38
+ ## Configuration Object
39
+
40
+ It is always worth checking sourcecode in [config.ts](../src/config.ts) for more insightful information.
41
+
42
+ | Parameter | Required | Default Value | Description |
43
+ |------------------------------------------|-----------------------------------|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
44
+ | `llm` | Required | - | An object configuring LLM. In JS config could be actual instance of LangChainJS [BaseChatModel](https://v03.api.js.langchain.com/classes/_langchain_core.language_models_chat_models.BaseChatModel.html), allowing to use LLMs which do not have a preset. |
45
+ | `llm.type` | Required (when using JSON config) | - | LLM type or provider. Options currently available are `anthropic`, `groq`, `vertexai` and `deepseek`. To use other models supported by LangChainJS, please use JavaScript config. |
46
+ | `llm.model` | Optional | - | Particular LLM model string (Check in your provider documentation). |
47
+ | `llm.apiKey` | Optional | - | API key for the LLM provider. You can either use this parameter or use environment variable. |
48
+ | `contentProvider` | Optional | `file` | Default content provider used to get content for review. Options available are `github`, `file` and `text` (`text` provides text as it is). |
49
+ | `requirementsProvider` | Optional | `file` | Default requirements provider used to get requirements for review. Options available are `jira`, `jira-legacy`, `github`, `file` and `text`. |
50
+ | `projectGuidelines` | Optional | `.gsloth.guidelines.md` | Path to the file containing project guidelines. |
51
+ | `projectReviewInstructions` | Optional | `.gsloth.review.md` | Path to the file containing project review instructions. |
52
+ | `streamOutput` | Optional | `true` | When set to `true`, AI responses are streamed to the console in real-time. When `false`, responses are displayed only after completion. |
53
+ | `filesystem` | Optional | See note | File system access configuration. Options: `'all'`, `'none'`, or an array of specific file operation names. Default is an array of read-only operations: `['read_file', 'read_multiple_files', 'list_directory', 'directory_tree', 'search_files', 'get_file_info', 'list_allowed_directories']`. |
54
+ | `commands` | Optional | - | Configuration for specific commands. |
55
+ | `commands.pr` | Optional | - | Configuration for the PR command. |
56
+ | `commands.pr.contentProvider` | Optional | `github` | Content provider used for PR review (`gsloth pr`). |
57
+ | `commands.pr.requirementsProvider` | Optional | `github` | Requirements provider used for PR review. If not specified, falls back to the global `requirementsProvider`. |
58
+ | `commands.pr.filesystem` | Optional | - | File system access configuration for PR command. Options: `'all'`, `'none'`, or specific file patterns for read-only access. |
59
+ | `commands.review` | Optional | - | Configuration for the review command. |
60
+ | `commands.review.contentProvider` | Optional | - | Content provider specifically for the review command. If not specified, falls back to the global `contentProvider`. |
61
+ | `commands.review.requirementsProvider` | Optional | - | Requirements provider specifically for the review command. If not specified, falls back to the global `requirementsProvider`. |
62
+ | `commands.review.filesystem` | Optional | - | File system access configuration for review command. Options: `'all'`, `'none'`, or specific file patterns for read-only access. |
63
+ | `commands.ask` | Optional | - | Configuration for the ask command. |
64
+ | `commands.ask.filesystem` | Optional | - | File system access configuration for ask command. Options: `'all'`, `'none'`, or specific file patterns for read-only access. |
65
+ | `commands.chat` | Optional | - | Configuration for the chat command (interactive chat sessions). |
66
+ | `commands.chat.filesystem` | Optional | - | File system access configuration for chat command. Options: `'all'`, `'none'`, or specific file patterns for read-only access. |
67
+ | `commands.code` | Optional | - | Configuration for the code command (interactive coding sessions with file system access). |
68
+ | `commands.code.filesystem` | Optional | `all` | File system access configuration for code command. Options: `'all'`, `'none'`, or specific file patterns. Default is `'all'` for full file system access. |
69
+ | `requirementsProviderConfig` | Optional | - | Configuration for requirements providers. Contains provider-specific configurations. |
70
+ | `requirementsProviderConfig.jira` | Optional | - | Configuration for the Jira requirements provider (Atlassian REST API v3 with Personal Access Token). |
71
+ | `requirementsProviderConfig.jira.username` | Optional | - | Jira username (email). Can also be set via JIRA_USERNAME environment variable. |
72
+ | `requirementsProviderConfig.jira.token` | Optional | - | Jira Personal Access Token. Can also be set via JIRA_API_PAT_TOKEN environment variable. |
73
+ | `requirementsProviderConfig.jira.cloudId` | Required for `jira` | - | Atlassian Cloud ID. Can also be set via JIRA_CLOUD_ID environment variable. |
74
+ | `requirementsProviderConfig.jira.displayUrl` | Optional | - | Optional URL for displaying Jira issues (e.g., "https://yourcompany.atlassian.net/browse/"). |
75
+ | `requirementsProviderConfig.jira-legacy` | Optional | - | Configuration for the Jira Legacy requirements provider (Atlassian REST API v2 with Legacy API Token). |
76
+ | `requirementsProviderConfig.jira-legacy.username` | Optional | - | Jira username (email). Can also be set via JIRA_USERNAME environment variable. |
77
+ | `requirementsProviderConfig.jira-legacy.token` | Optional | - | Jira Legacy API Token. Can also be set via JIRA_LEGACY_API_TOKEN environment variable. |
78
+ | `requirementsProviderConfig.jira-legacy.baseUrl` | Required for `jira-legacy` | - | Base URL for the Jira API (e.g., "https://yourcompany.atlassian.net/rest/api/2/issue/"). |
79
+ | `requirementsProviderConfig.jira-legacy.displayUrl` | Optional | - | Optional URL for displaying Jira issues (e.g., "https://yourcompany.atlassian.net/browse/"). |
80
+ | `contentProviderConfig` | Optional | - | Configuration for content providers. Currently, the available content providers (`github`, `file`, and `text`) don't require specific configuration. |
81
+ | `tools` | Optional (JS config only) | - | Array of LangChain tools that can be used by the LLM. This option is only available when using JavaScript configuration, allowing you to extend functionality with custom tools. |
82
+ | `mcpServers` | Optional | - | Configuration for Model Context Protocol (MCP) servers. This allows for enhanced context management. |
83
+
84
+ ## Config initialization
85
+ Configuration can be created with `gsloth init [vendor]` command.
86
+ Currently, vertexai, anthropic, groq and deepseek can be configured with `gsloth init [vendor]`.
87
+
88
+ ### Google Vertex AI
89
+ ```shell
90
+ cd ./your-project
91
+ gsloth init vertexai
92
+ gcloud auth login
93
+ gcloud auth application-default login
94
+ ```
95
+
96
+ ### Anthropic
97
+ ```shell
98
+ cd ./your-project
99
+ gsloth init anthropic
100
+ ```
101
+ Make sure you either define `ANTHROPIC_API_KEY` environment variable or edit your configuration file and set up your key.
102
+
103
+ ### Groq
104
+ ```shell
105
+ cd ./your-project
106
+ gsloth init groq
107
+ ```
108
+ Make sure you either define `GROQ_API_KEY` environment variable or edit your configuration file and set up your key.
109
+
110
+ ### DeepSeek
111
+ ```shell
112
+ cd ./your-project
113
+ gsloth init deepseek
114
+ ```
115
+ Make sure you either define `DEEPSEEK_API_KEY` environment variable or edit your configuration file and set up your key.
116
+ (note this meant to be an API key from deepseek.com, rather than from a distributor like TogetherAI)
117
+
118
+ ## Examples of configuration for different providers
119
+
120
+ ### JSON Configuration (.gsloth.config.json)
121
+
122
+ JSON configuration is simpler but less flexible than JavaScript configuration. It should directly contain the configuration object.
123
+
124
+ **Example of .gsloth.config.json for Anthropic**
125
+ ```json
126
+ {
127
+ "llm": {
128
+ "type": "anthropic",
129
+ "apiKey": "your-api-key-here",
130
+ "model": "claude-3-5-sonnet-20241022"
131
+ }
132
+ }
133
+ ```
134
+
135
+ **Example of .gsloth.config.json for VertexAI**
136
+ ```json
137
+ {
138
+ "llm": {
139
+ "type": "vertexai",
140
+ "model": "gemini-2.5-pro-preview-05-06",
141
+ "temperature": 0
142
+ }
143
+ }
144
+ ```
145
+
146
+ **Example of .gsloth.config.json for Groq**
147
+ ```json
148
+ {
149
+ "llm": {
150
+ "type": "groq",
151
+ "model": "deepseek-r1-distill-llama-70b",
152
+ "apiKey": "your-api-key-here"
153
+ }
154
+ }
155
+ ```
156
+
157
+ **Example of .gsloth.config.json for DeepSeek**
158
+ ```json
159
+ {
160
+ "llm": {
161
+ "type": "deepseek",
162
+ "model": "deepseek-reasoner",
163
+ "apiKey": "your-api-key-here"
164
+ }
165
+ }
166
+ ```
167
+
168
+ ### JavaScript Configuration
169
+
170
+ (.gsloth.config.js or .gsloth.config.mjs)
171
+
172
+ JavaScript configuration provides more flexibility than JSON configuration, allowing you to use dynamic imports and include custom tools.
173
+
174
+ **Example with Custom Tools**
175
+ ```javascript
176
+ import { tool } from '@langchain/core/tools';
177
+ import { z } from 'zod';
178
+
179
+ const parrotTool = tool((s) => {
180
+ console.log(s);
181
+ }, {
182
+ name: 'parrot_tool',
183
+ description: `This tool will simply print the string`,
184
+ schema: z.string(),
185
+ });
186
+
187
+ export async function configure() {
188
+ const anthropic = await import('@langchain/google-vertexai');
189
+ return {
190
+ llm: new anthropic.ChatVertexAI({
191
+ model: 'gemini-2.5-pro',
192
+ }),
193
+ tools: [
194
+ parrotTool
195
+ ]
196
+ };
197
+ }
198
+ ```
199
+
200
+ **Example of .gsloth.config.js for Anthropic**
201
+ ```javascript
202
+ export async function configure() {
203
+ const anthropic = await import('@langchain/anthropic');
204
+ return {
205
+ llm: new anthropic.ChatAnthropic({
206
+ apiKey: process.env.ANTHROPIC_API_KEY, // Default value, but you can provide the key in many different ways, even as literal
207
+ model: "claude-3-5-sonnet-20241022"
208
+ })
209
+ };
210
+ }
211
+ ```
212
+
213
+ **Example of .gsloth.config.js for VertexAI**
214
+ VertexAI usually needs `gcloud auth application-default login`
215
+ (or both `gcloud auth login` and `gcloud auth application-default login`) and does not need any separate API keys.
216
+ ```javascript
217
+ export async function configure() {
218
+ const vertexAi = await import('@langchain/google-vertexai');
219
+ return {
220
+ llm: new vertexAi.ChatVertexAI({
221
+ model: "gemini-2.5-pro-preview-05-06", // Consider checking for latest recommended model versions
222
+ // API Key from AI Studio should also work
223
+ //// Other parameters might be relevant depending on Vertex AI API updates.
224
+ //// The project is not in the interface, but it is in documentation and it seems to work.
225
+ // project: 'your-cool-google-cloud-project',
226
+ })
227
+ }
228
+ }
229
+ ```
230
+
231
+ **Example of .gsloth.config.js for Groq**
232
+ ```javascript
233
+ export async function configure() {
234
+ const groq = await import('@langchain/groq');
235
+ return {
236
+ llm: new groq.ChatGroq({
237
+ model: "deepseek-r1-distill-llama-70b", // Check other models available
238
+ apiKey: process.env.GROQ_API_KEY, // Default value, but you can provide the key in many different ways, even as literal
239
+ })
240
+ };
241
+ }
242
+ ```
243
+
244
+ **Example of .gsloth.config.js for DeepSeek**
245
+ ```javascript
246
+ export async function configure() {
247
+ const deepseek = await import('@langchain/deepseek');
248
+ return {
249
+ llm: new deepseek.ChatDeepSeek({
250
+ model: 'deepseek-reasoner',
251
+ apiKey: process.env.DEEPSEEK_API_KEY, // Default value, but you can provide the key in many different ways, even as literal
252
+ })
253
+ };
254
+ }
255
+ ```
256
+
257
+ ## Using other AI providers
258
+
259
+ The configure function should simply return instance of langchain [chat model](https://v03.api.js.langchain.com/classes/_langchain_core.language_models_chat_models.BaseChatModel.html).
260
+ See [Langchain documentation](https://js.langchain.com/docs/tutorials/llm_chain/) for more details.
261
+
262
+ ## Model Context Protocol (MCP)
263
+
264
+ Gaunt Sloth Assistant supports the Model Context Protocol (MCP), which provides enhanced context management.
265
+ The `@modelcontextprotocol/server-filesystem` package is included as a dependency, allowing you to easily configure file system access for your LLM.
266
+
267
+ ### MCP Filesystem Server Configuration
268
+
269
+ To configure the MCP filesystem server, add the `mcpServers` section to your configuration file:
270
+
271
+ ```json
272
+ {
273
+ "llm": {
274
+ "type": "vertexai",
275
+ "model": "gemini-2.5-pro-preview-05-06",
276
+ "temperature": 0
277
+ },
278
+ "mcpServers": {
279
+ "filesystem": {
280
+ "transport": "stdio",
281
+ "command": "npx",
282
+ "args": [
283
+ "-y",
284
+ "@modelcontextprotocol/server-filesystem",
285
+ "/home/path/to/your/files"
286
+ ]
287
+ }
288
+ }
289
+ }
290
+ ```
291
+
292
+ This configuration launches the MCP filesystem server using npx, providing the LLM with access to the specified directory. The server uses stdio for communication with the LLM.
293
+
294
+ ## Content providers
295
+
296
+ ### GitHub Issues
297
+
298
+ Gaunt Sloth supports GitHub issues as a requirements provider using the GitHub CLI. This integration is simple to use and requires minimal setup.
299
+
300
+ **Prerequisites:**
301
+
302
+ 1. **GitHub CLI**: Make sure the official [GitHub CLI (gh)](https://cli.github.com/) is installed and authenticated
303
+ 2. **Repository Access**: Ensure you have access to the repository's issues
304
+
305
+ **Usage:**
306
+
307
+ The command syntax is `gsloth pr <prId> [githubIssueId]`. For example:
308
+
309
+ ```shell
310
+ gsloth pr 42 23
311
+ ```
312
+
313
+ This will review PR #42 and include GitHub issue #23 as requirements.
314
+
315
+ To explicitly specify the GitHub issue provider:
316
+
317
+ ```shell
318
+ gsloth pr 42 23 -p github
319
+ ```
320
+
321
+ **Configuration:**
322
+
323
+ To set GitHub as your default requirements provider, add this to your configuration file:
324
+
325
+ ```json
326
+ {
327
+ "llm": {"type": "vertexai", "model": "gemini-2.5-pro-preview-05-06"},
328
+ "commands": {
329
+ "pr": {
330
+ "requirementsProvider": "github"
331
+ }
332
+ }
333
+ }
334
+ ```
335
+
336
+ ### JIRA
337
+
338
+ Gaunt Sloth supports two methods to integrate with JIRA:
339
+
340
+ #### 1. Modern Jira REST API (Scoped Token)
341
+
342
+ This method uses the Atlassian REST API v3 with a Personal Access Token (PAT). It requires your Atlassian Cloud ID.
343
+
344
+ **Prerequisites:**
345
+
346
+ 1. **Cloud ID**: You can find your Cloud ID by visiting `https://yourcompany.atlassian.net/_edge/tenant_info` while authenticated.
347
+
348
+ 2. **Personal Access Token (PAT)**: Create a PAT with the appropriate permissions from `Atlassian Account Settings -> Security -> Create and manage API tokens -> [Create API token with scopes]`.
349
+ - For issue access, the recommended permission is `read:jira-work` (classic)
350
+ - Alternatively granular access would require: `read:issue-meta:jira`, `read:issue-security-level:jira`, `read:issue.vote:jira`, `read:issue.changelog:jira`, `read:avatar:jira`, `read:issue:jira`, `read:status:jira`, `read:user:jira`, `read:field-configuration:jira`
351
+
352
+ Refer to JIRA API documentation for more details [https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-get](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-get)
353
+
354
+ **Environment Variables Support:**
355
+
356
+ For better security, you can set the JIRA username, token, and cloud ID using environment variables instead of placing them in the configuration file:
357
+
358
+ - `JIRA_USERNAME`: Your JIRA username (e.g., `user@yourcompany.com`).
359
+ - `JIRA_API_PAT_TOKEN`: Your JIRA Personal Access Token with scopes.
360
+ - `JIRA_CLOUD_ID`: Your Atlassian Cloud ID.
361
+
362
+ If these environment variables are set, they will take precedence over the values in the configuration file.
363
+
364
+ JSON:
365
+
366
+ ```json
367
+ {
368
+ "llm": {"type": "vertexai", "model": "gemini-2.5-pro-preview-05-06"},
369
+ "requirementsProvider": "jira",
370
+ "requirementsProviderConfig": {
371
+ "jira": {
372
+ "username": "username@yourcompany.com",
373
+ "token": "YOUR_JIRA_PAT_TOKEN",
374
+ "cloudId": "YOUR_ATLASSIAN_CLOUD_ID"
375
+ }
376
+ }
377
+ }
378
+ ```
379
+
380
+ Optionally displayUrl can be defined to have a clickable link in the output:
381
+
382
+ ```json
383
+ {
384
+ "llm": {"type": "vertexai", "model": "gemini-2.5-pro-preview-05-06"},
385
+ "requirementsProvider": "jira",
386
+ "requirementsProviderConfig": {
387
+ "jira": {
388
+ "displayUrl": "https://yourcompany.atlassian.net/browse/"
389
+ }
390
+ }
391
+ }
392
+ ```
393
+
394
+ JavaScript:
395
+
396
+ ```javascript
397
+ export async function configure() {
398
+ const vertexAi = await import('@langchain/google-vertexai');
399
+ return {
400
+ llm: new vertexAi.ChatVertexAI({
401
+ model: "gemini-2.5-pro-preview-05-06"
402
+ }),
403
+ requirementsProvider: 'jira',
404
+ requirementsProviderConfig: {
405
+ 'jira': {
406
+ username: 'username@yourcompany.com', // Your Jira username/email
407
+ token: 'YOUR_JIRA_PAT_TOKEN', // Your Personal Access Token
408
+ cloudId: 'YOUR_ATLASSIAN_CLOUD_ID' // Your Atlassian Cloud ID
409
+ }
410
+ }
411
+ }
412
+ }
413
+ ```
414
+
415
+ #### 2. Legacy Jira REST API (Unscoped Token)
416
+
417
+ This uses the Unscoped API token (Aka Legacy API token) method with REST API v2.
418
+
419
+ A legacy token can be acquired from `Atlassian Account Settings -> Security -> Create and manage API tokens -> [Create API token without scopes]`.
420
+
421
+ Example configuration setting up JIRA integration using a legacy API token for both `review` and `pr` commands.
422
+ Make sure you use your actual company domain in `baseUrl` and your personal legacy `token`.
423
+
424
+ **Environment Variables Support:**
425
+
426
+ For better security, you can set the JIRA username and token using environment variables instead of placing them in the configuration file:
427
+
428
+ - `JIRA_USERNAME`: Your JIRA username (e.g., `user@yourcompany.com`).
429
+ - `JIRA_LEGACY_API_TOKEN`: Your JIRA legacy API token.
430
+
431
+ If these environment variables are set, they will take precedence over the values in the configuration file.
432
+
433
+ JSON:
434
+
435
+ ```json
436
+ {
437
+ "llm": {"type": "vertexai", "model": "gemini-2.5-pro-preview-05-06"},
438
+ "requirementsProvider": "jira-legacy",
439
+ "requirementsProviderConfig": {
440
+ "jira-legacy": {
441
+ "username": "username@yourcompany.com",
442
+ "token": "YOUR_JIRA_LEGACY_TOKEN",
443
+ "baseUrl": "https://yourcompany.atlassian.net/rest/api/2/issue/"
444
+ }
445
+ }
446
+ }
447
+ ```
448
+
449
+ JavaScript:
450
+
451
+ ```javascript
452
+ export async function configure() {
453
+ const vertexAi = await import('@langchain/google-vertexai');
454
+ return {
455
+ llm: new vertexAi.ChatVertexAI({
456
+ model: "gemini-2.5-pro-preview-05-06"
457
+ }),
458
+ requirementsProvider: 'jira-legacy',
459
+ requirementsProviderConfig: {
460
+ 'jira-legacy': {
461
+ username: 'username@yourcompany.com', // Your Jira username/email
462
+ token: 'YOUR_JIRA_LEGACY_TOKEN', // Replace with your real Jira API token
463
+ baseUrl: 'https://yourcompany.atlassian.net/rest/api/2/issue/' // Your Jira instance base URL
464
+ }
465
+ }
466
+ }
467
+ }
468
+ ```