Configuration File Paths

User-level configuration file: ~/.hcode/settings.json
Project-level configuration file: .hcode/settings.json in the project root directory

Configuration Description

Property Name	Description	Hot Reload
env	Environment variable configuration for setting system-level environment variables, see Environment Variables section	Yes
language	UI language setting, configures Hawa Code’s default response language	Yes
disableSuggestion	Disable prompt suggestions	Yes
permissions	Permission configuration, see Permission Configuration section	Yes
sandbox	Sandbox configuration, see the Sandbox Configuration section for details	No
autoCompactEnabled	Enable session auto-compaction, default: true	Yes
sessionSummary	Session summary configuration, see Session Summary section	Yes
autoMemory	Session memory auto-extraction, see Session Memory Auto-Extraction section	Yes
autoDream	Session memory auto-consolidation, see Session Memory Auto-Consolidation section	Yes
autoMode	Automatic tool authorization mode, see Auto Mode section	Yes

Configuration Example

{
  "env": {
    "HAWA_CODE_LAZY_TOOL": false,
    "HAWA_CODE_FIX_SCHEMA": true
  },
  "permissions": {
    "allow": [
      "Bash(git branch:*)",
      "Bash(git status:*)",
      "mcp_notion_*"
    ],
    "deny": [
      "Read(./settings/**)"
    ]
  },
  "language": "english"
}

Environment Variables

The env configuration option allows you to set system-level environment variables that affect Hawa Code’s behavior.

HAWA_CODE_USER_AGENT

Customize the User-Agent string used by Hawa Code when making HTTP requests.

Property	Description	Example
HAWA_CODE_LAZY_TOOL	Tool lazy loading toggle	false
HAWA_CODE_FIX_SCHEMA	Tool call parameter compatibility fix option	true
HAWA_CODE_USER_AGENT	Customize the User-Agent string for HTTP requests	“MyCustomAgent/1.0”
HAWA_CODE_AUTH_DISABLED	Disable Authentication HTTP request header	true
HAWA_CODE_X_API_KEY_DISABLED	Disable x-api-key HTTP request header	true
HAWA_CODE_OPENAI_IMAGE_DETAIL	Set OpenAI image resolution level, optional values: “low”, “high”, “auto”, “original”, default is auto	“high”
HTTPS_PROXY	Set HTTPS proxy address	“http://127.0.0.1:7890“
HTTP_PROXY	Set HTTP proxy address	“http://127.0.0.1:7890“

Permission Configuration

Property Name	Description	Hot Reload
permissions.allow	Permission configuration for defining allowed tools	Yes
permissions.ask	Permission configuration requiring manual authorization when tools execute	Yes
permissions.deny	Permission configuration for defining denied tools	Yes
permissions.disableBypassPermissionsMode	Set to “disable” to prevent activating bypassPermissions mode	Yes

Permission Configuration Rules

Permission rules follow the format Tool or Tool(specifier). Rule priority: deny > ask > allow. The first matching rule is used.

Rule	Effect
Bash	Matches all Bash commands
Bash(npm test *)	Matches commands starting with “npm test”
Read(./.md)	Matches reading .md files
WebFetch(domain:test.com)	Matches fetch requests to test.com

For complete rule syntax reference, including wildcard behavior, tool-specific patterns for Read, Edit, WebFetch, MCP and Agent rules, and security limitations for Bash patterns, please refer to Permission Rule Syntax.

Sandbox Configuration

Configure advanced sandbox behavior. The sandbox isolates bash commands from your filesystem and network. See Sandbox for details.

Property	Description	Example
enabled	Enable bash sandbox, supported on macOS, Linux, and WSL2. Default: false	true
autoAllowBashIfSandboxed	Skip manual confirmation for bash commands when sandbox is enabled. Default: true	true
excludedCommands	Commands that can run outside the sandbox	[“git”, “docker”]
allowUnsandboxedCommands	Allow commands to run outside the sandbox via the dangerouslyDisableSandbox parameter. When set to false, dangerouslyDisableSandbox has no effect and all commands not in excludedCommands must be sandboxed. Default: true	false
filesystem.allowWrite	File paths the sandbox can write to; merged from user and project settings, and also merged with paths in Edit(…) and Write(…) allow permission rules. See path prefixes below.	[“//dev/ccr”, “~/.hcode”]
filesystem.denyWrite	Paths the sandbox cannot write to; merged from user and project settings, and also merged with paths in Edit(…) and Write(…) deny permission rules.	[“//etc”, “//usr/test”]
filesystem.denyRead	Paths the sandbox cannot read; merged from user and project settings, and also merged with paths in Read(…) deny permission rules.	[“~/dev/cre”]
filesystem.allowRead	Paths the sandbox can read; merged from user and project settings, and also merged with paths in Read(…) allow permission rules.	[“~/dev/cre”]
network.allowedDomains	Domains the sandbox can access. Supports wildcards (e.g. *.example.com).	[“github.com”, “*.npmjs.org”]
network.deniedDomains	Domains the sandbox cannot access. Supports wildcards (e.g. *.example.com).	[“github.com”, “*.npmjs.org”]
network.allowUnixSockets	Unix socket paths accessible in the sandbox (for SSH agents, etc.)	[“~/.ssh/code-socket”]
network.allowLocalBinding	Allow binding to localhost ports (macOS only). Default: false	true

Sandbox Configuration Example

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker"],
    "filesystem": {
      "allowWrite": ["//tmp/", "~/.hcode"],
      "denyRead": ["~/.ct/caa"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
      "deniedDomains": ["evil.example.com"],
      "allowLocalBinding": true
    }
  }
}

Session Summary

When autoCompactEnabled is set to true, session auto-compaction is enabled. When the context window is almost full, Hawa Code will automatically compress session messages to ensure long-running sessions. Session compression is performed in a single operation and may take some time.

sessionSummary is used to configure the session summary feature. Hawa Code asynchronously performs incremental summary of the current session during the conversation.

Summary files are stored at: ~/.hcode/projects/{project_name}/messages/{session_id}/session-summary/summary.md

Property	Description	Example
enabled	Enable session summary, default: false	true
config.minimumMessageTokensToInit	Minimum token count for the first summary execution, default: 10000	10000
config.minimumTokensBetweenUpdate	Minimum token increment between summary executions, default: 5000	5000
config.toolCallsBetweenUpdates	Minimum tool call increment between summary executions, default: 3	3

Session Memory Auto-Extraction

autoMemory automatically extracts key information during conversations and saves it as memory, without the need to manually maintain HAWA.md or rules configurations.

Property	Description	Example
enabled	Enable automatic memory extraction, default: false	true
minTokens	Minimum token increment for the first extraction and subsequent extractions, default: 3000	3000
minTurns	Minimum number of conversation turns required to trigger extraction, default: 3	3

Session Memory Auto-Consolidation

autoDream periodically consolidates, deduplicates, and cleans up expired automatically extracted memories. autoMemory must be enabled before using this feature.

Property	Description	Example
enabled	Enable session memory auto-consolidation, default: false	true
minHours	Minimum time interval between consolidations (in hours), default: 24	24
minSessions	Minimum number of new sessions required to trigger consolidation, default: 5	5

Auto Mode

When autoMode is enabled, Hawa Code will automatically determine whether a tool is allowed to execute, enabling unattended automatic authorization.

After setting the environment variable HAWA_CODE_AUTO_MODE_ACCEPTEDITS = "1", Hawa Code will automatically allow tools permitted by acceptEdits to execute. This setting reduces model requests but grants more tools by default; enable it based on your actual needs.

Property	Description	Example
enabled	Whether to enable auto mode, default: false	true
maxConsecutiveDenials	Number of consecutive denials before falling back to manual prompt, default: 3	3
maxTotalDenials	Total number of denials before falling back to manual prompt, default: 20	5