.env.example

# =============================================================================
# INTERNAL CATALOG — not a user-facing config file.
# =============================================================================
#
# End users of `interlinked-cli` never need a `.env` file. The CLI runs out
# of the box with no environment configuration required, and this file is
# not included in the published tarball (`files` in package.json excludes it).
#
# This file exists solely so the `undefined_env_vars` harness check can
# recognise which `process.env.FOO` references in the source are documented.
# Contributors editing the CLI: when you add a `process.env.NEW_VAR` read
# anywhere under `src/`, add a commented-out entry here with a one-line
# description of what the variable controls. Verify with `interlinked verify`.
#
# Day-to-day discovery of environment variables for end users happens via
# the `interlinked env` command, which prints every recognised variable
# along with its currently resolved value.
# =============================================================================

# ---------------------------------------------------------------------------
# Hook pipeline (set by the generated `.interlinked/hooks/interlinked-activity.mjs`
# when it invokes adapters; not something the user normally sets)
# ---------------------------------------------------------------------------

# The hook event name being dispatched (e.g. "PreToolUse", "PostToolUse",
# "SessionStart"). Set automatically by the hook runtime.
# INTERLINKED_EVENT=PreToolUse

# Which AI coding agent emitted the event. One of: claude-code, copilot-cli,
# gemini-cli, codex. Set automatically by the hook runtime.
# INTERLINKED_RUNNER=claude-code

# Short client identifier injected by the hook command installed into each
# client's settings file. One of: claude, copilot, gemini, codex. The .mjs
# runtime reads this in CLIENT_HANDLERS to disambiguate clients whose
# payload shapes overlap (Claude vs Codex). Set automatically.
# INTERLINKED_CLIENT=claude

# Unix socket path the hook connects to when talking to the harness daemon.
# Default: walks up from CWD looking for the nearest `.interlinked/harness.sock`.
# INTERLINKED_SOCKET=/path/to/.interlinked/harness.sock

# Hook wire protocol the hook process should use when talking to the harness daemon (auto-negotiated; rarely set manually).
# INTERLINKED_HOOK_PROTOCOL=framed

# ---------------------------------------------------------------------------
# Toolchain selection
# ---------------------------------------------------------------------------

# Override the `tsgo` binary used for fast TypeScript type-checking.
# Default: resolve from node_modules. Point at a specific binary for
# reproducible builds or when using a pinned nightly.
# INTERLINKED_TSGO=/absolute/path/to/tsgo

# ---------------------------------------------------------------------------
# Runner detection markers (read, never written, by adapters in
# src/harness/adapters/*.ts). The hook script decides which AI coding agent
# it is running under by sniffing these variables from `process.env`. The
# CLI never sets or requires any of them — they are set by the host agent
# (Claude Code, Copilot CLI, Cursor, Gemini CLI, Codex) when it spawns the
# hook, so their "documentation" here simply declares which agent each
# marker identifies.
# ---------------------------------------------------------------------------

# --- Claude Code (src/harness/adapters/claude-code.ts) ---

# Marker set by Claude Code's CLI runtime when hooks are invoked. Presence
# signals the Claude Code runner to the adapter.
# CLAUDE_CODE=1

# Alternate/legacy marker name observed in some Claude Code releases; treated
# as equivalent to CLAUDE_CODE by the adapter.
# CLAUDECODE=1

# Working directory Claude Code advertises for the current session. Non-empty
# value is also treated as a Claude Code runner signal.
# CLAUDE_WORKING_DIR=/path/to/repo

# Version string injected by Claude Code. Used purely as an additional runner
# detection signal when the other markers are absent.
# CLAUDE_CODE_VERSION=1.0.0

# --- GitHub Copilot CLI (src/harness/adapters/copilot-cli.ts) ---

# Primary marker set by GitHub Copilot CLI. Presence signals the copilot-cli
# runner to the adapter.
# GH_COPILOT_CLI=1

# Alternate marker name under which some Copilot CLI builds expose their
# presence; treated as equivalent to GH_COPILOT_CLI.
# COPILOT_CLI=1

# Third observed marker variant for Copilot CLI (matches the older
# `GITHUB_COPILOT_*` naming). Treated as equivalent to GH_COPILOT_CLI.
# GITHUB_COPILOT_CLI=1

# Copilot CLI version string. Non-empty value is also treated as a runner
# detection signal.
# GH_COPILOT_VERSION=1.0.0

# --- Cursor (src/harness/adapters/cursor.ts) ---

# Session identifier Cursor injects into hook processes. Presence signals the
# cursor runner to the adapter.
# CURSOR_SESSION_ID=abc123

# Trace identifier Cursor injects alongside CURSOR_SESSION_ID. Used as an
# additional runner detection signal.
# CURSOR_TRACE_ID=trace-xyz

# API endpoint Cursor advertises for its backend. Non-empty value is treated
# as a Cursor runner signal; its value is otherwise unused by the adapter.
# CURSOR_API_URL=https://api.cursor.com

# --- Gemini CLI (src/harness/adapters/gemini-cli.ts) ---

# Marker set by Gemini CLI when invoking hooks. Presence signals the
# gemini-cli runner to the adapter.
# GEMINI_CLI=1

# Google Gemini API key. Used only as a runner-detection heuristic (its
# presence strongly suggests Gemini CLI is the host); the adapter never reads
# or transmits the key itself.
# GEMINI_API_KEY=your-key-here

# Gemini CLI version string. Non-empty value is also treated as a runner
# detection signal.
# GEMINI_CLI_VERSION=0.1.0

# --- OpenAI Codex CLI (src/harness/adapters/codex.ts) ---

# Primary marker set by the OpenAI Codex CLI. Presence signals the codex
# runner to the adapter.
# CODEX_CLI=1

# Alternate marker name observed in some Codex CLI releases; treated as
# equivalent to CODEX_CLI.
# OPENAI_CODEX_CLI=1

# Session identifier Codex CLI injects into hook processes. Used as an
# additional runner detection signal.
# CODEX_SESSION_ID=sess-abc

# Codex CLI version string. Non-empty value is also treated as a runner
# detection signal.
# CODEX_VERSION=0.1.0

# ---------------------------------------------------------------------------
# Config location overrides (src/lib/config.ts)
# ---------------------------------------------------------------------------

# Absolute path to the .interlinked config dir. When set, overrides the
# default `{cwd}/.interlinked/` resolution. Useful for tests and for
# operators who keep per-project config outside the repo tree.
# INTERLINKED_HOME=/path/to/.interlinked

# Absolute path for activity / session / sync state files. When set,
# overrides the default `{INTERLINKED_HOME}/` data dir. Useful for keeping
# JSONL data on a separate disk or outside the repo. Skipping data-related
# `.gitignore` entries when this path lives outside `cwd`.
# INTERLINKED_DATA_DIR=/path/to/data

# ---------------------------------------------------------------------------
# Terminal-session identifiers (src/commands/scanner.ts)
# ---------------------------------------------------------------------------
# Read when recording a PII-filter toggle audit entry so the reviewer sees
# which shell disabled the filter. Both are standard system env vars; the
# CLI never sets them — it just captures whatever the login shell exposes.

# Controlling pty set by OpenSSH. Recorded in the scanner audit log.
# SSH_TTY=/dev/ttys001

# Fallback terminal identifier some shells export. Also recorded in audit.
# TTY=/dev/ttys001

# ---------------------------------------------------------------------------
# Server connection & auth (src/lib/config.ts, src/lib/auth.ts)
# ---------------------------------------------------------------------------

# Remote Interlinked MCP Server base URL. Overrides config.*.json. A
# localhost/127.0.0.1 value puts the CLI in dev mode (auth skipped).
# INTERLINKED_SERVER_URL=https://your-worker.workers.dev

# Personal access token for the server; overrides config.local.json.
# INTERLINKED_ACCESS_TOKEN=il_xxx

# Legacy alias for INTERLINKED_ACCESS_TOKEN (still honored).
# INTERLINKED_TOKEN=il_xxx

# Workspace the CLI syncs activity into.
# INTERLINKED_WORKSPACE_ID=ws_xxx

# MCP tool-name prefix used to locate Claude Code OAuth credentials.
# INTERLINKED_MCP_PREFIX=interlinked

# ---------------------------------------------------------------------------
# Agent identity (src/commands/context.ts, src/commands/first-run.ts)
# ---------------------------------------------------------------------------

# Display name for this agent in the activity feed; overrides config.
# INTERLINKED_AGENT_NAME=my-agent
# Short alias for INTERLINKED_AGENT_NAME.
# INTERLINKED_AGENT=my-agent
# Generic agent-name fallback used when the INTERLINKED_* forms are unset.
# AGENT_NAME=my-agent
# Per-event session id (normally set by the hook runtime).
# INTERLINKED_SESSION_ID=sess-abc
# Comma-separated client allowlist consumed by `interlinked enable`.
# INTERLINKED_CLIENTS=claude,codex

# ---------------------------------------------------------------------------
# Sync behaviour (src/lib/config.ts)
# ---------------------------------------------------------------------------

# realtime | local | manual. Overrides config.local.json sync_mode.
# INTERLINKED_SYNC_MODE=realtime

# ---------------------------------------------------------------------------
# Diagnostics (src/harness/*, src/commands/harness.ts)
# ---------------------------------------------------------------------------

# Set to 1 for verbose harness/CLI logging.
# INTERLINKED_VERBOSE=1
# Set to 1 for extra debug tracing.
# INTERLINKED_DEBUG=1

# ---------------------------------------------------------------------------
# Harness tuning (src/harness/*, src/lib/hook-template-chunks/*)
# ---------------------------------------------------------------------------

# 1 to force-enable the grep accelerator (otherwise auto-detected).
# INTERLINKED_GREP_ACCELERATOR=1
# Max old-space size (MB) for the harness daemon process.
# INTERLINKED_HARNESS_HEAP_MB=512
# Cap on captured tool-response bytes (event normalizers).
# INTERLINKED_TOOL_RESPONSE_MAX_BYTES=65536
# Cap on captured stderr bytes (event normalizers).
# INTERLINKED_STDERR_MAX_BYTES=8192

# ---------------------------------------------------------------------------
# Feature / guard toggles — set to 1 to disable the named behaviour
# ---------------------------------------------------------------------------

# Disable the inline graph-shard prediction path (src/hook-entry.ts).
# INTERLINKED_DISABLE_GRAPH_SHARD_INLINE=1
# Bypass the supply-chain package-install allowlist for ONE command (logged;
# intended only for documented bootstrap flows). src/hook-entry.ts.
# INTERLINKED_DISABLE_PACKAGE_GUARD=1
# Skip the project typecheck gate (src/harness/project-typecheck-gate.ts).
# INTERLINKED_SKIP_PROJECT_TYPECHECK=1
# Skip the project test gate.
# INTERLINKED_SKIP_PROJECT_TESTS=1
# Skip loading sanitizer overrides (src/harness/sanitizer-registry.ts).
# INTERLINKED_SKIP_SANITIZER_OVERRIDES=1
# Skip loading distilled (/enforce) rules (src/harness/rules-loader.ts).
# INTERLINKED_SKIP_DISTILLED_RULES=1
# Skip loading compiled rules (src/harness/rules-loader.ts).
# INTERLINKED_SKIP_COMPILED_RULES=1

# ---------------------------------------------------------------------------
# Standard runtime vars the CLI reads (set by your OS/CI, not configured here)
# ---------------------------------------------------------------------------

# Node environment (development / production / test).
# NODE_ENV=development
# Disable ANSI colour in output (any non-empty value).
# NO_COLOR=1
# Set by CI systems; switches output to non-interactive mode.
# CI=1
# Home directory — used to locate ~/.interlinked. USERPROFILE is the Windows form.
# HOME=/home/you
# USERPROFILE=C:\Users\you
# Current user — used as an agent-name fallback. USERNAME is the Windows form.
# USER=you
# USERNAME=you