These variables control how agentihooks init installs and configures Claude Code. They are read at install time, not at hook runtime.
Variable
Default
Description
CLAUDE_CODE_HOME_DIR
$HOME
Home-directory root override. When set, agentihooks targets $CLAUDE_CODE_HOME_DIR/.claude for all install operations. Use when $HOME differs from where Claude Code stores its config (e.g. shared volumes).
AGENTIHOOKS_CLAUDE_HOME
~/.claude
Legacy: direct path to the .claude directory. CLAUDE_CODE_HOME_DIR takes priority if both are set.
AGENTIHOOKS_PROFILE
default
Profile to use when --profile is not passed on the command line. Controls which CLAUDE.md, settings overrides, and MCP category selection are applied.
AGENTIHOOKS_MCP_FILE
–
Absolute path to an MCP JSON file. When set, agentihooks init automatically merges the servers from this file into user-scope config (~/.claude.json). The path is recorded in state.json so subsequent runs re-apply it. Useful for CI/Docker automation where a gateway MCP file is injected at container start.
Global
Variable
Default
Description
AGENTIHOOKS_HOME
~/.agentihooks
Root directory for all runtime data: logs, memory, state. Set to a shared mount for Kubernetes deployments.
MCP_CATEGORIES
all
Comma-separated list of MCP tool categories to load. Valid values: channels,enforcement,agent_pool (see hooks/mcp/_registry.py).
ALLOWED_TOOLS
–
Legacy: comma-separated list of specific tool names. Takes precedence over category filtering after categories are loaded.
ENABLE_TOOL_SEARCH
true
Set in the env block of settings.json. Makes all MCP tools lazy-loaded on demand – shown as “(loaded on-demand)” in /context. Eliminates approximately 79K token upfront cost from MCP tool schemas.
MCP Transport
Only relevant when running hooks-utils as a network server instead of a per-session stdio subprocess – for clients that filter stdio MCP servers out at load time. See MCP Transport for the full setup.
Variable
Default
Description
MCP_TRANSPORT
stdio
stdio, sse, or streamable-http. An unrecognised value warns on stderr and falls back to stdio.
MCP_HOST
localhost
Bind address for network transports, and the host written into the ~/.claude.json url. The loopback bind is the only access boundary – neither transport carries authentication. Spelled localhost rather than 127.0.0.1 deliberately: an enterprise policy was observed dropping a dotted-quad entry from the client’s configured-server set outright. See MCP Transport.
MCP_SCHEME
http
Scheme in the ~/.claude.json url. The daemon serves plaintext, which is correct for a loopback bind; set https only when a TLS reverse proxy fronts it.
AGENTIHOOKS_MCP_SUPERVISOR
auto
Daemon supervisor: systemd where a user bus exists, pidfile otherwise. Force either to exercise both paths on one machine; an unrecognised value warns on stderr and falls back to detection. Drive the daemon with agentihooks mcp start\|stop\|restart\|status.
MCP_PORT
8642
Bind port for network transports.
MCP_SSE_PATH
/sse
Event-stream path under sse.
MCP_STREAMABLE_HTTP_PATH
/mcp
Endpoint path under streamable-http.
MCP_STATELESS_HTTP
false
Stateless HTTP mode. Only relevant behind a non-sticky reverse proxy.
MCP_SESSION_ID_BANNER_ENABLED
true
Inject the session’s own id at SessionStart, so the agent can pass it to the session-scoped tools (call_agent, pool_list, pool_status, channel_acknowledge). Required under a network transport, where one process serves every session and the environment cannot identify the caller.
AGENTIHOOKS_MCP_TRANSPORT
–
Read by agentihooks init only, overriding MCP_TRANSPORT for that run. Use for a one-off install without editing ~/.agentihooks/.env.
Logging
Variable
Default
Description
LOG_ENABLED
true
Enable or disable hook logging entirely.
CLAUDE_HOOK_LOG_FILE
~/.agentihooks/logs/hooks.log
Hook event log file path.
AGENT_LOG_FILE
~/.agentihooks/logs/agent.log
Agent transcript log file path.
LOG_TRANSCRIPT
true
Auto-log conversation transcript entries on each hook event.
STREAM_AGENT_LOG
true
Stream transcript to AGENT_LOG_FILE in real-time.
LOG_HOOKS_COMMANDS
false
Enable verbose command output logging.
LOG_USE_COLORS
true
ANSI colors in log output. Set false for CloudWatch Logs.
Memory
Variable
Default
Description
MEMORY_AUTO_SAVE
true
Auto-save session digest to memory store on Stop event.
REDIS_URL
–
Redis connection string. Format: redis://:PASSWORD@host:port/db. Used by token monitor (burn rate), file read cache (dedup), and warning edge-triggers. All features degrade gracefully when Redis is unavailable. Uses DB0 on the shared Redis instance (same as agenticore). Leave unset to use in-memory/JSONL fallback.
REDIS_SESSION_TTL
86400
Session TTL in seconds (24 hours).
REDIS_POSITION_TTL
3600
Position TTL in seconds (1 hour).
REDIS_KEY_PREFIX
agenticore
Redis key prefix for all stored keys.
REDIS_SOCKET_TIMEOUT
5.0
Redis socket timeout in seconds.
Token Control
Controls the Token Control Layer, which reduces context window consumption in agentic sessions. All features are individually disableable. Requires Redis for burn-rate tracking and edge-trigger warnings; degrades gracefully without it.
Variable
Default
Description
TOKEN_CONTROL_ENABLED
true
Master switch. Set false to disable all token control features at once.
TOKEN_MONITOR_ENABLED
true
Enable the statusLine script (hooks/statusline.py) context window monitor. Outputs a 3-line status bar (line 1: fill %, model, cost; line 2: token counts, burn rate, cache ratio, git branch; line 3: active agentihooks profile, settings-profile, channels subscription list from AGENTIHOOKS_BASE_CHANNELS) plus a conditional 4th line for threshold warnings, native rate limits, or peak/off-peak indicator. used_pct is recomputed from total_input_tokens / context_window_size * 100 to avoid stale payload values.
TOKEN_WARN_PCT
60
Fill percentage at which a warning banner is injected into Claude’s context. Edge-triggered: fires only once per session per threshold level.
TOKEN_CRITICAL_PCT
80
Fill percentage at which a critical banner is injected.
TOKEN_REDIS_TTL
3600
TTL (seconds) for Redis keys storing token metrics and warning state.
BASH_FILTER_ENABLED
true
Truncate verbose bash command output before it enters the context window.
BASH_FILTER_MAX_LINES
50
Line limit for docker/kubectl output (keeps last N lines).
BASH_FILTER_MAX_CHARS
5000
Character cap for build and generic output.
BASH_FILTER_TEST_MAX_FAILURES
10
Maximum FAILED blocks to retain from test runner output.
BASH_FILTER_GIT_MAX_COMMITS
20
Maximum commits to retain from git log output.
FILE_READ_CACHE_ENABLED
true
Block redundant re-reads of unmodified files within a session. Files modified since last read are always allowed through (mtime guard).
FILE_READ_CACHE_BACKEND
redis
Cache backend. redis uses the configured REDIS_URL; any other value forces the in-process memory fallback.
FILE_READ_CACHE_TTL
21600
TTL (seconds) for Redis cache keys (6 hours).
MCP_HYGIENE_ENABLED
true
Inject an MCP server usage reminder at SessionStart prompting Claude to disable unused servers via /mcp.
CONTEXT_AUDIT_ENABLED
true
Track cumulative byte output per tool type across the session. Emits an audit report on Stop when fill exceeds CONTEXT_AUDIT_THRESHOLD_PCT.
CONTEXT_AUDIT_THRESHOLD_PCT
70
Context fill % threshold for emitting the audit report on Stop.
COMPACT_SUGGEST_ENABLED
true
Replace generic “/compact” warnings with smart suggestions showing top context consumers from audit data.
EFFORT_POLICY_ENABLED
true
Inject thinking/effort guidance at SessionStart based on DEFAULT_EFFORT. Warns on PostToolUse when Agent tool spawns with unnecessarily expensive models.
DEFAULT_EFFORT
medium
Default reasoning effort level: low, medium, or high. Controls guidance injected at session start.
THINKING_BUDGET_TOKENS
0
Advisory thinking token ceiling per response. 0 = no limit.
PEAK_HOURS_ENABLED
true
Show peak/off-peak indicator on statusline line 3. Detects Anthropic peak billing hours (weekday business hours).
PEAK_HOURS_START
9
Peak start hour (in target timezone).
PEAK_HOURS_END
17
Peak end hour (exclusive).
PEAK_HOURS_TZ
US/Pacific
IANA timezone name for peak hour detection.
MCP_TOOL_WARN_THRESHOLD
40
Warn at SessionStart if total MCP tools across all servers exceed this count.
MCP_SCHEMA_AVG_TOKENS
150
Estimated tokens per MCP tool schema (used in agentihooks mcp report).
CLAUDE.md Sanity Check
Guardrail that prevents agents from bloating CLAUDE.md and CLAUDE.local.md files past a configurable line limit. Runs on every PreToolUse event for Write and Edit tools. Enabled by default.
For Write: counts lines in the new content. For Edit: reads the current file from disk, simulates the replacement, and counts resulting lines. If the result exceeds the limit, the tool call is blocked (exit code 2) with a message telling the agent the current/resulting line count and the cap.
Variable
Default
Description
AGENTIHOOKS_CLAUDE_MD_SANITY_CHECK
true
Enable/disable the guardrail. Set false or 0 to allow unrestricted edits.
AGENTIHOOKS_CLAUDE_MD_MAXLINES
200
Maximum allowed lines in CLAUDE.md / CLAUDE.local.md files.
Context Preprocessor (token compression)
Periodic rules / CLAUDE.md re-injection was removed on 2026-07-20. Claude Code loads ~/.claude/CLAUDE.md, the project CLAUDE.md, and every ~/.claude/rules/*.md at position 0 for the whole session. Re-emitting those same bytes every N turns spent thousands of duplicate tokens per session and broke the prompt-cache prefix on each refresh, for a re-emphasis the brain drumbeat and the enforcement cadence already provide more cheaply. Live re-emphasis of edited rules still ships to running sessions via the one-shot agentihooks refresh-rules path.
The token-compression preprocessor survives — it still compresses injected broadcast banners and verbose tool output. The variables keep their historical CONTEXT_REFRESH_* names for config back-compat; they no longer gate any periodic re-injection.
all compresses all injections + tool output. refresh (default) is a no-op — it once scoped compression to the removed context-refresh payload; set all to get any compression.
CONTEXT_REFRESH_ABBREV_FILE
(empty)
Path to user-supplied abbreviation dictionary (JSON). Merged on top of built-in.
Broadcast System
Variable
Default
Description
BROADCAST_ENABLED
true
Enable/disable the broadcast system.
BROADCAST_FILE
~/.agentihooks/broadcast.json
Path to the broadcast file. Set to a shared mount for multi-node deployments.
BROADCAST_MAX_MESSAGES
50
Maximum concurrent broadcasts. Oldest expire first when limit is reached.
BROADCAST_CRITICAL_ON_PRETOOL
true
Inject critical broadcasts on PreToolUse via additionalContext JSON.
AGENTIHOOKS_BASE_CHANNELS
"" (empty)
Comma-separated channel subscription floor. Default ships in profiles/default/.claude/settings.overrides.json env block as "brain,amygdala". Layered: profile env → repo .claude/settings.json env → repo .claude/settings.local.json env → container launch ENV (highest). Empty / unset → session only receives global broadcasts (no channel field). Wildcard * subscribes to everything. Whitespace and duplicates are trimmed/deduped at parse time. Mid-session change requires a session restart.
See Broadcast System for full architecture and CLI documentation.
Tool Memory
Variable
Default
Description
AGENTICORE_TOOL_MEMORY_PATH
~/.agenticore_tool_memory.ndjson
Path to the tool error memory file.
AGENTICORE_TOOL_MEMORY_MAX
100
Maximum number of error entries to store.
AGENTICORE_TOOL_MEMORY_SHOW
15
Number of entries to inject per PreToolUse event.
Session Context
Variable
Default
Description
AGENTICORE_CORRELATION_ID
–
Correlation ID for distributed tracing. Injected into outgoing payloads.
AGENTICORE_CLAUDE_SESSION_ID
–
Claude Code session ID override.
AGENTICORE_AGENT
unknown
Agent identifier tag.
AGENT_NAME
Agent
Agent display name for notifications and logs.
CLAUDE_CODE_MAX_OUTPUT_TOKENS
–
Output token limit. Injected into session context if set.
Email / SMTP
Variable
Default
Description
SMTP_SERVER
–
SMTP server hostname.
SMTP_PORT
25
SMTP port.
SMTP_SERVER_IP
–
Optional fallback IP for the SMTP server.
SMTP_USER
–
SMTP username (authenticated mode only).
SMTP_PASS
–
SMTP password (authenticated mode only).
SENDER_EMAIL
–
From address for all outgoing email.
Storage (S3)
Variable
Default
Description
STORAGE_URL
–
S3 URL or endpoint (e.g., s3://my-bucket).
IS_EVALUATION
false
Evaluation mode – skips actual upload.
Database
DynamoDB
Variable
Default
Description
DYNAMODB_TABLE_NAME
–
DynamoDB table name.
DYNAMODB_PARTITION_KEY
session_id
Partition key attribute name.
DYNAMODB_SORT_KEY
–
Sort key attribute name. Omit for tables with no sort key.
DYNAMODB_ENDPOINT_URL
–
Custom DynamoDB endpoint (for DynamoDB Local in testing).
IS_EVALUATION
false
Evaluation mode – skips actual write.
PostgreSQL
Variable
Default
Description
POSTGRES_HOST
–
Database host.
POSTGRES_NAME
–
Database name.
POSTGRES_USERNAME
–
Username.
POSTGRES_PASSWORD
–
Password.
POSTGRES_PORT
5432
Port.
POSTGRES_TABLE
–
Default table name.
IS_EVALUATION
false
Evaluation mode – skips actual write.
Compute (Lambda)
Variable
Default
Description
LAMBDA_FUNCTION_NAME
–
Lambda function ARN or name.
LAMBDA_INVOCATION_TYPE
RequestResponse
Default invocation type. RequestResponse (sync) or Event (async).
IS_EVALUATION
false
Evaluation mode – skips actual invocation.
AWS (Config reader)
Variable
Default
Description
AWS_CONFIG_FILE
~/.aws/config
Path to AWS config file.
Evaluation mode
IS_EVALUATION=true is a shared flag recognized by storage, database, and compute integrations. When set, tools skip their actual external calls and return a simulated success response. Useful for testing agent logic without side effects.
Variable
Integrations affected
IS_EVALUATION
S3, DynamoDB, PostgreSQL, Lambda
Brain Adapter
Variable
Default
Description
BRAIN_ENABLED
false
Enable the brain adapter for knowledge injection via broadcast channels.
BRAIN_SOURCE_TYPE
file
Brain source backend. Currently only file is shipped.
Broadcast channel the brain adapter publishes to (producer side). Sessions only receive brain content if this channel name is in their AGENTIHOOKS_BASE_CHANNELS env. The default profile ships "brain,amygdala", so the default brain value works out of the box; if you rename this, update subscriptions to match.
BRAIN_REFRESH_INTERVAL
30
Re-inject brain content every N turns (counter-gated).
HARD-FLOOR live-patching guard. PreToolUse Bash hook that blocks kubectl exec/cp writes, kubectl edit/patch/set/scale/rollout-restart/annotate/label/drain/debug/create -f/apply -f/autoscale, helm install/upgrade/rollback outside CI, argocd app sync --local, SSH-edit, scp INTO host, and docker exec writes. Does NOT honor bypass mode, hotfix signals, or release-gate signals — code is the source of truth. See CI Manifesto §3.5 and rules/code-is-source.md.