# Hacxgent Configuration Reference

Hacxgent is highly configurable, allowing you to tailor its behavior, integrated AI models, tools, and UI to your exact preferences. All settings are stored in a `settings.json` file, typically located at `~/.hacxgent/settings.json`.

You can manage your configuration in two ways:
1.  **Directly edit** the `settings.json` file.
2.  Use the **in-app `/config` command** for quick adjustments.

---

## Global Settings (`HacxgentConfig`)

These are the top-level settings controlling Hacxgent's core behavior and user experience.

### `active_model`
- **Type**: `string`
- **Default**: `""`
- **Description**: The alias of the AI model to use for all interactions. This must match an `alias` defined in the `models` array.
- **Example**: `"active_model": "mistral-large"`

### `animation`
- **Type**: `enum` (`"MATRIX"`, `"CAT"`, `"NONE"`)
- **Default**: `"MATRIX"`
- **Description**: Controls the animation displayed in the welcome banner.
    - `"MATRIX"`: The classic green falling code animation.
    - `"CAT"`: A playful cat animation.
    - `"NONE"`: Disables all banner animations.
- **Example**: `"animation": "CAT"`

### `vim_keybindings`
- **Type**: `boolean`
- **Default**: `false`
- **Description**: Enables Vim-style keybindings for the chat input. If set to `true`, you can use Vim commands to navigate and edit your input.
- **Example**: `"vim_keybindings": true`

### `disable_welcome_banner_animation`
- **Type**: `boolean`
- **Default**: `false`
- **Description**: Globally disables the welcome banner animation on startup. Set to `true` if you prefer a static banner.
- **Example**: `"disable_welcome_banner_animation": true`

### `autocopy_to_clipboard`
- **Type**: `boolean`
- **Default**: `true`
- **Description**: If `true`, any text selected in the terminal will automatically be copied to your system clipboard.
- **Example**: `"autocopy_to_clipboard": false`

### `displayed_workdir`
- **Type**: `string`
- **Default**: `""`
- **Description**: Overrides the displayed working directory in the UI's status bar. Useful for complex setups where the actual CWD isn't what you want to show.
- **Example**: `"displayed_workdir": "/app/src"`

### `auto_compact_threshold`
- **Type**: `integer`
- **Default**: `200000`
- **Description**: The token limit for the entire conversation history. If the total context tokens exceed this threshold, Hacxgent will perform a "hard compact" (summarizing the entire conversation into a single message) to reduce context size.
- **Example**: `"auto_compact_threshold": 150000`

### `memory_interval`
- **Type**: `integer`
- **Default**: `10`
- **Description**: The number of turns after which Hacxgent's "Smart Memory" middleware will attempt a "soft compact." In a soft compact, large tool outputs in the conversation history are redacted and replaced with summary tags, preserving context flow without losing too many tokens.
- **Example**: `"memory_interval": 5`

### `memory_threshold`
- **Type**: `integer`
- **Default**: `1000`
- **Description**: The minimum character length for a tool output message to be considered for redaction during a "soft compact" cycle. Tool outputs shorter than this will not be redacted.
- **Example**: `"memory_threshold": 500`

### `context_warnings`
- **Type**: `boolean`
- **Default**: `false`
- **Description**: If `true`, Hacxgent will inject warnings into the conversation when the context window is nearing its `auto_compact_threshold`.
- **Example**: `"context_warnings": true`

### `auto_approve`
- **Type**: `boolean`
- **Default**: `false`
- **Description**: If `true`, Hacxgent will automatically approve all tool executions without prompting the user. Use with extreme caution, preferably in sandboxed or trusted environments.
- **Example**: `"auto_approve": true`

### `system_prompt_id`
- **Type**: `string`
- **Default**: `"cli"`
- **Description**: Specifies which system prompt to load. Can be a built-in ID (e.g., `"cli"`) or the filename (without extension) of a custom `.md` file in `~/.hacxgent/prompts/`.
- **Example**: `"system_prompt_id": "my_custom_engineer_prompt"`

### `include_commit_signature`
- **Type**: `boolean`
- **Default**: `true`
- **Description**: If `true`, all `git commit` messages generated by the agent will automatically include a "Co-Authored-By: Hacxgent" signature.
- **Example**: `"include_commit_signature": false`

### `include_model_info`
- **Type**: `boolean`
- **Default**: `true`
- **Description**: If `true`, the system prompt will include information about the currently active AI model (name and capabilities).
- **Example**: `"include_model_info": false`

### `include_project_context`
- **Type**: `boolean`
- **Default**: `true`
- **Description**: If `true`, the system prompt will include a summary of the project's directory structure and Git status. This helps the agent understand the codebase's layout.
- **Example**: `"include_project_context": false`

### `include_prompt_detail`
- **Type**: `boolean`
- **Default**: `true`
- **Description**: If `true`, the system prompt will include detailed information about available tools and skills.
- **Example**: `"include_prompt_detail": false`

### `enable_update_checks`
- **Type**: `boolean`
- **Default**: `false`
- **Description**: If `true`, Hacxgent will periodically check for new versions and notify you of available updates.
- **Example**: `"enable_update_checks": true`

### `api_timeout`
- **Type**: `float`
- **Default**: `720.0`
- **Description**: The maximum duration (in seconds) to wait for a response from the LLM provider API. Increase this for models with longer response times or complex queries.
- **Example**: `"api_timeout": 300.0`

### `theme_color`
- **Type**: `string` (hex color code)
- **Default**: `"#00BFFF"` (Hacxgent Blue)
- **Description**: Sets the primary theme color for the Hacxgent UI. Use standard hex color codes.
- **Example**: `"theme_color": "#FFD700"` (Gold)

### `show_banner`
- **Type**: `boolean`
- **Default**: `true`
- **Description**: If `true`, the welcome banner will be displayed on startup.
- **Example**: `"show_banner": false`

## Nested Configurations

Hacxgent uses nested configuration objects for more granular control over specific components.

### `project_context` (`ProjectContextConfig`)

Controls how Hacxgent scans and summarizes your project's directory structure.

- **`max_chars`**: `integer` (Default: `40000`). Maximum characters for the entire project context summary.
- **`default_commit_count`**: `integer` (Default: `5`). Number of recent Git commits to include in the project context.
- **`max_doc_bytes`**: `integer` (Default: `32768`). Maximum bytes to read from a `README` or similar project documentation file.
- **`truncation_buffer`**: `integer` (Default: `1000`). Buffer for character-based truncation of project context.
- **`max_depth`**: `integer` (Default: `3`). Maximum directory depth to scan when building the project tree.
- **`max_files`**: `integer` (Default: `1000`). Maximum number of files to include in the directory structure summary.
- **`max_dirs_per_level`**: `integer` (Default: `20`). Maximum number of directories to list per level in the tree structure.
- **`timeout_seconds`**: `float` (Default: `2.0`). Timeout (in seconds) for generating the project context summary.

### `session_logging` (`SessionLoggingConfig`)

Manages the logging and persistence of your Hacxgent sessions.

- **`save_dir`**: `string` (Default: `~/.hacxgent/logs/sessions`). Directory where session logs are saved.
- **`session_prefix`**: `string` (Default: `"session"`). Prefix for session log filenames.
- **`enabled`**: `boolean` (Default: `true`). Enables or disables session logging. Set to `false` for privacy or to prevent log file creation.

## AI Model & Provider Configuration

Hacxgent's LLM backend is completely pluggable. You define your AI providers and models.

### `providers` (Array of `ProviderConfig`)

Defines the API endpoints and authentication details for your LLM providers.

- **`name`**: `string` (Required). A unique name for the provider (e.g., `"Groq"`, `"OpenAI"`).
- **`api_base`**: `string` (Required). The base URL for the provider's API (e.g., `"https://api.groq.com/openai/v1"`).
- **`api_key_env_var`**: `string` (Default: `""`). The name of the environment variable (e.g., `"GROQ_API_KEY"`) that holds your API key for this provider.
- **`api_style`**: `string` (Default: `"openai"`). The API style/protocol the provider adheres to. Hacxgent currently primarily supports the OpenAI API format.
- **`backend`**: `enum` (`"HACXGENT"`, `"GENERIC"`) (Default: `"GENERIC"`). Specifies the backend driver. `"HACXGENT"` for custom Hacxgent backends, `"GENERIC"` for standard API adherence.
- **`reasoning_field_name`**: `string` (Default: `"reasoning_content"`). The field name in the LLM's response that contains reasoning or thought process.

### `models` (Array of `ModelConfig`)

Defines the specific AI models available from your configured providers.

- **`name`**: `string` (Required). The model identifier used by the provider (e.g., `"llama3-8b-8192"`, `"gpt-4o"`).
- **`provider`**: `string` (Required). The `name` of a provider defined in the `providers` array.
- **`alias`**: `string` (Default: same as `name`). A shorter, human-readable alias for the model, used in the `active_model` setting.
- **`temperature`**: `float` (Default: `0.2`). Controls the randomness of the model's output. Lower values mean more deterministic results.
- **`input_price`**: `float` (Default: `0.0`). Cost per million input tokens for this model (in USD). Used for session cost tracking.
- **`output_price`**: `float` (Default: `0.0`). Cost per million output tokens for this model (in USD). Used for session cost tracking.
- **`rate_limit_rpm`**: `integer` (Default: `0`). Rate limit for this model in requests per minute (RPM). Set to `0` for no client-side rate limiting.
- **`max_context_tokens`**: `integer` (Default: `0`). The maximum number of tokens this model can handle in its context window. Set to `0` to use the provider's default.

## Tool & Skill Management

Hacxgent's extensibility comes from its robust tool and skill management system.

### `tools` (Object of `BaseToolConfig`)

Allows overriding default configurations or permissions for individual tools. The keys are tool names (e.g., `"bash"`, `"read_file"`).

- **`permission`**: `enum` (`"ASK"`, `"ALWAYS"`, `"NEVER"`) (Default: `"ASK"` for most tools).
    - `"ASK"`: Hacxgent will prompt for user approval before executing the tool.
    - `"ALWAYS"`: The tool will execute automatically without prompting.
    - `"NEVER"`: The tool will never execute and will be effectively disabled.
- **Example**:
    ```json
    "tools": {
      "bash": {
        "permission": "ASK",
        "default_timeout": 60
      },
      "read_file": {
        "permission": "ALWAYS",
        "max_read_bytes": 128000
      }
    }
    ```
    (Note: Specific tools may have additional configuration fields like `default_timeout` or `max_read_bytes` for `bash` and `read_file` respectively. These are tool-specific and can be found in the tool's documentation.)

### `tool_paths`
- **Type**: `array of strings`
- **Default**: `[]`
- **Description**: A list of additional file system paths where Hacxgent should look for custom tools. These paths are scanned recursively.
- **Example**: `"tool_paths": ["/my/custom/tools", "./project_tools"]`

### `mcp_servers` (Array of `MCPServer`)

Configures connections to external Model Context Protocol (MCP) servers, which extend Hacxgent's toolset. Each entry can be an HTTP, Streamable HTTP, or STDIO server.

- **Common Fields for all `MCPServer` types**:
    - **`name`**: `string` (Required). A short alias used to prefix tools provided by this server (e.g., "my_server_tool_name").
    - **`prompt`**: `string` (Optional). An optional usage hint appended to tool descriptions.
    - **`startup_timeout_sec`**: `float` (Default: `10.0`). Timeout (in seconds) for the server to start and initialize.
    - **`tool_timeout_sec`**: `float` (Default: `60.0`). Timeout (in seconds) for individual tool executions from this server.

- **Specific Fields for `HTTP` and `STREAMABLE_HTTP` transports**:
    - **`transport`**: `string` (Must be `"http"` or `"streamable-http"`).
    - **`url`**: `string` (Required). Base URL of the MCP HTTP server.
    - **`headers`**: `object` (Default: `{}`). Additional HTTP headers (e.g., `{"Authorization": "Bearer token"}`).
    - **`api_key_env`**: `string` (Optional). Environment variable name containing an API token to send.
    - **`api_key_header`**: `string` (Default: `"Authorization"`). HTTP header name to carry the token (e.g., `"X-API-Key"`).
    - **`api_key_format`**: `string` (Default: `"Bearer {token}"`). Format string for the header value, `{token}` is a placeholder.

- **Specific Fields for `STDIO` transport**:
    - **`transport`**: `string` (Must be `"stdio"`).
    - **`command`**: `string` or `array of strings` (Required). The command to run the STDIO server.
    - **`args`**: `array of strings` (Default: `[]`). Additional arguments for the command.
    - **`env`**: `object` (Default: `{}`). Environment variables to set for the server process.

- **Example (`mcp_servers`)**:
    ```json
    "mcp_servers": [
      {
        "name": "my_local_mcp",
        "transport": "stdio",
        "command": "python",
        "args": ["-m", "my_mcp_server_module"],
        "env": {"DEBUG": "1"},
        "startup_timeout_sec": 5.0
      },
      {
        "name": "remote_tool_api",
        "transport": "http",
        "url": "https://api.example.com/mcp",
        "api_key_env": "MY_REMOTE_API_KEY",
        "api_key_header": "X-API-TOKEN"
      }
    ]
    ```

### `enabled_tools`
- **Type**: `array of strings`
- **Default**: `[]` (empty, meaning all tools are enabled by default)
- **Description**: A list of tool names (or patterns) to explicitly enable. If this list is not empty, only tools matching these patterns will be active. Supports exact names, glob patterns (e.g., `"bash*"`), or regex with `re:` prefix (e.g., `"re:^my_custom_tool_.*$"`).
- **Example**: `"enabled_tools": ["bash", "file_meta", "re:^my_custom_tool_.*$"]`

### `disabled_tools`
- **Type**: `array of strings`
- **Default**: `[]`
- **Description**: A list of tool names (or patterns) to explicitly disable. These tools will not be available to the agent. Supports exact names, glob patterns, or regex.
- **Example**: `"disabled_tools": ["bash", "file_operations"]`

### `agent_paths`
- **Type**: `array of strings`
- **Default**: `[]`
- **Description**: Additional file system paths where Hacxgent should look for custom agent configurations.
- **Example**: `"agent_paths": ["/my/custom/agents"]`

### `enabled_agents`
- **Type**: `array of strings`
- **Default**: `[]` (empty, meaning all agents are enabled by default)
- **Description**: Similar to `enabled_tools`, but for agent profiles. Only agents matching these patterns will be available.
- **Example**: `"enabled_agents": ["default", "my_special_agent"]`

### `disabled_agents`
- **Type**: `array of strings`
- **Default**: `[]`
- **Description**: Similar to `disabled_tools`, but for agent profiles. Agents matching these patterns will be unavailable.
- **Example**: `"disabled_agents": ["auto-approve"]`

### `skill_paths`
- **Type**: `array of strings`
- **Default**: `[]`
- **Description**: Additional file system paths where Hacxgent should look for custom skills.
- **Example**: `"skill_paths": ["/my/custom/skills"]`

### `enabled_skills`
- **Type**: `array of strings`
- **Default**: `[]` (empty, meaning all skills are enabled by default)
- **Description**: Similar to `enabled_tools`, but for skills. Only skills matching these patterns will be active.
- **Example**: `"enabled_skills": ["code-review", "testing-skill"]`

### `disabled_skills`
- **Type**: `array of strings`
- **Default**: `[]`
- **Description**: Similar to `disabled_tools`, but for skills. Skills matching these patterns will be unavailable.
- **Example**: `"disabled_skills": ["experimental-feature"]`

---
This comprehensive guide should provide all the necessary details for configuring Hacxgent to your exact needs.