Automergent Troubleshooting & FAQ

Automergent cannot reach the AI provider API endpoint.

The conversation context has exceeded the model's context window limit.

The approval prompt appears repeatedly for safe, routine operations.

Characters are garbled, colors missing, or layout is misaligned.

The Go build fails with compilation or linking errors.

Session data is lost between runs or history is not persisted.

A spawned sub-agent appears stuck or never completes.

Colors are washed out, incorrect, or appear as solid blocks.

Custom MCP servers fail to start or tools are not available.

File writes or commands are blocked by the security sandbox.

🛡️ How Sandboxing Works

Automergent runs a sandboxed environment that restricts file writes and command execution to approved paths and commands. The sandbox operates at the tool-execution level — each write or shell operation is checked against a configurable allowlist.

• File writes: Restricted to the current working directory and explicitly allowed paths.
• Command execution: Only commands matching an allowlist pattern can run.
• Network: Outbound network is unrestricted by default but can be limited via .opencode/sandbox.json.

🚫 What Gets Blocked by Default

• Writes to system directories (/etc, /usr, /var)
• Execution of destructive commands (rm -rf /, dd, mkfs)
• Modifications to files outside the project directory
• Sensitive file access (~/.ssh, ~/.aws/credentials)
• Installation of system packages without explicit approval

📁 Configuring Write Paths

Add custom paths to the sandbox allowlist:

{
  "write": [
    "./src/**",
    "./tests/**",
    "./config/**",
    "/usr/local/lib/myproject/**"
  ],
  "commands": [
    "npm run *",
    "cargo test",
    "go test ./...",
    "pytest"
  ]
}

Place this in .opencode/sandbox.json at your project root.

🔐 Secrets Scanning Coverage

• Automergent scans file diffs for patterns matching common secret formats (API keys, tokens, passwords).
• Coverage includes: AWS keys, GitHub tokens, npm tokens, generic API keys, private keys.
• Detected secrets are redacted from output and the user is warned.
• Custom patterns can be added to .automergent/config.yaml.

🛠️ Dependency Audit Support

• Automergent can run npm audit, cargo audit, govulncheck, or pip-audit via sub-agents.
• Vulnerability reports are summarized with severity levels and remediation suggestions.
• Configure automated audits in your CI workflow using /workflow.

🔵 Truecolor Support

Automergent uses truecolor (24-bit) for themes and diff rendering. Check support:

# Run in your terminal
echo -e "\e[38;2;255;100;0mTruecolor\e[0m"

# Or check via Automergent
/env   # look for "Truecolor: yes"

✨ Unicode Rendering

• Minimum: UTF-8 encoding with box-drawing characters.
• Recommended: Full Unicode support including glyphs.
• If characters render as ?? or boxes, set noAnimation: true or noColor: true in config.

📐 Minimum Terminal Size

Automergent requires a minimum of 80 columns × 24 rows. Recommended: 120×40 for optimal diff and code viewing. Use /env to check your current terminal dimensions.