Environment variables

Behavior & tools: configure in /config

Feature toggles are configured inside the harness, not through env vars. Run /config in an interactive session: every setting shows a one-line description and its live value, and changes apply immediately. Configurable there:

Setting	Default	What it does
Web tools	on (interactive)	keyless web_fetch + web_search (DuckDuckGo); off in one-shot/eval for offline determinism. See Web access
TDD enforcement	on	test-first guidance + test-sibling-required as an error on changed logic files

/config also sets the model, interactive mode, gate command, and editable scope.

Both toggles have env equivalents for scripted runs: TSFORGE_WEB (1/0; an explicit value always wins over the interactive default) and TSFORGE_TDD (0 to opt out).

Only genuine human choices live in /config. The rest run unconditionally: the update check always happens in an interactive, non-CI session. Set the cross-tool NO_UPDATE_NOTIFIER=1 (note: not a TSFORGE_* variable) to suppress it. Programmatic tool calling, LSP navigation, git_context, hashline, TTSR, and write diagnostics are always on.

The variables listed below the fold are endpoint, tuning, and operational knobs (model endpoint, timeouts, eval/test harness), not user-facing feature switches.

Eval / CI knobs (not in /config)

The always-on tools can be withheld via env only for eval sweeps or non-git / headless environments. Never change these interactively:

Variable	Default	Effect
TSFORGE_NO_LSP_TOOLS	off	withhold the LSP navigation tools (=1)
TSFORGE_NO_OSC8	off	disable OSC 8 file:line hyperlinks in the pane TUI (=1)
TSFORGE_NO_GIT_TOOL	off	withhold the git_context tool (=1)
TSFORGE_NO_SCRIPT	off	withhold the script (programmatic tool calling) tool (=1)
TSFORGE_NO_DELEGATION	off	withhold spawn_agent: run single-stream with no subagents (=1). See delegation
TSFORGE_NO_REVIEW	off	skip the automatic post-work agent review after a task goes green (=1)

Git context

On existing-code runs tsforge offers git_context, a read-only tool giving the model structured, token-bounded access to repo state, so it can scope a review or a fix to what actually changed instead of shelling out to raw git. Ops: diff, changed_files, log (incl. a line range’s history), blame, and show. It wraps the git binary via an explicit argv (no shell), validates the sha, and rejects shell metacharacters / option injection in ref/path; output is char-capped (maxChars to raise it).

Offered only when there is existing code to inspect (greenfield scratch builds have no history), and it is independent of TSFORGE_NO_LSP_TOOLS since it is not an LSP tool. Being read-only, it is available in plan mode too. For eval/headless runs it can be withheld with TSFORGE_NO_GIT_TOOL=1.

Integrations: GitHub, Linear, Notion, Sentry

Optional, opt-in integrations that let the agent read and act on the tools your workflow runs through. Each is off until it’s available — GitHub when the gh CLI is installed and authenticated; Linear, Notion, and Sentry when their MCP server is configured — and each writes only in interactive modes (never while planning or running unattended). The kill-switches force one off; the *_RAW flags additionally expose that server’s raw mcp__<server>__* tools alongside the curated verbs (off by default, so the model sees a small, focused tool set).

Variable	Default	Effect
TSFORGE_NO_GITHUB	off	withhold the git/GitHub tools even when gh is authenticated (=1)
TSFORGE_NO_LINEAR	off	withhold the Linear tools even when the server is connected (=1)
TSFORGE_LINEAR_RAW	off	also advertise the raw mcp__linear__* tools (=1)
TSFORGE_NO_NOTION	off	withhold the Notion tools (=1)
TSFORGE_NOTION_RAW	off	also advertise the raw mcp__notion__* tools (=1)
TSFORGE_NO_SENTRY	off	withhold the Sentry tools (=1)
TSFORGE_SENTRY_RAW	off	also advertise the raw mcp__sentry__* tools (=1)

Web access

Opt-in, free, and no required service keys. Turn on Web tools in /config to add read-only research tools: package_info, package_docs, web_fetch, web_search, and web_browse. Search defaults to DuckDuckGo’s keyless HTML endpoint. SearXNG is not bundled; set TSFORGE_SEARXNG_URL only when you already run a SearXNG service. Full guide: Web access.

Variable	Default	Toggles
TSFORGE_NPM_REGISTRY	npm registry	registry used by package_info / package_docs
TSFORGE_SEARXNG_URL	unset	route web_search to a SearXNG instance you already run (e.g. http://localhost:8888)
TSFORGE_WEB_SEARCH_BACKEND	auto	duckduckgo or searxng; searxng fails closed if no SearXNG URL is set

Image capabilities (vision, generation)

When the chat model is text-only, route reading and generating images to a separate backend. Configure it in models.json capabilities or the env vars below. Each capability is off unless configured; when on, it enables the read_image / generate_image tools and the drag / paste / @ attachment UX (interactive). The env trio is an ad-hoc backend without editing the file; a _MODEL alone (no _BASE_URL) names an existing registry entry.

Variable	Default	Effect
TSFORGE_VISION_BASE_URL / TSFORGE_VISION_MODEL / TSFORGE_VISION_API_KEY	unset	ad-hoc vision (image-reading) backend
TSFORGE_IMAGE_BASE_URL / TSFORGE_IMAGE_MODEL / TSFORGE_IMAGE_API_KEY	unset	ad-hoc image-generation backend
TSFORGE_IMAGE_API	chat-modalities	image-gen wire shape: chat-modalities or images-generations
TSFORGE_IMAGE_PROTOCOL	auto	inline preview of generated images: iterm2 to force, off/none to disable (auto-detects iTerm2, disabled under tmux)

Generated images are saved under .tsforge/images/. Pasting an image is Ctrl+V (a terminal app can’t receive Cmd+V); identical images are described once (no duplicate cost). Model IDs + costs: OpenRouter runs everything through /chat/completions (no /images endpoint). For example, google/gemini-2.5-flash-lite (read) and google/gemini-3.1-flash-lite-image (generate).

Opt-in gate oracles

Extra gate steps (default off; each skips cleanly when nothing applies). See How tsforge builds the gate.

Variable	Adds
TSFORGE_COVERAGE=<pct>	fail if line/function coverage is below the floor
TSFORGE_BOOT="<start cmd>"	boot the server (TSFORGE_BOOT_URL, default http://localhost:3000/; TSFORGE_BOOT_TIMEOUT, default 15000 ms) and require a non-5xx
TSFORGE_PROPTEST=1	fuzz exported functions from their types; fail if any throws on valid input (TSFORGE_PROPTEST_TIMEOUT_MS bounds the generated suite)

Model / inference

Variable	Default	Toggles
TSFORGE_BASE_URL	http://localhost:8000/v1	API endpoint
TSFORGE_MODEL	deepseek-v4-flash	model name
TSFORGE_API_KEY	unset	API key
TSFORGE_MAX_TOKENS	16384	max output tokens
TSFORGE_REPETITION_PENALTY	off	vLLM repetition penalty
TSFORGE_THINKING_BUDGET	unset	reasoning token cap
TSFORGE_CONTEXT_WINDOW	32768	context window
TSFORGE_COMPACT_AT	0.8	auto-compact threshold

Judge (eval scripts)

Variable	Default
TSFORGE_JUDGE_URL	TSFORGE_BASE_URL
TSFORGE_JUDGE_MODEL	TSFORGE_MODEL
TSFORGE_JUDGE_KEY	TSFORGE_API_KEY

Session / paths

Variable	Default	Toggles
TSFORGE_HOME	~	root for ~/.tsforge/
TSFORGE_NO_PERSIST	off	disable disk sessions
TSFORGE_SESSION_TTL_DAYS	30	session prune age

Timeouts

Variable	Default	Toggles
TSFORGE_RUN_TIMEOUT_MS	120000	shell timeout (0 = none)
TSFORGE_GATE_TIMEOUT_MS	600000	gate timeout (0 = none)

Gate subprocess

Variable	Default
TSFORGE_PACKS	comma-separated pack IDs
TSFORGE_RULE_OVERRIDES	JSON severity map
TSFORGE_CONVENTIONS	JSON conventions block (interface naming / enums): rebuilds the bundled rule options. Written by tsforge setup

Eval scripts

Variable	Default
TSFORGE_SEED	fixture seed name
TSFORGE_TEMPS	0,0.5
TSFORGE_REPEATS	3
TSFORGE_STREAM	off (=1 to enable)
TSFORGE_FEATURE_VARIANTS	comma-separated dims

Script tool (programmatic tool calling)

On by default; withhold with TSFORGE_NO_SCRIPT=1 (above). Tuning knobs:

Variable	Default	Toggles
TSFORGE_SCRIPT_MAX_CALLS	50	max tool calls one script may make
TSFORGE_SCRIPT_TIMEOUT_MS	60000	per-script timeout (capped at 300000)

Automation hooks

Variable	Set by	Meaning
TSFORGE_STATUS	tsforge (for your --notify command)	the run outcome (e.g. greenfield done 7/7). Read it in the notifier script

Debug & tracing

Variable	Default	Toggles
TSFORGE_TRACE	off	surface quietly-degraded errors: a file path appends [scope] message lines; 1/true/stderr writes to stderr
TSFORGE_DEBUG	off	alias for TSFORGE_TRACE (same channel)
TSFORGE_EDITOR_DEBUG	off	append input-editor event logs to the given file path
TSFORGE_BASIC_INPUT	off	=1 forces the plain readline input row instead of the multi-line editor (compat/debug)

Tests

Variable	Default
TSFORGE_BROWSER_TESTS	off (=1 for Playwright integration)
TSFORGE_WEB_LIVE_TESTS	off (=1 for live web_fetch/web_search network tests)

→ Commands · Permissions & policy