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) 


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

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) 


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

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) 


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

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

.analytical_brain_max_tokens ⇒ Integer

Maximum tokens per analytical brain response.

Returns:

  • (Integer) 


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

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

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


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

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) 


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

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

.max_file_size ⇒ Integer

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

Returns:

  • (Integer) 


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

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

.max_output_bytes ⇒ Integer

Maximum bytes of command output before truncation.

Returns:

  • (Integer) 


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

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

.max_read_bytes ⇒ Integer

Maximum bytes returned by the read tool.

Returns:

  • (Integer) 


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

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

.max_read_lines ⇒ Integer

Maximum lines returned by the read tool.

Returns:

  • (Integer) 


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

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) 


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

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

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


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

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

.project_files_max_depth ⇒ Integer

Maximum directory depth for project file scanning.

Returns:

  • (Integer) 


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

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


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

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

.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



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

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

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