GthConfig

Defined in: core/dist/config/types.d.ts:99

This is a processed Gaunt Sloth config ready to be passed down into components.

Default values can be found in DEFAULT_CONFIG

Properties

a2aAgents?

optional a2aAgents?: Record<string, unknown>

Defined in: core/dist/config/types.d.ts:355

A2A (Agent-to-Agent) protocol agents configuration. Enables delegation of tasks to external AI agents. Each agent becomes available as a tool named a2a_agent_<agentId>. This feature is experimental and may change.

See

https://a2a-protocol.org/

agent?

optional agent?: object

Defined in: core/dist/config/types.d.ts:114

Selects the agent backend.

lean (default when omitted): the plain LangChain agent (GthLangChainAgent). It is given gsloth’s full toolset (filesystem + hardened dev/shell + the gth_checklist planning tool), with no deepagents machinery (no /large_tool_results offload). This is the recommended backend and the default for the CLI (code/chat), single-shot (ask/exec), and the AG-UI/api server.
deep (experimental, opt-in): the deepagents runtime (subagents, write_todos, summarization, tool-result offload). Selecting it emits a warning. It can exhibit path-divergence and sporadic failures and carries extra internal workarounds; prefer lean.

Honored everywhere; the ACP server is still structurally deep-only and always runs deep.

backend?

optional backend?: "deep" | "lean"

aiignore?

optional aiignore?: object

Defined in: core/dist/config/types.d.ts:357

enabled?

optional enabled?: boolean

patterns?

optional patterns?: string[]

allowDirs?

optional allowDirs?: string[]

Defined in: core/dist/config/types.d.ts:451

Transient (runtime-only) extra filesystem roots the agent is allowed to read/write for THIS run, in addition to the cwd sandbox. Populated by gth exec --allow-dir <path> (repeatable); never persisted to a config file. When set, the deep agent’s FilesystemBackend drops virtualMode (so absolute paths and .. resolve on the real filesystem) and access is constrained to cwd + these dirs via permission allow-rules. Removing the cwd-only sandbox is a guardrail removal, so callers announce it loudly.

allowedTools?

optional allowedTools?: string[]

Defined in: core/dist/config/types.d.ts:226

Restrict the agent to this allow-list of tool names, applied after every tool source (filesystem, built-in, custom, MCP, A2A, and tools) is resolved. This is the only knob that can gate MCP and A2A tools, which have no per-source override of their own.

omitted/undefined: no filtering, all resolved tools remain available.
non-empty array: keep only tools whose name is in the list.
empty array []: disable every tool. MCP servers are not even contacted (no OAuth), which is useful for agents that only need to reason over the prompt (e.g. the review agent).

Can be overridden per command via commands.<command>.allowedTools.

approvals?

optional approvals?: ApprovalsConfig

Defined in: core/dist/config/types.d.ts:211

CFG-27 — the tool-approval ladder: one of the five rungs (read-only · write · auto-safe · full-auto · bypass), written either as the bare rung name or as an object carrying the rater’s identity profile and the declared allow/deny lists. Each rung fully determines behaviour — there are no severity thresholds, no strictness levels and no independent rater switch.

Settable at the root or per command (commands.<command>.approvals). §9.1 — a per-command value overrides only the fields it NAMES. mode, rater and raterTimeoutMs replace the root’s; deny and escalate CONCATENATE across every scope, so a per-command rung can never discard the root’s prohibitions; allow is REPLACED when the command states its own and inherited when it does not, so a scope may narrow what runs unprompted and may never widen what is prohibited (§3.1: a too-broad allow entry runs unrated, a missed deny entry does not). Absent = auto-safe, resolved by resolveApprovals.

askWriteMode?

optional askWriteMode?: boolean

Defined in: core/dist/config/types.d.ts:457

Transient (runtime-only) flag set by gth ask --write: opt ask into the same “do-the-job” filesystem + dev tools that exec/code get, so a question can act (read/write files, run commands) rather than only chat. Never persisted to a config file.

binaryFormats?

optional binaryFormats?: false | BinaryFormatConfig[]

Defined in: core/dist/config/types.d.ts:138

Binary format support configuration. Disabled by default unless explicitly configured.

builtInTools?

optional builtInTools?: BuiltInToolsSetting

Defined in: core/dist/config/types.d.ts:195

Selects and configures the built-in tools the agent loads. Either a string[] of tool names (each enabled) or a registry keyed by tool name whose values enable (true), force-disable (false), or configure (BuiltInToolConfig) each tool. CFG-18 folded the former per-command devTools (the run_* commands + run_shell_command’s EXT-9/10/12 config) into this single registry: e.g. { "run_tests": { "command": "npm test" }, "run_shell_command": { "timeout": 300000 } }. Settable at the root or per command (commands.<command>.builtInTools); a per-command value replaces the top-level one.

builtInToolsConfig?

optional builtInToolsConfig?: BuiltInToolsConfig

Defined in: core/dist/config/types.d.ts:356

canInterruptInferenceWithEsc

canInterruptInferenceWithEsc: boolean

Defined in: core/dist/config/types.d.ts:302

Allow inference to be interrupted with esc. Only has an effect in TTY mode.

commands?

optional commands?: object

Defined in: core/dist/config/types.d.ts:361

api?

optional api?: object

api.approvals?

optional approvals?: ApprovalsConfig

§9.1 — per-command approvals posture. It overrides only the fields it NAMES: mode, rater, raterTimeoutMs and allow replace the root’s, while deny and escalate concatenate with it. See GthConfig.approvals.

api.builtInTools?

optional builtInTools?: BuiltInToolsSetting

api.cors?

optional cors?: object

api.cors.allowHeaders?

optional allowHeaders?: string

api.cors.allowMethods?

optional allowMethods?: string

api.cors.allowOrigin?

optional allowOrigin?: string

api.filesystem?

optional filesystem?: string[] | "none" | "all" | "read"

api.port?

optional port?: number

ask?

optional ask?: CommandToolingConfig

chat?

optional chat?: CommandToolingConfig

code?

optional code?: CommandToolingConfig

gth code — interactive coding session. Carries the do-the-job tool/filesystem knobs; the dev/shell tools (CFG-18) are configured via CommandToolingConfig.builtInTools.

exec?

optional exec?: CommandToolingConfig

gth exec — prompt-as-script runtime. Like code, an exec run may need to actually do the job (read/write files, run commands), so it carries the same tool/filesystem knobs.

pr?

optional pr?: PrCommandConfig

review?

optional review?: CommandToolingConfig & object

Type Declaration

contentSource?

optional contentSource?: string

rating?

optional rating?: RatingConfig

requirementSource?

optional requirementSource?: string

commit?

optional commit?: object

Defined in: core/dist/config/types.d.ts:404

GS2-35 — identity for the Co-Authored-By trailer of agent-authored git commits. Gaunt Sloth has no dedicated commit tool (it commits via run_shell_command), so this identity is injected into the code-mode system prompt, which instructs the agent to co-author commits as this account and NEVER as the underlying model. Optional and defaulted: when unset (or a field is unset) the agent co-authors as DEFAULT_COMMIT_CO_AUTHOR_NAME <DEFAULT_COMMIT_CO_AUTHOR_EMAIL>.

coAuthor?

optional coAuthor?: object

coAuthor.email?

optional email?: string

coAuthor.name?

optional name?: string

consoleLevel?

optional consoleLevel?: StatusLevel

Defined in: core/dist/config/types.d.ts:320

Console logging level. Only messages at or above this level will be displayed. Valid values: ‘debug’, ‘info’, ‘display’, ‘success’, ‘warning’, ‘error’, ‘stream’ Default: ‘info’ (not debug)

contentSource

contentSource: string

Defined in: core/dist/config/types.d.ts:144

Content source type. Source used to fetch content (usually diff) for review or pr command.

DEFAULT_CONFIG#contentSource

contentSourceConfig?

optional contentSourceConfig?: Record<string, unknown>

Defined in: core/dist/config/types.d.ts:323

customTools?

optional customTools?: CustomToolsConfig

Defined in: core/dist/config/types.d.ts:321

debugDump?

optional debugDump?: object

Defined in: core/dist/config/types.d.ts:440

GS2-47 — controls the shared secret-redaction pass applied to /debug-dump archives. Default ON (omitted = redact): secret-named env-var values, inline config secrets, provider-key/auth patterns and sensitive config fields are masked before any artifact hits disk. Set debugDump.redact: false (or run /debug-dump --unsafe-no-redact) to write a RAW archive, which the command flags with a loud “may contain secrets” warning. Defaulted at the read site (not in DEFAULT_CONFIG) to avoid churning the effective-config snapshot.

redact?

optional redact?: boolean

debugLog?

optional debugLog?: boolean

Defined in: core/dist/config/types.d.ts:307

Log messages and events to gaunt-sloth.log, use llm.verbose or gth --verbose as more intrusive option, setting verbose to LangChain / LangGraph

filesystem

filesystem: string[] | "none" | "all" | "read"

Defined in: core/dist/config/types.d.ts:185

history?

optional history?: object

Defined in: core/dist/config/types.d.ts:123

GS2-7 (B20) — local, opt-in session history store. DEFAULT OFF (absent = disabled): a default run persists nothing and behaves exactly as before. When enabled, each run is recorded to a local SQLite DB (~/.gsloth/history.db by default, overridable via dbPath) for gth history search / gth insights. Local only — no telemetry leaves the machine.

dbPath?

optional dbPath?: string

enabled?

optional enabled?: boolean

identityProfile?

optional identityProfile?: string

Defined in: core/dist/config/types.d.ts:164

Separate identity profile. May include separate identity, guidelines and command protocol, making gsloth behave as an agent different from default profile behaviour. for example, devops profile to detect changes such as properties and environment variables. Custom config can still win over this one. This setting requires .gsloth/.gsloth-settings directory to exist.

includeCurrentDateAfterGuidelines

includeCurrentDateAfterGuidelines: boolean

Defined in: core/dist/config/types.d.ts:168

Whether to include the current date in the project review instructions or not.

injectModelContext?

optional injectModelContext?: boolean

Defined in: core/dist/config/types.d.ts:431

GS2-34 — inject the resolved active provider:model identity into the assembled system prompt so the agent knows which model is serving it (to answer “what model are you?” and reason about its own capabilities/limits). Default ON (omitted = inject). Opt out with injectModelContext: false to keep reproducible / model-agnostic runs (e.g. review) blind to the identity — when off, the assembled prompt is exactly as it is without this feature. Applies in ALL modes (unlike the code-mode-only cwd/os-shell/commit notes). Defaulted at the read site (not in DEFAULT_CONFIG) to avoid churning the effective-config snapshot.

llm

llm: BaseChatModel

Defined in: core/dist/config/types.d.ts:100

mcpServers?

optional mcpServers?: Record<string, unknown>

Defined in: core/dist/config/types.d.ts:329

MCP (Model Context Protocol) server connections. Allows connecting to external MCP servers including those requiring OAuth.

See

https://modelcontextprotocol.io/

memory?

optional memory?: object

Defined in: core/dist/config/types.d.ts:131

GS2-7 (B21) — opt-in file-backed memory (MEMORY.md / USER.md). DEFAULT OFF. Forward-compat toggle only; the feature is a deferred follow-up.

enabled?

optional enabled?: boolean

middleware?

optional middleware?: unknown[]

Defined in: core/dist/config/types.d.ts:259

Middleware configuration for LangChain v1. Middleware provides hooks to intercept and control agent execution at critical points.

Middleware can be:

Predefined middleware (string or config object) - works in both JSON and JS configs
Custom middleware objects - only available in JS configs

Example (JSON config):

{
  "middleware": [
    "summarization",
    { "name": "anthropic-prompt-caching", "ttl": "5m" }
  ]
}

Example (JS config):

{
  middleware: [
    "summarization",
    { beforeModel: (state) => { /* custom logic */ return state; } }
  ]
}

Available predefined middleware:

anthropic-prompt-caching: Reduces API costs by caching prompts (Anthropic only)
summarization: Condenses conversation history when approaching token limits

modelDisplayName?

optional modelDisplayName?: string

Defined in: core/dist/config/types.d.ts:410

modelProviderType?

optional modelProviderType?: string

Defined in: core/dist/config/types.d.ts:421

GS2-53 — the configured provider type string (openrouter/deepseek/xai/anthropic/…), stashed by the loader from the raw llm.type before the built BaseChatModel replaces the raw spec. INTERNAL (loader-set, never user-supplied), so it is deliberately absent from the config schema. import(‘#src/utils/systemPromptNotes.js’).resolveModelIdentity PREFERS this over the live model’s _llmType() for the injected identity, because OpenAI-compatible shims (openrouter/deepseek/xai all extend ChatOpenAI) report _llmType() === 'openai' and would otherwise mislabel the provider half. Absent for module configs (which hand us an already-built LLM with no raw type), where resolution falls back to the guarded _llmType().

noDefaultPrompts?

optional noDefaultPrompts?: boolean

Defined in: core/dist/config/types.d.ts:184

If true, only use user-provided system prompts. Do not fall back to the bundled .gsloth.*.md prompt files shipped with the installation. This applies to all .gsloth.*.md files (backstory, system, chat, code, guidelines, review).

organization?

optional organization?: object

Defined in: core/dist/config/types.d.ts:174

Organisation name, locale and timezone. Only used with includeCurrentDateAfterGuidelines. timeZone and locale should be in format supported by Intl.DateTimeFormat

locale?

optional locale?: string

name?

optional name?: string

timezone?

optional timezone?: string

output?

optional output?: object

Defined in: core/dist/config/types.d.ts:470

GS2-63 — output surface controls.

output.header DEFAULTS ON (omitted = show). Set false to suppress the technical run-header preamble — the Workdir/Model/Tools/Middleware status block, the Press Escape or Q to interrupt hint, and their surrounding blank lines — in NON-TUI text modes (--no-tui, ask, exec, eval, pr, review, piped/CI), so captured stdout and log diffs stay clean. The interactive TUI ignores the setting and always shows the header. Only the preamble is suppressed — never model/tool output, errors, or config-validation warnings, and never the live Thinking… indicator. Defaulted at the read site (!== false), not in DEFAULT_CONFIG, to avoid churning the effective-config snapshot.

optional header?: boolean

prompts?

optional prompts?: Partial<Record<PromptSegmentName, PromptSegmentSetting>>

Defined in: core/dist/config/types.d.ts:155

GS2-43 — the unified prompt-segment config (see PromptsConfig). Each of the seven segments (backstory | guidelines | system | chat | code | exec | review) accepts a string path (e.g. "guidelines": "AGENTS.md") or an object ({ path?, enabled?, mode? }). When a segment is omitted its default-named file / bundled default applies unchanged.

recursionLimit?

optional recursionLimit?: number

Defined in: core/dist/config/types.d.ts:314

LangGraph recursion limit for an agent run — the maximum number of super-steps (model ↔ tool round-trips) before the graph throws. Defaults to 1000, which suits long coding chains; embodied / tight-loop consumers can lower it so a stuck run fails fast and visibly instead of grinding.

reporters?

optional reporters?: Record<string, string>

Defined in: core/dist/config/types.d.ts:503

BATCH-19 — custom gth eval reporters, keyed by the NAME they are selected under (gth eval … --reporter <name>). Each value is a MODULE PATH, resolved relative to the project dir, whose default export is an EvalReporterFactory (() => EvalReporter). Loaded and registered through the SAME seam the bundled reporters (text, junit) use, so a config reporter can also override a built-in of the same name (config wins). A missing file, a failed import, or a non-function default export is a hard error (the eval harness exits 2). Trusted: it is the user’s own config, which already executes arbitrary JS.

requirementSource

requirementSource: string

Defined in: core/dist/config/types.d.ts:148

Requirement source type. Source used to fetch requirements for review or pr command.

requirementSourceConfig?

optional requirementSourceConfig?: Record<string, unknown>

Defined in: core/dist/config/types.d.ts:322

streamOutput

streamOutput: boolean

Defined in: core/dist/config/types.d.ts:265

Stream output. Some models do not support streaming. Set value to false for them.

DEFAULT_CONFIG#streamOutput

streamSessionInferenceLog

streamSessionInferenceLog: boolean

Defined in: core/dist/config/types.d.ts:298

Stream session log instead of writing it when inference streaming is complete. (only works when streamOutput is true)

subagents?

optional subagents?: SubagentProfileSpec[]

Defined in: core/dist/config/types.d.ts:512

GS2-33 — profile-backed subagents. Each entry names a subagent and the named config profile the CHILD resolves when the parent spawns it, so a subagent can run under a different model/tools/prompt than the parent (a cheap profile for recall/search while the parent runs on a strong model). Honored by the deep (deepagents) backend — its task tool gains one selectable subagent per entry; the lean backend’s own subagent primitive lands in GS2-25.

tls?

optional tls?: object

Defined in: core/dist/config/types.d.ts:336

TLS trust for outbound HTTPS. Primarily so an http-transport MCP server behind a private/corporate CA can be reached without prepending NODE_EXTRA_CA_CERTS on every invocation. The mechanism is a process-global undici dispatcher, so it applies to ALL outbound fetch this process makes (LLM provider calls included), not only MCP.

extraCaCerts?

optional extraCaCerts?: string[]

Extra CA certificate file(s) to trust IN ADDITION to Node’s built-in roots. Paths resolve relative to the project dir (or ~/absolute). Additive — never removes a default root.

rejectUnauthorized?

optional rejectUnauthorized?: boolean

DANGER — false disables TLS certificate verification for ALL outbound HTTPS this process makes, not just MCP. Escape hatch only; a loud security warning is emitted every session.

toolLoopGuard?

optional toolLoopGuard?: boolean | { halt?: boolean; threshold?: number; warn?: boolean; }

Defined in: core/dist/config/types.d.ts:489

EXT-36 — the tool-loop guard: a repeated-identical-(tool, args) / no-progress detector that runs as a lean-backend beforeModel middleware, the orthogonal sibling of GS2-36’s consecutive-tool-ERROR budget. It catches the case GS2-36 leaves open — a model re-issuing the SAME call verbatim, whether it keeps erroring or keeps “succeeding” with the same result.

false disables it entirely.
true / omitted → WARN on, HALT off, default threshold (DEFAULT_TOOL_LOOP_THRESHOLD).
object → per-field: warn (default ON) injects a control-flow-free nudge at the threshold; halt (default OFF, opt-in) ends the run cleanly (jumpTo:'end', never a throw) at the threshold; threshold is the number of consecutive identical calls that trip it.

WARN is provably harmless (no routing effect, one nudge per signature per streak). The WARN-on default is applied at the read site (not in DEFAULT_CONFIG) to avoid churning the effective-config snapshot.

tools?

optional tools?: StructuredToolInterface<ToolInputSchemaBase, any, any>[] | BaseToolkit[] | ServerTool[]

Defined in: core/dist/config/types.d.ts:212

useColour

useColour: boolean

Defined in: core/dist/config/types.d.ts:286

Use colour in output

useMouse

useMouse: boolean

Defined in: core/dist/config/types.d.ts:293

Enable terminal mouse reporting in the Ink TUI, making its affordances clickable. On by default in an interactive terminal. While it is on the terminal’s own text selection needs a modifier (Shift, or Option in some macOS terminals) — set this to false, or set GTH_NO_MOUSE, to get unmodified selection back.

writeBinaryOutputsToFile

writeBinaryOutputsToFile: boolean

Defined in: core/dist/config/types.d.ts:282

Whether binary model outputs should be written to files instead of printed inline. When enabled, supported binary content blocks are materialized as gth_*.<ext> files.

writeOutputToFile

writeOutputToFile: string | boolean

Defined in: core/dist/config/types.d.ts:277

Should the output be written to md file. (e.g. gth_2025-07-26_22-59-06_REVIEW.md). Defaults to false (no file is written); set to true for the standard gth_<timestamp>_<COMMAND>.md name. Can be set to false with -wn or -w0 Can be set to a specific filename or path by passing a string:

Bare filenames (e.g. "review.md") are placed in .gsloth/ when it exists, otherwise project root
Paths with separators (e.g. "./review.md" or "reviews/last.md") are always relative to project root Please note the string does not accept absolute path, but allows to exit project with .. if necessary.