---
title: "Configuration"
source: https://docs.autohand.ai/working-with-autohand-code/configuration
---

# Configuration

Configure Autohand CLI with global and project-level settings, and environment variables to customize its behavior to meet your needs.

## Overview

Autohand offers a variety of settings to configure its behavior. You can configure Autohand by running the `/config` command in interactive mode, which opens a settings interface where you can view status information and modify configuration options.

## Settings files

The `settings.json` file is the primary mechanism for configuring Autohand through hierarchical settings:

-   **User settings** are defined in `~/.autohand/settings.json` and apply to all projects.
-   **Project settings** are saved in your project directory:
    -   `.autohand/settings.json` for settings checked into source control and shared with your team
    -   `.autohand/settings.local.json` for settings that are not checked in, useful for personal preferences and experimentation. Autohand will configure git to ignore this file when created.
-   For enterprise deployments, **managed policy settings** take precedence over user and project settings. System administrators can deploy policies to:
    -   macOS: `/Library/Application Support/Autohand/managed-settings.json`
    -   Linux: `/etc/autohand/managed-settings.json`
    -   Windows: `C:\Program Files\Autohand\managed-settings.json`
-   **Other configuration** is stored in `~/.autohand/config.json`. This file contains your preferences (theme, notification settings), API keys, MCP server configurations, per-project state (allowed tools, trust settings), and various caches.

``` json
{
  "permissions": {
    "allow": [
      "run_command:npm run lint",
      "run_command:npm run test:*",
      "read_file:~/.zshrc"
    ],
    "deny": [
      "run_command:curl:*",
      "read_file:./.env",
      "read_file:./.env.*",
      "read_file:./secrets/**"
    ]
  },
  "env": {
    "AUTOHAND_ENABLE_TELEMETRY": "1"
  },
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
    "Reminder: Code reviews required for all PRs"
  ]
}
```

## Available settings

`settings.json` supports the following options:

| Key | Description | Example |
|---|---|---|
| apiKeyHelper | Custom script to generate an auth value for API requests | /bin/generate_temp_api_key.sh |
| cleanupPeriodDays | Sessions inactive for longer than this period are deleted at startup. Setting to 0 immediately deletes all sessions. (default: 30) | 20 |
| companyAnnouncements | Announcement to display to users at startup | ["Welcome to Acme Corp!"] |
| env | Environment variables applied to every session | {"FOO": "bar"} |
| attribution | Customize attribution for git commits and pull requests | {"commit": "Generated with Autohand", "pr": ""} |
| permissions | Permission rules for tool access. See permission settings below. |  |
| hooks | Custom commands to run before or after tool executions | {"PreToolUse": {"run_command": "echo 'Running...'"}} |
| disableAllHooks | Disable all hooks | true |
| model | Override the default model to use | "anthropic/claude-4-sonnet" |
| statusLine | Configure a custom status line to display context | {"type": "command", "command": "~/.autohand/statusline.sh"} |
| outputStyle | Configure an output style to adjust the system prompt | "Explanatory" |
| forceLoginMethod | Restrict login to specific account types | "api" |
| enableAllProjectMcpServers | Automatically approve all MCP servers defined in project .mcp.json files | true |
| enabledMcpjsonServers | List of specific MCP servers from .mcp.json to approve | ["memory", "github"] |
| disabledMcpjsonServers | List of specific MCP servers from .mcp.json to reject | ["filesystem"] |
| alwaysThinkingEnabled | Enable extended thinking by default for all sessions | true |
| contextCompact | Enable context compaction to automatically compress conversation history when nearing context limits | true |
| locale | Set the display language for the UI and agent responses (e.g., en, es, ja) | "en" |

## UI settings

Control how Autohand displays information in the terminal:

| Key | Description | Default |
|---|---|---|
| showThinking | Display LLM reasoning process during execution | false |
| showCompletionNotification | Show system notification when tasks complete | true |
| readFileCharLimit | Maximum characters to display when reading files | 300 |
| useInkRenderer | Use experimental React-based terminal rendering | false |
| theme | Terminal color theme (dark or light) | "dark" |
| locale | Display language for UI elements and agent responses | "en" |
| contextCompact | Enable automatic context compaction | false |

## Agent settings

Control how the AI agent operates:

| Key | Description | Default |
|---|---|---|
| maxIterations | Maximum tool iterations per request before stopping | 100 |
| enableRequestQueue | Queue additional requests while agent is working (max 10) | true |

## Network settings

Configure network behavior for API requests:

| Key | Description | Default |
|---|---|---|
| maxRetries | Number of retry attempts for failed requests (max 5) | 3 |
| timeout | Request timeout in milliseconds | 30000 |
| retryDelay | Delay between retries in milliseconds | 1000 |

``` json
{
  "network": {
    "maxRetries": 3,
    "timeout": 30000,
    "retryDelay": 1000
  }
}
```

## Search settings

Configure web search behavior for the agent:

| Key | Description | Default |
|---|---|---|
| provider | Search engine provider (google, brave, duckduckgo) | "google" |
| apiKey | API key for the search provider | - |
| maxResults | Maximum number of search results to return | 5 |

``` json
{
  "search": {
    "provider": "brave",
    "apiKey": "BSA-...",
    "maxResults": 10
  }
}
```

## Sync settings

Configure settings synchronization across devices:

| Key | Description | Default |
|---|---|---|
| enabled | Enable settings sync across devices | false |
| interval | Sync interval in seconds | 300 |
| exclude | Keys to exclude from sync | ["apiKey"] |
| consent | Whether the user has consented to sync | false |

``` json
{
  "sync": {
    "enabled": true,
    "interval": 300,
    "exclude": ["apiKey", "mcp.servers"],
    "consent": true
  }
}
```

## Extended thinking settings

Configure the agent's reasoning depth:

| Key | Description | Default |
|---|---|---|
| alwaysThinkingEnabled | Enable extended thinking by default for all sessions | false |
| thinkingLevel | Default thinking level (none, normal, extended) | "normal" |

``` json
{
  "alwaysThinkingEnabled": true,
  "thinkingLevel": "extended"
}
```

## YOLO mode settings

Configure auto-approval patterns in the permission settings:

``` json
{
  "permissions": {
    "allow": [
      "run_command:npm test:*",
      "run_command:git status:*",
      "run_command:git diff:*"
    ],
    "deny": [
      "run_command:rm -rf *",
      "run_command:sudo *"
    ],
    "yolo": {
      "enabled": false,
      "patterns": "allow:npm *,deny:rm *",
      "timeout": 30
    }
  }
}
```

The `yolo` block in permissions configures default YOLO mode behavior. Override at runtime with `--yolo` and `--timeout` flags.

## Permission settings

Configure granular permissions to control which tools Autohand can use:

| Key | Description | Example |
|---|---|---|
| allow | Array of permission rules to allow tool use | ["run_command:git diff:*"] |
| ask | Array of permission rules to ask for confirmation upon tool use | ["run_command:git push:*"] |
| deny | Array of permission rules to deny tool use. Use this to exclude sensitive files from Autohand access. | ["read_file:./.env", "read_file:./secrets/**"] |
| additionalDirectories | Additional working directories that Autohand has access to | ["../docs/"] |
| defaultMode | Default permission mode when opening Autohand | "acceptEdits" |
| disableBypassPermissionsMode | Set to "disable" to prevent unrestricted mode from being activated | "disable" |

### Excluding sensitive files

To prevent Autohand from accessing files containing sensitive information like API keys, secrets, and environment files, use the `permissions.deny` setting:

``` json
{
  "permissions": {
    "deny": [
      "read_file:./.env",
      "read_file:./.env.*",
      "read_file:./secrets/**",
      "read_file:./config/credentials.json",
      "read_file:./build"
    ]
  }
}
```

Files matching these patterns will be completely invisible to Autohand, preventing any accidental exposure of sensitive data.

## Sandbox settings

Configure advanced sandboxing behavior. Sandboxing isolates commands from your filesystem and network:

| Key | Description | Example |
|---|---|---|
| enabled | Enable command sandboxing (macOS/Linux only). Default: false | true |
| autoAllowIfSandboxed | Auto-approve commands when sandboxed. Default: true | true |
| excludedCommands | Commands that should run outside of the sandbox | ["git", "docker"] |
| allowUnsandboxedCommands | Allow commands to run outside the sandbox via escape hatch. Default: true | false |
| network.allowUnixSockets | Unix socket paths accessible in sandbox | ["~/.ssh/agent-socket"] |
| network.allowLocalBinding | Allow binding to localhost ports (macOS only). Default: false | true |

``` json
{
  "sandbox": {
    "enabled": true,
    "autoAllowIfSandboxed": true,
    "excludedCommands": ["docker"],
    "network": {
      "allowUnixSockets": ["/var/run/docker.sock"],
      "allowLocalBinding": true
    }
  },
  "permissions": {
    "deny": [
      "read_file:.envrc",
      "read_file:~/.aws/**"
    ]
  }
}
```

## Attribution settings

Autohand adds attribution to git commits and pull requests. These are configured separately:

-   **Commits** use git trailers (like `Co-Authored-By`) by default, which can be customized or disabled
-   **Pull request descriptions** are plain text

| Key | Description |
|---|---|
| commit | Attribution for git commits, including any trailers. Empty string hides commit attribution |
| pr | Attribution for pull request descriptions. Empty string hides PR attribution |

**Default commit attribution:**

``` text
Generated with Autohand CLI

Co-Authored-By: Autohand <noreply@autohand.ai>
```

**Example custom attribution:**

``` json
{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>",
    "pr": ""
  }
}
```

## Settings precedence

Settings apply in order of precedence. From highest to lowest:

1.  **Enterprise managed policies** (`managed-settings.json`) - Deployed by IT/DevOps, cannot be overridden
2.  **Command line arguments** - Temporary overrides for a specific session
3.  **Local project settings** (`.autohand/settings.local.json`) - Personal project-specific settings
4.  **Shared project settings** (`.autohand/settings.json`) - Team-shared project settings in source control
5.  **User settings** (`~/.autohand/settings.json`) - Personal global settings

This hierarchy ensures that enterprise security policies are always enforced while still allowing teams and individuals to customize their experience.

For example, if your user settings allow `run_command:npm run:*` but a project's shared settings deny it, the project setting takes precedence and the command is blocked.

## Key points about configuration

-   **Memory files (AGENTS.md)**: Contain instructions and context that Autohand loads at startup
-   **Settings files (JSON)**: Configure permissions, environment variables, and tool behavior
-   **Slash commands**: Custom commands that can be invoked during a session with `/command-name`
-   **MCP servers**: Extend Autohand with additional tools and integrations
-   **Precedence**: Higher-level configurations (Enterprise) override lower-level ones (User/Project)
-   **Inheritance**: Settings are merged, with more specific settings adding to or overriding broader ones

## Environment variables

Autohand supports the following environment variables to control its behavior. All environment variables can also be configured in `settings.json`:

| Variable | Purpose |
|---|---|
| AUTOHAND_API_KEY | API key for Autohand services |
| AUTOHAND_AUTH_TOKEN | Custom value for the Authorization header |
| AUTOHAND_CONFIG | Path to configuration file |
| AUTOHAND_MODEL | Name of the model to use |
| AUTOHAND_SECRET | Company secret for enterprise deployments |
| AUTOHAND_API_URL | Custom API endpoint URL |
| AUTOHAND_MAX_OUTPUT_TOKENS | Maximum number of output tokens for requests |
| AUTOHAND_SHELL_PREFIX | Command prefix to wrap all commands (for logging or auditing) |
| AUTOHAND_DISABLE_TELEMETRY | Set to 1 to opt out of telemetry |
| AUTOHAND_DISABLE_AUTOUPDATER | Set to 1 to disable automatic updates |
| AUTOHAND_DISABLE_ERROR_REPORTING | Set to 1 to opt out of error reporting |
| BASH_DEFAULT_TIMEOUT_MS | Default timeout for long-running commands |
| BASH_MAX_OUTPUT_LENGTH | Maximum characters in command outputs before truncation |
| BASH_MAX_TIMEOUT_MS | Maximum timeout the model can set for commands |
| MAX_THINKING_TOKENS | Token budget for extended thinking process |
| MCP_TIMEOUT | Timeout in milliseconds for MCP server startup |
| MCP_TOOL_TIMEOUT | Timeout in milliseconds for MCP tool execution |
| HTTP_PROXY | Specify HTTP proxy server for network connections |
| HTTPS_PROXY | Specify HTTPS proxy server for network connections |
| NO_PROXY | List of domains and IPs to bypass proxy |

## Tools available to Autohand

Autohand has access to a set of powerful tools that help it understand and modify your codebase:

| Tool | Description | Permission Required |
|---|---|---|
| ask_user_question | Asks multiple choice questions to gather information | No |
| run_command | Executes shell commands in your environment | Yes |
| read_file | Reads the contents of files | No |
| write_file | Creates or overwrites files | Yes |
| apply_patch | Makes targeted edits to specific files | Yes |
| search | Searches for patterns in file contents | No |
| list_tree | Finds files based on pattern matching | No |
| git_status | View repository state | No |
| git_commit | Stage and commit changes | Yes |
| delegate_task | Runs a sub-agent to handle complex tasks | No |
| todo_write | Creates and manages structured task lists | No |
| web_fetch | Fetches content from a specified URL | Yes |
| web_search | Performs web searches with domain filtering | Yes |

Permission rules can be configured using `/allowed-tools` or in permission settings.

## Subagent configuration

Autohand supports custom AI subagents that can be configured at both user and project levels. These subagents are stored as Markdown files with YAML frontmatter:

-   **User subagents**: `~/.autohand/agents/` - Available across all your projects
-   **Project subagents**: `.autohand/agents/` - Specific to your project and can be shared with your team

Subagent files define specialized AI assistants with custom prompts and tool permissions. Create new subagents with `/agents-new`.

## MCP server configuration

Configure MCP (Model Context Protocol) servers to extend Autohand with external tools. Servers can use stdio, SSE, or Streamable HTTP transports.

``` json
{
  "mcp": {
    "servers": [
      {
        "name": "database",
        "transport": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-postgres"],
        "autoConnect": true
      },
      {
        "name": "context7",
        "transport": "http",
        "url": "https://mcp.context7.com/mcp",
        "headers": { "CONTEXT7_API_KEY": "your-key" },
        "autoConnect": true
      }
    ]
  }
}
```

Manage servers via CLI (`autohand mcp add/list/remove`) or interactively with `/mcp`. See [MCP Servers](/docs/working-with-autohand-code/mcp-servers.html) for full documentation.

## Hook configuration

You can run custom commands before or after any tool executes using hooks. For example, you could automatically run a formatter after Autohand modifies files:

``` json
{
  "hooks": {
    "PostToolUse": {
      "write_file": {
        "matcher": "*.py",
        "command": "black {file}"
      }
    },
    "PreToolUse": {
      "run_command": {
        "matcher": "rm *",
        "command": "echo 'Warning: Deleting files'"
      }
    }
  }
}
```