Configuration

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.

{
  "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:

UI settings

Control how Autohand displays information in the terminal:

Agent settings

Control how the AI agent operates:

Network settings

Configure network behavior for API requests:

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

Search settings

Configure web search behavior for the agent:

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

Sync settings

Configure settings synchronization across devices:

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

Extended thinking settings

Configure the agent's reasoning depth:

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

YOLO mode settings

Configure auto-approval patterns in the permission settings:

{
  "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:

Excluding sensitive files

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

{
  "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:

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

Default commit attribution:

Generated with Autohand CLI

Co-Authored-By: Autohand <[email protected]>

Example custom attribution:

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <[email protected]>",
    "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:

Tools available to Autohand

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

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.

{
  "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 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:

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