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) 


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

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) 


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

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) 


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

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) 


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

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

.api_timeout ⇒ Integer

LLM API request timeout.

Returns:

  • (Integer) —

    seconds



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

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

.command_timeout ⇒ Integer

Shell command execution timeout.

Returns:

  • (Integer) —

    seconds



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

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:



151
152
153
154
155
156
157
158
 
# File 'lib/anima/settings.rb', line 151

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) 


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

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) 


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

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

.max_file_size ⇒ Integer

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

Returns:

  • (Integer) 


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

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

.max_output_bytes ⇒ Integer

Maximum bytes of command output before truncation.

Returns:

  • (Integer) 


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

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

.max_read_bytes ⇒ Integer

Maximum bytes returned by the read tool.

Returns:

  • (Integer) 


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

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

.max_read_lines ⇒ Integer

Maximum lines returned by the read tool.

Returns:

  • (Integer) 


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

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

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


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

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

.mcp_response_timeout ⇒ Integer

MCP server response timeout.

Returns:

  • (Integer) —

    seconds



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

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) 


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

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) 


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

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) 


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

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) 


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

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

.mneme_max_tokens ⇒ Integer

Maximum tokens per Mneme LLM response.

Returns:

  • (Integer) 


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

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) 


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

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) 


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

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) 


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

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

.project_files_max_depth ⇒ Integer

Maximum directory depth for project file scanning.

Returns:

  • (Integer) 


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

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


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

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) 


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

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

.recall_max_results ⇒ Integer

Maximum search results returned per FTS5 query.

Returns:

  • (Integer) 


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

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

.recall_max_snippet_tokens ⇒ Integer

Maximum tokens per individual recall snippet.

Returns:

  • (Integer) 


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

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) 


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

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



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

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) 


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



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

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

.web_request_timeout ⇒ Integer

Web fetch request timeout.

Returns:

  • (Integer) —

    seconds



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

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