Module: Anima::Settings

Defined in:
lib/anima/settings.rb

Overview

User-facing configuration backed by ~/.anima/config.toml with hot-reload.

Reads the TOML config file on each access, re-parsing only when the file’s mtime has changed. The config file is created by the installer with all values set — it is the single source of truth for all settings.

Settings are grouped into sections that mirror the TOML file structure:

[llm]       — Model selection and response limits
[timeouts]  — Network and execution timeouts (seconds)
[shell]     — Shell command output limits
[tools]     — File and web tool limits
[session]   — Conversation behavior

Examples:

Reading a setting

Anima::Settings.model          #=> "claude-sonnet-4-20250514"
Anima::Settings.api_timeout    #=> 30

Hot-reload (no restart needed)

Anima::Settings.model  #=> "claude-sonnet-4-20250514"
# user edits ~/.anima/config.toml: model = "claude-haiku-4-5"
Anima::Settings.model  #=> "claude-haiku-4-5"

See Also:

Defined Under Namespace

Classes: MissingConfigError, MissingSettingError

Constant Summary collapse

DEFAULT_PATH = 
File.expand_path("~/.anima/config.toml")

Class Method Summary collapse

Class Method Details

.agent_name ⇒ String

The agent’s display name. Separates engine identity (“Anima”) from agent identity — any agent running on Anima can name itself.

Returns:

  • (String) 


68
 
# File 'lib/anima/settings.rb', line 68

def agent_name = get("agent", "name")

.analytical_brain_blocking_on_agent_message ⇒ Boolean

Run the analytical brain asynchronously after the main agent completes.

Returns:

  • (Boolean) 


225
 
# File 'lib/anima/settings.rb', line 225

def analytical_brain_blocking_on_agent_message = get("analytical_brain", "blocking_on_agent_message")

.analytical_brain_blocking_on_user_message ⇒ Boolean

Run the analytical brain synchronously before the main agent on user messages.

Returns:

  • (Boolean) 


221
 
# File 'lib/anima/settings.rb', line 221

def analytical_brain_blocking_on_user_message = get("analytical_brain", "blocking_on_user_message")

.analytical_brain_max_tokens ⇒ Integer

Maximum tokens per analytical brain response.

Returns:

  • (Integer) 


217
 
# File 'lib/anima/settings.rb', line 217

def analytical_brain_max_tokens = get("analytical_brain", "max_tokens")

.analytical_brain_message_window ⇒ Integer

Number of recent messages to include in the analytical brain’s context window.

Returns:

  • (Integer) 


229
 
# File 'lib/anima/settings.rb', line 229

def analytical_brain_message_window = get("analytical_brain", "message_window")

.api_timeout ⇒ Integer

LLM API request timeout.

Returns:

  • (Integer) —

    seconds



103
 
# File 'lib/anima/settings.rb', line 103

def api_timeout = get("timeouts", "api")

.command_timeout ⇒ Integer

Shell command execution timeout.

Returns:

  • (Integer) —

    seconds



107
 
# File 'lib/anima/settings.rb', line 107

def command_timeout = get("timeouts", "command")

.completed_decay_messages ⇒ Integer

Number of meaningful messages (user + agent turns) after completion before a completed goal is automatically evicted from context.

Returns:

  • (Integer) 


236
 
# File 'lib/anima/settings.rb', line 236

def completed_decay_messages = get("goals", "completed_decay_messages")

.config_path ⇒ String

Returns active config file path.

Returns:

  • (String) —

    active config file path



53
54
55
 
# File 'lib/anima/settings.rb', line 53

def config_path
  @config_path || DEFAULT_PATH
end

.config_path=(path) ⇒ Object

Override config file path (for testing). Resets the cache so the next access reads from the new location.

Parameters:

  • path (String, nil) —

    custom path, or nil to restore default



46
47
48
49
50
 
# File 'lib/anima/settings.rb', line 46

def config_path=(path)
  @config_path = path
  @config_cache = nil
  @config_mtime = nil
end

.default_view_mode ⇒ String

View mode applied to new sessions: “basic”, “verbose”, or “debug”. Changing this setting only affects sessions created afterwards.

Returns:

  • (String)

Raises:



173
174
175
176
177
178
179
180
 
# File 'lib/anima/settings.rb', line 173

def default_view_mode
  value = get("session", "default_view_mode")
  unless Session::VIEW_MODES.include?(value)
    raise MissingSettingError,
      "[session] default_view_mode must be one of: #{Session::VIEW_MODES.join(", ")} (got #{value.inspect})"
  end
  value
end

.fast_model ⇒ String

Lightweight model for fast tasks (e.g. session naming).

Returns:

  • (String) —

    Anthropic model identifier



78
 
# File 'lib/anima/settings.rb', line 78

def fast_model = get("llm", "fast_model")

.github_label ⇒ String

Label applied to agent-created feature request issues.

Returns:

  • (String) 


211
 
# File 'lib/anima/settings.rb', line 211

def github_label = get("github", "label")

.github_repo ⇒ String

Repository for feature requests (owner/repo format). Falls back to parsing git remote origin when unset.

Returns:

  • (String) 


207
 
# File 'lib/anima/settings.rb', line 207

def github_repo = get("github", "repo")

.interrupt_check_interval ⇒ Numeric

Polling interval for user interrupt checks during long-running commands. Enforces a 0.5s floor to prevent busy-polling from misconfiguration.

Returns:

  • (Numeric) —

    seconds (minimum 0.5)



125
126
127
 
# File 'lib/anima/settings.rb', line 125

def interrupt_check_interval
  [get("timeouts", "interrupt_check"), 0.5].max
end

.max_file_size ⇒ Integer

Maximum file size for read/edit operations (bytes).

Returns:

  • (Integer) 


139
 
# File 'lib/anima/settings.rb', line 139

def max_file_size = get("tools", "max_file_size")

.max_output_bytes ⇒ Integer

Maximum bytes of command output before truncation.

Returns:

  • (Integer) 


133
 
# File 'lib/anima/settings.rb', line 133

def max_output_bytes = get("shell", "max_output_bytes")

.max_read_bytes ⇒ Integer

Maximum bytes returned by the read_file tool.

Returns:

  • (Integer) 


147
 
# File 'lib/anima/settings.rb', line 147

def max_read_bytes = get("tools", "max_read_bytes")

.max_read_lines ⇒ Integer

Maximum lines returned by the read_file tool.

Returns:

  • (Integer) 


143
 
# File 'lib/anima/settings.rb', line 143

def max_read_lines = get("tools", "max_read_lines")

.max_subagent_response_chars ⇒ Integer

Maximum characters of sub-agent result before head+tail truncation. Higher than tool threshold because sub-agent output is already curated.

Returns:

  • (Integer) 


165
 
# File 'lib/anima/settings.rb', line 165

def max_subagent_response_chars = get("tools", "max_subagent_response_chars")

.max_tokens ⇒ Integer

Maximum tokens per LLM response.

Returns:

  • (Integer) 


82
 
# File 'lib/anima/settings.rb', line 82

def max_tokens = get("llm", "max_tokens")

.max_tool_response_chars ⇒ Integer

Maximum characters of tool output before head+tail truncation. Full output saved to a temp file for paginated reading.

Returns:

  • (Integer) 


160
 
# File 'lib/anima/settings.rb', line 160

def max_tool_response_chars = get("tools", "max_tool_response_chars")

.max_tool_rounds ⇒ Integer

Maximum consecutive tool execution rounds per LLM message. Prevents runaway tool loops.

Returns:

  • (Integer) 


87
 
# File 'lib/anima/settings.rb', line 87

def max_tool_rounds = get("llm", "max_tool_rounds")

.max_web_response_bytes ⇒ Integer

Maximum bytes from web GET responses.

Returns:

  • (Integer) 


151
 
# File 'lib/anima/settings.rb', line 151

def max_web_response_bytes = get("tools", "max_web_response_bytes")

.mcp_response_timeout ⇒ Integer

MCP server response timeout.

Returns:

  • (Integer) —

    seconds



111
 
# File 'lib/anima/settings.rb', line 111

def mcp_response_timeout = get("timeouts", "mcp_response")

.min_web_content_chars ⇒ Integer

Minimum characters of extracted web content before flagging as possibly incomplete.

Returns:

  • (Integer) 


155
 
# File 'lib/anima/settings.rb', line 155

def min_web_content_chars = get("tools", "min_web_content_chars")

.mneme_l1_budget_fraction ⇒ Float

Fraction of the main viewport token budget reserved for L1 snapshots.

Returns:

  • (Float) 


250
 
# File 'lib/anima/settings.rb', line 250

def mneme_l1_budget_fraction = get("mneme", "l1_budget_fraction")

.mneme_l2_budget_fraction ⇒ Float

Fraction of the main viewport token budget reserved for L2 snapshots.

Returns:

  • (Float) 


254
 
# File 'lib/anima/settings.rb', line 254

def mneme_l2_budget_fraction = get("mneme", "l2_budget_fraction")

.mneme_l2_snapshot_threshold ⇒ Integer

Number of uncovered L1 snapshots that triggers L2 compression.

Returns:

  • (Integer) 


258
 
# File 'lib/anima/settings.rb', line 258

def mneme_l2_snapshot_threshold = get("mneme", "l2_snapshot_threshold")

.mneme_max_tokens ⇒ Integer

Maximum tokens per Mneme LLM response.

Returns:

  • (Integer) 


242
 
# File 'lib/anima/settings.rb', line 242

def mneme_max_tokens = get("mneme", "max_tokens")

.mneme_pinned_budget_fraction ⇒ Float

Fraction of the main viewport token budget reserved for pinned messages. Pinned messages appear between snapshots and the sliding window.

Returns:

  • (Float) 


263
 
# File 'lib/anima/settings.rb', line 263

def mneme_pinned_budget_fraction = get("mneme", "pinned_budget_fraction")

.mneme_viewport_fraction ⇒ Float

Fraction of the main viewport token budget allocated to Mneme’s viewport.

Returns:

  • (Float) 


246
 
# File 'lib/anima/settings.rb', line 246

def mneme_viewport_fraction = get("mneme", "viewport_fraction")

.model ⇒ String

Primary model for conversations.

Returns:

  • (String) —

    Anthropic model identifier



74
 
# File 'lib/anima/settings.rb', line 74

def model = get("llm", "model")

.name_generation_interval ⇒ Integer

Regenerate session name every N messages.

Returns:

  • (Integer) 


184
 
# File 'lib/anima/settings.rb', line 184

def name_generation_interval = get("session", "name_generation_interval")

.project_files_max_depth ⇒ Integer

Maximum directory depth for project file scanning.

Returns:

  • (Integer) 


200
 
# File 'lib/anima/settings.rb', line 200

def project_files_max_depth = get("environment", "project_files_max_depth")

.project_files_whitelist ⇒ Array<String>

Filenames to scan for in the working directory.

Returns:

  • (Array<String>) 


196
 
# File 'lib/anima/settings.rb', line 196

def project_files_whitelist = get("environment", "project_files")

.recall_budget_fraction ⇒ Float

Fraction of the main viewport token budget reserved for recalled memories.

Returns:

  • (Float) 


273
 
# File 'lib/anima/settings.rb', line 273

def recall_budget_fraction = get("recall", "budget_fraction")

.recall_max_results ⇒ Integer

Maximum search results returned per FTS5 query.

Returns:

  • (Integer) 


269
 
# File 'lib/anima/settings.rb', line 269

def recall_max_results = get("recall", "max_results")

.recall_max_snippet_tokens ⇒ Integer

Maximum tokens per individual recall snippet.

Returns:

  • (Integer) 


277
 
# File 'lib/anima/settings.rb', line 277

def recall_max_snippet_tokens = get("recall", "max_snippet_tokens")

.recall_recency_decay ⇒ Float

Recency decay factor for search ranking (0.0 = pure relevance).

Returns:

  • (Float) 


281
 
# File 'lib/anima/settings.rb', line 281

def recall_recency_decay = get("recall", "recency_decay")

.reset! ⇒ Object

Resets to default path and clears cached config. Useful in test teardown.



59
60
61
 
# File 'lib/anima/settings.rb', line 59

def reset!
  self.config_path = nil
end

.soul_path ⇒ String

Path to the soul file — the agent’s self-authored identity.

Returns:

  • (String) —

    absolute path



190
 
# File 'lib/anima/settings.rb', line 190

def soul_path = get("paths", "soul")

.thinking_budget ⇒ Integer

Maximum character length for the Think tool’s thoughts parameter. Sub-agents receive half this budget (their tasks are less complex).

Returns:

  • (Integer) 


97
 
# File 'lib/anima/settings.rb', line 97

def thinking_budget = get("llm", "thinking_budget")

.token_budget ⇒ Integer

Context window budget — tokens reserved for conversation history. Set this based on your model’s context window minus system prompt.

Returns:

  • (Integer) 


92
 
# File 'lib/anima/settings.rb', line 92

def token_budget = get("llm", "token_budget")

.tool_timeout ⇒ Integer

Per-tool-call timeout. Used as the default deadline for orphan detection and as the default value for the tool’s ‘timeout` input parameter.

Returns:

  • (Integer) —

    seconds



120
 
# File 'lib/anima/settings.rb', line 120

def tool_timeout = get("timeouts", "tool")

.web_request_timeout ⇒ Integer

Web fetch request timeout.

Returns:

  • (Integer) —

    seconds



115
 
# File 'lib/anima/settings.rb', line 115

def web_request_timeout = get("timeouts", "web_request")