Environment Variables

When running without a config file, the CLI reads these environment variables to configure the agent.

Variable Reference

Variable	Default	Description
`ANTHROPIC_API_KEY`	—	Anthropic API key (required for anthropic provider)
`OPENROUTER_API_KEY`	—	OpenRouter API key (required for openrouter provider)
`HEARTBIT_PROVIDER`	auto-detect	Force provider (`anthropic` / `openrouter`)
`HEARTBIT_MODEL`	`claude-sonnet-4-20250514`	Override model name
`HEARTBIT_MAX_TURNS`	`50` (`run`) / `200` (`chat`)	Max agent turns
`HEARTBIT_PROMPT_CACHING`	`false`	Enable Anthropic prompt caching (`1` or `true`)
`HEARTBIT_SUMMARIZE_THRESHOLD`	`80000`	Token count to trigger context summarization
`HEARTBIT_MAX_TOOL_OUTPUT_BYTES`	`32768`	Max bytes per tool output before truncation
`HEARTBIT_TOOL_TIMEOUT`	`120`	Tool execution timeout in seconds
`HEARTBIT_MCP_SERVERS`	—	Comma-separated MCP server URLs
`HEARTBIT_A2A_AGENTS`	—	Comma-separated A2A agent URLs
`HEARTBIT_REASONING_EFFORT`	—	Reasoning effort level (`high`, `medium`, `low`, `none`)
`HEARTBIT_ENABLE_REFLECTION`	`false`	Enable reflective reasoning (`1` or `true`)
`HEARTBIT_COMPRESSION_THRESHOLD`	—	Token threshold for context compression
`HEARTBIT_MAX_TOOLS_PER_TURN`	—	Max tool calls per turn
`HEARTBIT_TOOL_PROFILE`	—	Tool pre-filtering (`conversational`, `standard`, `full`)
`HEARTBIT_MAX_IDENTICAL_TOOL_CALLS`	—	Doom loop detection threshold
`HEARTBIT_SESSION_PRUNE`	`false`	Enable session pruning of old tool results (`1` or `true`)
`HEARTBIT_RECURSIVE_SUMMARIZATION`	`false`	Enable cluster-then-summarize (`1` or `true`)
`HEARTBIT_REFLECTION_THRESHOLD`	—	Cumulative importance threshold to trigger reflection
`HEARTBIT_CONSOLIDATE_ON_EXIT`	`false`	Consolidate memories at session end (`1` or `true`)
`HEARTBIT_MEMORY`	—	Memory backend (`in_memory` or a PostgreSQL URL)
`HEARTBIT_LSP_ENABLED`	`false`	Enable LSP integration (`1` or `true`)
`HEARTBIT_OBSERVABILITY`	`production`	Observability mode (`production`, `analysis`, `debug`, `off`)
`HEARTBIT_TELEGRAM_TOKEN`	—	Telegram bot token (daemon mode)
`HEARTBIT_API_KEY`	—	API key for daemon HTTP authentication
`EXA_API_KEY`	—	Exa AI API key (for `websearch` built-in tool)
`RUST_LOG`	—	Tracing filter (e.g. `info`, `debug`)

Provider Auto-Detection

When HEARTBIT_PROVIDER is not set, the CLI auto-detects the provider based on which API key is available:

If ANTHROPIC_API_KEY is set, uses the Anthropic provider
If OPENROUTER_API_KEY is set, uses the OpenRouter provider

Boolean Variables

Variables documented as accepting 1 or true treat both values as enabled. Any other value (or unset) means disabled.

Examples

# Minimal standalone setup
export ANTHROPIC_API_KEY=sk-ant-...
heartbit "Analyze this codebase"

# Custom model with prompt caching
export HEARTBIT_MODEL=claude-opus-4-20250514
export HEARTBIT_PROMPT_CACHING=true
heartbit "Write a detailed report"

# With MCP servers and session pruning
export HEARTBIT_MCP_SERVERS="http://localhost:8000/mcp,http://localhost:8001/mcp"
export HEARTBIT_SESSION_PRUNE=1
heartbit "Use the available tools to complete the task"

# OpenRouter with custom tool timeout
export OPENROUTER_API_KEY=sk-or-...
export HEARTBIT_PROVIDER=openrouter
export HEARTBIT_TOOL_TIMEOUT=300
heartbit "Long-running analysis task"

# Daemon mode with Telegram
export HEARTBIT_TELEGRAM_TOKEN=bot123:ABC...
export HEARTBIT_API_KEY=my-secret-key
heartbit daemon --config daemon.toml