Configuration

Start with the settings UI

Run /settings in an interactive session or autohand --settings from a shell for common UI, agent, session, permission, network, telemetry, auto-mode, team, and search settings. Edit the config file directly for provider blocks, hooks, MCP servers, custom themes, extension providers, and advanced policy.

autohand --setup
autohand --settings
autohand config set ui.promptSuggestions false
autohand config set sessions.awareness coordinate
autohand --permissions

Configuration files and lookup

Autohand selects one user configuration source in this order:

1. An explicit --config <path>
2. The AUTOHAND_CONFIG environment variable
3. $AUTOHAND_HOME/config.toml
4. $AUTOHAND_HOME/config.yaml
5. $AUTOHAND_HOME/config.yml
6. $AUTOHAND_HOME/config.json

AUTOHAND_HOME defaults to ~/.autohand. Keep only one of the four standard config files in that directory; multiple formats are rejected instead of being merged. JSON is created with safe defaults on first run when no file exists.

Project-local overlay

When a workspace is known, Autohand also reads .autohand/settings.local.json. The overlay supports provider, model, agent, network, telemetry, and permissions. Those values override or merge with the user config for that workspace.

{
  "version": 1,
  "provider": "openrouter",
  "model": "anthropic/claude-sonnet-4",
  "agent": {
    "maxIterations": 80
  },
  "permissions": {
    "allowList": ["run_command:npm test", "run_command:npm run lint"],
    "denyList": ["run_command:npm publish"]
  }
}

Keep this file local when it contains personal approvals. Project-scoped extensions, agents, skills, hooks, and MCP servers have their own documented storage and lifecycle; do not place arbitrary top-level user config inside this overlay.

Effective precedence

Explicit CLI flags control the current process. For persistent settings, the project overlay is merged over the selected user config, then supported environment variables override API and provider fields. A feature-specific runtime flag such as --no-idle-logout, --offline, or --no-browser applies last for that run.

Complete working example

This example shows the main current sections without embedding real credentials. Remove sections you do not use and provide secrets through your normal local secret-management process.

{
  "provider": "openrouter",
  "openrouter": {
    "apiKey": "replace-locally",
    "model": "anthropic/claude-sonnet-4",
    "contextWindow": 200000
  },
  "workspace": {
    "defaultRoot": "/work/projects",
    "allowDangerousOps": false
  },
  "ui": {
    "theme": "dark",
    "silentToolOutput": false,
    "showThinking": true,
    "completionReportEnabled": true,
    "promptSuggestions": true,
    "activityVerbs": ["Indexing", "Reviewing", "Testing"],
    "activityVerbsEnabled": true,
    "activitySymbol": "✳",
    "statusLine": {
      "showProviderModel": true,
      "showContext": true,
      "showWorkspacePath": true,
      "showGitBranch": true,
      "showCommandHint": true,
      "showPullRequest": true,
      "showSessionLines": false,
      "showQueue": true,
      "showActiveStatus": true,
      "showActiveMetrics": true,
      "showCancelHint": true
    }
  },
  "agent": {
    "maxIterations": 100,
    "enableRequestQueue": true,
    "idleLogoutEnabled": true,
    "idleTimeoutMs": 3600000,
    "sessionRetryLimit": 3,
    "sessionRetryDelay": 1000,
    "parallelToolConcurrency": 5,
    "toolSelectionCache": true,
    "autoMemory": true,
    "debug": false
  },
  "sessions": {
    "awareness": "warn"
  },
  "permissions": {
    "mode": "interactive",
    "allowList": ["run_command:git status --short"],
    "denyList": ["run_command:npm publish"],
    "rememberSession": true
  },
  "features": {
    "usageV2": false,
    "tokenUsageStatus": false,
    "slashGoal": false
  },
  "teams": {
    "enabled": true,
    "teammateMode": "auto",
    "maxTeammates": 5
  },
  "search": {
    "provider": "browser-profile"
  },
  "mcp": {
    "enabled": true,
    "servers": []
  },
  "hooks": {
    "enabled": true,
    "hooks": []
  },
  "telemetry": {
    "enabled": false
  },
  "autoReport": {
    "enabled": true
  },
  "sync": {
    "enabled": true,
    "interval": 300000,
    "exclude": [],
    "includeTelemetry": false,
    "includeFeedback": false
  }
}

Top-level keys

Provider settings

Set the top-level provider to the provider Autohand should use. Common provider fields are model, apiKey, baseUrl, port, contextWindow, and reasoningEffort. Provider-specific integrations add fields such as Azure deployment/authentication data, Vertex project and region, xAI OAuth state, NVIDIA chat-template options, or Bedrock region and API mode.

Custom OpenAI-compatible providers

{
  "provider": "custom:company-gateway",
  "customProviders": {
    "company-gateway": {
      "id": "company-gateway",
      "displayName": "Company Gateway",
      "apiFormat": "openai-compatible",
      "baseUrl": "https://models.example.com/v1",
      "apiKey": "replace-locally",
      "apiKeyRequired": true,
      "model": "company-code",
      "contextWindow": 131072,
      "models": [
        {
          "id": "company-code",
          "label": "Company Code",
          "contextWindow": 131072,
          "reasoningEffort": "high"
        }
      ]
    }
  }
}

The object key and its id must match. apiFormat is currently openai-compatible. Set disabled to hide the provider without deleting its saved settings.

Trusted extension providers

{
  "provider": "extension:company-release",
  "extensionProviders": {
    "extension:company-release": {
      "model": "release-model",
      "apiKey": "replace-locally",
      "baseUrl": "https://models.example.com"
    }
  }
}

The extension controls additional fields, but every provider entry requires a non-empty model. The matching extension must be installed, enabled, trusted, and successfully activated. See Extension API v1.

UI settings

Status line

Every ui.statusLine field defaults to true except showSessionLines, which defaults to false.

Use /statusline for the interactive editor.

Agent and concurrent-session settings

{
  "agent": {
    "autoMemory": true,
    "idleLogoutEnabled": true,
    "idleTimeoutMs": 7200000
  },
  "sessions": {
    "awareness": "coordinate"
  }
}

Use --no-idle-logout for one long-running process without changing the saved config. Run autohand agents --once to print the live local agent/session snapshot.

Permission settings

Autohand's immutable security checks run before configurable policy. Configuration can narrow or approve supported actions, but it cannot override the immutable blacklist.

{
  "permissions": {
    "mode": "interactive",
    "allowList": [
      "run_command:git status --short",
      "run_command:npm test"
    ],
    "denyList": [
      "run_command:npm publish"
    ],
    "rules": [
      {
        "tool": "run_command",
        "pattern": "git diff *",
        "action": "allow"
      }
    ],
    "rememberSession": true
  }
}

Use /permissions or autohand --permissions to inspect the effective user, project, and session policy. Saved “always” decisions may be written to user or project scope; keep project-local approvals reviewable.

Features and experiments

Use autohand experiments list or /experiments to see the effective feature state. Local flags persist to their config path. Eligible server-controlled flags may be turned off locally through features.remoteOverrides, but a local config cannot force on a server-disabled remote flag.

autohand experiments list
autohand experiments status token_usage_status
autohand experiments enable token_usage_status
autohand experiments disable token_usage_status
autohand experiments refresh

Autohand inference rollout flag

features.autohand_inference separately gates the Autohand Cloud/local provider, setup choices, model discovery, RPC, and ACP surfaces. It is off unless deliberately enabled in config or with AUTOHAND_FEATURE_AUTOHAND_INFERENCE=1 (also accepted in AUTOHAND_FEATURES).

Auto-mode and teams

Network, search, telemetry, and reporting

--offline disables startup network operations such as model-catalog and feature/announcement refreshes while preserving useful cached local state.

MCP and hooks

MCP servers

{
  "mcp": {
    "enabled": true,
    "servers": [
      {
        "name": "repository-tools",
        "transport": "stdio",
        "command": "npx",
        "args": ["-y", "@company/repository-mcp"],
        "env": {
          "LOG_LEVEL": "warn"
        },
        "autoConnect": true
      },
      {
        "name": "remote-tools",
        "transport": "http",
        "url": "https://mcp.example.com/mcp",
        "headers": {
          "Authorization": "Bearer replace-locally"
        },
        "autoConnect": true
      }
    ]
  }
}

A server requires name and transport. stdio requires command; http and sse require url. Optional fields are args, env, headers, and autoConnect. Manage servers with autohand mcp or /mcp. See MCP servers.

Lifecycle hooks

{
  "hooks": {
    "enabled": true,
    "hooks": [
      {
        "event": "post-tool",
        "command": "./scripts/record-tool-result.sh",
        "description": "Record completed tool calls",
        "enabled": true,
        "timeout": 5000,
        "async": false,
        "filter": {
          "tool": ["run_command"]
        }
      }
    ]
  }
}

Each definition requires event and command. It may also set description, enabled, timeout, async, matcher, and a tool/path filter. Current events cover tool, prompt, response, file, session, permission, notification, sub-agent, auto-mode, auto-research, learning, goals, teams, review, mode, and context lifecycles. See Hooks and events for the event payload and control-flow contract.

Authentication, community skills, sharing, and sync

{
  "communitySkills": {
    "enabled": true,
    "showSuggestionsOnStartup": true,
    "autoBackup": true
  },
  "share": {
    "enabled": false
  },
  "sync": {
    "enabled": true,
    "interval": 300000,
    "exclude": ["temp/*"],
    "includeTelemetry": false,
    "includeFeedback": false
  },
  "externalAgents": {
    "enabled": true,
    "paths": ["/work/shared-agents"]
  }
}

Sync handles canonical memory event logs by event id instead of overwriting one device's history with another. Derived memory caches and locks are not synced. Sensitive config fields are encrypted for account sync, but you should still avoid committing secrets to a repository.

Browser integration

The historical config object remains chrome for compatibility. The public CLI and slash-command surface is browser-neutral: --browser, --no-browser, and /browser. The older --chrome aliases remain hidden compatibility inputs.

{
  "chrome": {
    "extensionId": "installed-extension-id",
    "browser": "auto",
    "userDataDir": "/path/to/browser/user-data",
    "profileDirectory": "Default",
    "installUrl": "https://autohand.ai/chrome",
    "enabledByDefault": false
  }
}

Environment variables

Runtime-only controls

Some current CLI capabilities intentionally do not persist as config:

Structured output requires a one-shot prompt. --output-format stream-json cannot be combined with --json local.

Related references