Configuration

AIDE is configured through environment variables. All variables are optional.

Environment Variables

Variable	Description
AIDE_DEBUG=1	Enable debug logging (logs to .aide/_logs/)
AIDE_FORCE_INIT=1	Force initialization in non-git directories
AIDE_CODE_WATCH=1	Enable file watching for auto-reindex
AIDE_CODE_WATCH_DELAY=30s	Delay before re-indexing after file changes
AIDE_INDEX_NON_VCS=1	Allow watcher/indexing in non-VCS dirs (default: refuse)
AIDE_INDEX_WORKERS=N	Parallel parser workers for code indexing (default: NumCPU, capped at 32)
AIDE_MEMORY_INJECT=0	Disable memory injection
AIDE_MCP_SYNC=0	Disable cross-assistant MCP server sync (default: enabled)
AIDE_MEMORY_SCORING_DISABLED=1	Disable memory scoring (use chronological order)
AIDE_MEMORY_DECAY_DISABLED=1	Disable recency decay in memory scoring
AIDE_SHARE_AUTO_IMPORT=1	Auto-import shared decisions/memories on start
AIDE_MAINTENANCE_COMPACT_ON_EXIT=0	Disable automatic bolt-store compaction when the daemon/MCP server exits (default: on)
AIDE_REFLECT=1	Enable the reflect Stop hook (extracts instinct proposals from session observe events). Accepts any truthy value: 1/true/on/yes. Equivalent to reflect.enabled=true in .aide/config/aide.json. Env wins when set; otherwise the config file value wins; otherwise default off.

Where env vars are read from

aide is invoked from three surfaces, each with a different env scope. Setting an AIDE_* var in the wrong place is a common gotcha — this table maps each var to where it actually needs to live:

Variable	Read by	Set where
AIDE_CODE_WATCH	hooks + CLI + daemon	shell that launches the harness, or MCP env block
AIDE_CODE_WATCH_DELAY	daemon	MCP env block (used at daemon startup)
AIDE_DEBUG	hooks + CLI	shell that launches the harness
AIDE_FORCE_INIT	CLI	shell at CLI invocation time
AIDE_INDEX_NON_VCS	daemon	MCP env block
AIDE_MCP_SYNC	session-start hook	shell that launches the harness
AIDE_MEMORY_INJECT	hooks	shell that launches the harness
AIDE_MEMORY_SCORING_DISABLED	daemon	MCP env block
AIDE_MEMORY_DECAY_DISABLED	daemon	MCP env block
AIDE_PROJECT_ROOT	CLI	shell at CLI invocation
AIDE_REFLECT	hooks + CLI	either shell or reflect.enabled in .aide/config/aide.json
AIDE_SHARE_AUTO_IMPORT	session-start hook	shell that launches the harness

MCP env block = the env (Claude Code) or environment (OpenCode) mapping under the aide MCP server in the harness's config. This block only propagates to the MCP daemon subprocess — not to hooks.

Shell env at harness launch = what's exported in your shell when you run claude / opencode. The harness's process env (and therefore its spawned hooks) inherits these.

Claude Code

To set an env var visible to both hooks and the MCP daemon, the cleanest place is the user-level ~/.claude/settings.json:

{
  "env": {
    "AIDE_REFLECT": "1",
    "AIDE_CODE_WATCH": "1"
  }
}

Or in your shell rc (~/.zshrc / ~/.bashrc):

export AIDE_REFLECT=1
export AIDE_CODE_WATCH=1

Either works — Claude Code's process env inherits both.

OpenCode

OpenCode reads env from the launching shell. Same export pattern in your shell rc. The aide plugin's environment block in opencode.json only propagates to the aide MCP daemon, not to OpenCode's own process or its spawned hooks.

.aide/config/aide.json for project-local settings

For settings that should travel with the project (not the developer):

{
  "reflect": { "enabled": true },
  "memory":  { "scoring_enabled": true, "decay_enabled": true }
}

The Go-side config layer reads this file. The TS-side reflect.enabled check (used by skill-injector.ts for the convergence user-prompt emit) also reads this file directly. Env vars take precedence over file values.

Project Configuration

Project-level settings can be stored in .aide/config/aide.json:

{
  "findings": {
    "complexity": {
      "threshold": 10
    },
    "coupling": {
      "fanOut": 15,
      "fanIn": 20
    },
    "clones": {
      "windowSize": 50,
      "minLines": 6
    }
  }
}

Setting	Default	Description
findings.complexity.threshold	10	Cyclomatic complexity threshold per function
findings.coupling.fanOut	15	Maximum outgoing imports before flagging
findings.coupling.fanIn	20	Maximum incoming imports before flagging
findings.clones.windowSize	50	Sliding window size in tokens for detection
findings.clones.minLines	6	Minimum clone size in lines to report

| cleanup.enabled | true | Master switch for the daemon's background bucket-pruning loop | | cleanup.observe_max_age | 8760h | TTL for observe/telemetry events (0 = keep forever) | | cleanup.task_max_age | 8760h | TTL for completed tasks (pending/claimed are never pruned) | | cleanup.state_max_age | 8760h | TTL for per-agent session state | | maintenance.compact_on_exit | true | Rewrite bolt stores to reclaim free pages when the daemon/MCP server exits |

Values in aide.json serve as project-level defaults. CLI flags override config file values. If neither is set, the built-in defaults apply.

Managing Configuration from the CLI

Rather than editing aide.json by hand, use the aide config command family. It reads and writes the same .aide/config/aide.json file (or the user-global file with --global), and reports where each value comes from.

aide config show                              # Print effective config + each value's source
aide config get cleanup.observe_max_age       # Read one value
aide config set maintenance.compact_on_exit false   # Write a project value
aide config set memory.scoring_enabled true   # Booleans, strings, numbers
aide config unset cleanup.observe_max_age     # Remove a project override
aide config path                              # Show the config file path

Precedence (lowest to highest): built-in defaults → user-global ~/.aide/config/aide.json → project .aide/config/aide.json → AIDE_* environment variables. Use aide config set --global <key> <value> to write the user-global file, which applies to every project unless that project overrides it. The global file is config only — never data or a database.

File Exclusions

Create a .aideignore file in your project root to exclude files from indexing and analysis. Uses gitignore syntax:

# Exclude generated files
*.generated.ts
*.min.js

# Exclude vendor
vendor/

# But include important vendor files
!vendor/important.go

Built-in defaults already exclude common generated files, lock files, build artifacts, and directories like node_modules/, .git/, vendor/, etc.

Troubleshooting

aide version                              # Check binary
aide status                               # Full system dashboard
AIDE_DEBUG=1 claude                       # Debug logging (or AIDE_DEBUG=1 opencode)