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

.analytical_brain_blocking_on_agent_message ⇒ Boolean

Run the analytical brain asynchronously after the main agent completes.

Returns:

  • (Boolean) 


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

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) 


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

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

.analytical_brain_event_window ⇒ Integer

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

Returns:

  • (Integer) 


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

def analytical_brain_event_window = get("analytical_brain", "event_window")

.analytical_brain_max_tokens ⇒ Integer

Maximum tokens per analytical brain response.

Returns:

  • (Integer) 


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

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

.api_timeout ⇒ Integer

LLM API request timeout.

Returns:

  • (Integer) —

    seconds



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

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

.command_timeout ⇒ Integer

Shell command execution timeout.

Returns:

  • (Integer) —

    seconds



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

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

.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:



140
141
142
143
144
145
146
147
 
# File 'lib/anima/settings.rb', line 140

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



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

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

.github_label ⇒ String

Label applied to agent-created feature request issues.

Returns:

  • (String) 


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

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) 


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

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

.max_file_size ⇒ Integer

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

Returns:

  • (Integer) 


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

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

.max_output_bytes ⇒ Integer

Maximum bytes of command output before truncation.

Returns:

  • (Integer) 


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

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

.max_read_bytes ⇒ Integer

Maximum bytes returned by the read tool.

Returns:

  • (Integer) 


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

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

.max_read_lines ⇒ Integer

Maximum lines returned by the read tool.

Returns:

  • (Integer) 


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

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

.max_tokens ⇒ Integer

Maximum tokens per LLM response.

Returns:

  • (Integer) 


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

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

.max_tool_rounds ⇒ Integer

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

Returns:

  • (Integer) 


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

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

.max_web_response_bytes ⇒ Integer

Maximum bytes from web GET responses.

Returns:

  • (Integer) 


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

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

.mcp_response_timeout ⇒ Integer

MCP server response timeout.

Returns:

  • (Integer) —

    seconds



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

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

.mneme_l1_budget_fraction ⇒ Float

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

Returns:

  • (Float) 


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

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) 


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

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) 


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

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

.mneme_max_tokens ⇒ Integer

Maximum tokens per Mneme LLM response.

Returns:

  • (Integer) 


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

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

.mneme_pinned_budget_fraction ⇒ Float

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

Returns:

  • (Float) 


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

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) 


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

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

.model ⇒ String

Primary model for conversations.

Returns:

  • (String) —

    Anthropic model identifier



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

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

.name_generation_interval ⇒ Integer

Regenerate session name every N messages.

Returns:

  • (Integer) 


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

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

.project_files_max_depth ⇒ Integer

Maximum directory depth for project file scanning.

Returns:

  • (Integer) 


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

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>) 


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

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) 


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

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

.recall_max_results ⇒ Integer

Maximum search results returned per FTS5 query.

Returns:

  • (Integer) 


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

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

.recall_max_snippet_tokens ⇒ Integer

Maximum tokens per individual recall snippet.

Returns:

  • (Integer) 


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

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) 


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

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



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

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

.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) 


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

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



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

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

.web_request_timeout ⇒ Integer

Web fetch request timeout.

Returns:

  • (Integer) —

    seconds



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

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