Getting Started with Automergent

From installation to your first autonomous coding task in under 5 minutes. Automergent is a terminal-native AI pair-programmer that reads, writes, searches, tests, and refactors your codebase.

1

Installation

Install Automergent using one of the methods below. The one-line installer is the fastest way to get started.

bash 
curl -fsSL https://automergent.github.io/install.sh | bash
Note
The installer downloads the latest release for your platform, places it in /usr/local/bin, and creates the amt alias (same binary, every flag works on both — amt -s <id> resumes a session). Requires curl and bash.
bash 
# Requires Go 1.25+ with CGO enabled
CGO_ENABLED=1 go install github.com/iSundram/Automergent/cmd/automergent@latest
Prerequisite
Ensure you have Go 1.25 or later installed. CGO is required for tree-sitter AST parsing. Run go version to verify.
bash 
git clone https://github.com/iSundram/Automergent.git
cd Automergent
make build
make install

Download pre-built binaries from GitHub Releases:

Platform Architecture Download
Linux amd64 automergent-linux-amd64
Linux arm64 automergent-linux-arm64
macOS amd64 automergent-darwin-amd64
bash 
# Example: Linux amd64
curl -L https://github.com/iSundram/Automergent/releases/latest/download/automergent-linux-amd64 -o automergent
chmod +x automergent
sudo mv automergent /usr/local/bin/
2

First Launch

Launching Automergent for the first time is simple. Navigate to your project directory and run the command.

1

Navigate to your project

Change to the root directory of any Git repository.

2

Run Automergent

bash 
cd your-project/
automergent
3

Automatic Detection

Automergent automatically detects your Git context, repository root, configuration files, and project languages on startup.

First-Time Setup
On first launch, you'll be guided through a setup wizard to configure your AI provider and preferred settings. This only happens once.
3

Provider Setup

Automergent supports multiple AI providers. Configure your preferred provider using environment variables or the config file.

Google AI Studio (Default)

Set your API key as an environment variable:

bash 
# Either variable works
export GOOGLE_API_KEY="your-google-api-key"
# or
export GEMINI_API_KEY="your-gemini-api-key"
Google Vertex AI

For enterprise use with Google Cloud:

yaml 
provider: "google-vertex"
providers:
  google-vertex:
    project: "your-gcp-project-id"
    location: "us-central1"
Any OpenAI-Compatible Endpoint (Custom)

OpenAI, Anthropic, DeepSeek, Ollama and friends all connect through the custom provider — any OpenAI- or Gemini-compatible endpoint works with apiKey + baseUrl + defaultModel:

yaml 
provider: "custom"
providers:
  custom:
    apiKey: "${PROVIDER_API_KEY}"
    baseUrl: "https://api.openai.com/v1"
    defaultModel: "gpt-4o"
Ollama (Local)

Local models connect through custom with no API key:

yaml 
provider: "custom"
providers:
  custom:
    baseUrl: "http://localhost:11434/v1"
    defaultModel: "llama3"
Custom / OpenAI-Compatible Providers

Connect to any OpenAI- or Gemini-compatible API (LiteLLM, OpenRouter, self-hosted, etc.) with apiKey, baseUrl and defaultModel:

yaml 
provider: "custom"
providers:
  custom:
    apiKey: "${CUSTOM_API_KEY}"
    baseUrl: "http://localhost:11434/v1"
    defaultModel: "llama3"

Environment Variables Reference

Variable Provider Description
GOOGLE_API_KEY Google AI Studio API key for Gemini models (preferred)
GEMINI_API_KEY Google AI Studio Alias for GOOGLE_API_KEY, used as fallback
AUTOMERGENT_REDUCED_MOTION Any 1 disables spinner animations
Note
Other providers (OpenAI, Anthropic, DeepSeek, Ollama) connect through the custom provider with apiKey + baseUrl in ~/.automergent/config.yaml — no dedicated environment variables are read for them.
4

Configuration

Automergent uses a YAML configuration file for persistent settings. The config file is located at ~/.automergent/config.yaml.

Minimal Config Example

yaml 
# ~/.automergent/config.yaml
provider: "google-aistudio"
model: "gemini-3.6-flash"
temperature: 0.2
mode: "accept-edits"
theme: "modern"

Key Settings

Setting Values Description
provider google-aistudio, google-vertex, custom (legacy aliases: google, openai, anthropic, deepseek, ollama) AI provider to use
model String Model identifier (provider-specific)
mode manual, accept-edits, auto, plan Approval mode for operations
theme modern, catppuccin, tokyonight, dracula, nord, gruvbox, onedark Color theme
temperature 0.0 - 1.0 Model temperature (default: 0.2)

Per-Project Overrides

Place a .automergent/config.yaml in your project root to override global settings:

bash 
your-project/
├── .automergent/
│   └── config.yaml    # Project-specific overrides
├── src/
└── ...
5

Approval Modes

Control how Automergent handles file changes and command execution with approval modes. Switch anytime using /mode command or Shift + Tab.

Manual

Confirms every action before execution. Full control over all operations.

Recommended

File edits auto-apply, but commands require approval. Great balance of speed and control.

Auto

Acts freely without confirmation. Use only when you trust the agent completely.

Plan

Read-only analysis mode. No file changes or commands are executed.

Switching Modes

terminal 
/mode accept-edits
# or
Shift+Tab  (cycles through modes)
6

Your First Task

Try these example prompts to explore Automergent's capabilities. Start with Plan mode to see how it analyzes code before making changes.

Read & Understand Code
prompt 
Read main.go and explain what it does
Search for Patterns
prompt 
Find all TODO comments in the project
Debug & Fix
prompt 
Run the tests and fix any failures
Tip
Start in Plan mode to see how Automergent analyzes your code before making any changes. This helps you understand its approach and build trust.

Next Steps