Advanced Features

Sub-agents, MCP, workflows, memory, artifacts, security, and background execution.

Sub-agent System Stable

Automergent spawns specialized child agents to parallelize work. Each sub-agent runs in its own context with an isolated tool registry and todo store, reporting progress back through a steering channel.

Agent Types

task(agent_type="general-purpose",
     prompt="Implement the OAuth2 flow in src/auth.ts")

task(agent_type="explore",
     prompt="Find all database migration files")

task(agent_type="review",
     prompt="Review src/api/handlers.go for security issues")

task(agent_type="contexter",
     prompt="Compact the session history for topic X")

task(agent_type="coordinator",
     prompt="Refactor the payment module: explore, plan, implement")

task(agent_type="task",
     prompt="Run the full test suite and report failures")

Spawning Agents

Use the task tool with a self-contained prompt. The parent agent should include all necessary context since the child has no access to parent conversation history.

// Self-contained prompt — child agent cannot see parent context
task(
  agent_type="explore",
  prompt="""
    Project: Automergent CLI
    Goal: Find all error handling patterns in Go source files.
    Constraints: Read-only, no modifications.
    Output: List files with line numbers and the pattern used.
  """
)

Parallel Execution

Launch multiple agents simultaneously with batch_task. Each runs independently, and results are collected when all complete.

// Launch 3 explore agents to analyze different parts of the codebase
batch_task([
  { agent_type: "explore",  prompt: "Analyze src/auth/ — patterns, dependencies" },
  { agent_type: "explore",  prompt: "Analyze src/api/ — routes, middleware" },
  { agent_type: "explore",  prompt: "Analyze src/db/ — models, migrations" },
])

Execution flow:

Monitoring Agents

Background Execution with Live Progress

Sub-agents run in the background. The parent agent continues working while children execute. Task notifications arrive through the steering channel:

// Parent receives notifications like:
// [task:explore] Completed in 12.3s — found 47 files, 3 patterns
// [task:review]  Completed in 8.1s  — 3 warnings, 0 errors

// Read results when ready:
read_agent(agent_id="task-explore-001")

Per-child Tool Registry & Todo Store

Each sub-agent maintains an isolated workspace:

MCP — Model Context Protocol Stable

MCP is a standard protocol for integrating external tools and resources into Automergent. It lets you connect custom APIs, databases, and services as first-class tools.

Server Configuration

Add MCP servers in config.yaml:

# config.yaml
mcp:
  servers:
    github:
      transport: stdio
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-github"]
      env:
        GITHUB_TOKEN: "${GITHUB_TOKEN}"

    postgres:
      transport: sse
      url: "http://localhost:8080/mcp"
      auth_token: "${DB_TOKEN}"

    filesystem:
      transport: stdio
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/safe/path"]

Transport Types

Commands

MCP Tools

Once connected, MCP tools are available alongside built-in tools:

// List all resources exposed by MCP servers
list_mcp_resources(server="github")

// Read a specific resource
read_mcp_resource(server="github", uri="github://repo/owner/name")

Hot-Reload Support

MCP servers support hot-reload. Edit config.yaml and changes take effect within seconds:

// Config watcher detects changes:
// [mcp] Config changed — reloading github server...
// [mcp] github: connected (3 tools, 12 resources)

Example: Adding a Custom MCP Server

# 1. Create a minimal MCP server
cat > my-mcp-server.js << 'EOF'
const { Server } = require("@modelcontextprotocol/sdk/server");

const server = new Server({ name: "my-tools", version: "1.0.0" });

server.tool("get_weather", { city: { type: "string" } }, async ({ city }) => {
  return { content: [{ type: "text", text: `Weather in ${city}: 72°F sunny` }] };
});

server.connect({ transport: "stdio" });
EOF

# 2. Add to config.yaml
# mcp:
#   servers:
#     weather:
#       transport: stdio
#       command: node
#       args: ["my-mcp-server.js"]

# 3. Verify
# /mcp tools → lists "get_weather"

Workflows Stable

Workflows are declarative YAML specs defining multi-step pipelines. Each step has an id, a prompt (with ${step-id} variable interpolation), optional dependsOn for DAG ordering, optional agentType and model overrides. The engine runs steps in dependency order with configurable concurrency and a token budget cap.

Format

Store workflows as YAML files in .automergent/workflows/:

# .automergent/workflows/deploy-check.yaml
name: deploy-check
description: Full CI pipeline before deployment
budget: 500000
concurrency: 2
steps:
  - id: lint
    prompt: "Run lint and typecheck. Report any errors."
  
  - id: test
    prompt: "Run unit tests with coverage. Fail if coverage drops below 80%."
    dependsOn: [lint]
  
  - id: build
    prompt: "Run build. Confirm output exists at dist/."
    dependsOn: [lint]
  
  - id: deploy-preview
    prompt: "Deploy to preview. Return the preview URL."
    dependsOn: [build, test]
  
  - id: smoke-test
    prompt: "Fetch the preview URL and verify HTTP 200."
    dependsOn: [deploy-preview]

Running Workflows

Background Dock Display

When running with --bg, the workflow appears in the bottom dock:

// Bottom dock shows:
┌─ Workflow: deploy-check ─────────────────────────┐
│ Step 1: Lint & Type Check     ✓ passed (4.2s)    │
│ Step 2: Unit Tests             ⏳ running (12s)   │
│ Step 3: Build                  ⬜ pending          │
│ Step 4: Deploy Preview         ⬜ pending          │
│ Step 5: Smoke Test             ⬜ pending          │
└───────────────────────────────────────────────────┘

Per-step Results & Run History

Each workflow run is logged. Access history with:

• /workflow history — list past runs with timestamps and status
• /workflow history deploy-check --last 5 — last 5 runs
• Click any step in the dock to see full output

Skills System Stable

Skills are specialized instructions and workflows loaded contextually. They provide domain-specific guidance without polluting the main context.

Skill Paths

Skill Discovery & Loading

Automergent discovers skills on startup and when the /skills command runs. Skills are loaded on-demand when a task matches their description.

# .automergent/skills/testing.md
---
name: testing
description: Best practices for writing and running tests in this project
triggers:
  - "write tests"
  - "test coverage"
  - "unit test"
---

## Testing Guidelines

- Use Vitest for unit tests
- Place tests adjacent to source: src/foo.ts → src/foo.test.ts
- Aim for 80% coverage on new code
- Mock external APIs with MSW
- Use describe/it/expect pattern

The /skills Command

# Browse available skills
/skills

# Output:
# Available Skills:
#   testing     (.automergent/skills/)  — Test writing best practices
#   security    (.automergent/skills/)  — Security review checklist
#   rust        (~/.automergent/skills/) — Rust idioms and patterns
#   python      (~/.automergent/skills/) — Python conventions

Creating Custom Skills

Skills are Markdown files with YAML frontmatter:

• name — identifier
• description — when to load this skill
• triggers — keywords that auto-activate the skill
• Body — instructions, examples, constraints

Memory System Stable

Durable memory persists facts, decisions, and preferences across sessions. Memory is injected as context — not as commands — so the agent uses it as background knowledge.

Commands

Memory Examples

# Store a fact
/memory add "This project uses PostgreSQL 16 with Prisma ORM"

# Store a preference
/memory add "Always use kebab-case for CSS class names"

# Store a decision
/memory add "Decided to use Zustand over Redux for state management (simpler API)"

# List all memories
/memory list
# [1] This project uses PostgreSQL 16 with Prisma ORM
# [2] Always use kebab-case for CSS class names
# [3] Decided to use Zustand over Redux for state management

Dream Mode — /dream

The /dream command consolidates session memory. It reviews the current conversation, extracts durable facts, and stores them:

# At end of a productive session
/dream

# Automergent:
# Scanning session... found 4 durable facts:
# [1] API uses REST, not GraphQL
# [2] Auth middleware at src/middleware/auth.ts
# [3] Tests require DATABASE_URL env var
# [4] Build command is make prod
# Stored 4 memories. Use /memory list to review.

Auto-recall in Later Sessions

Memories are automatically injected into new sessions as background context. The agent sees them as knowledge, not instructions:

// System prompt automatically includes:
// Durable Memory:
// - This project uses PostgreSQL 16 with Prisma ORM
// - Always use kebab-case for CSS class names
// - Decided to use Zustand over Redux

Best Practices

• Store facts: "This project uses X", "The API endpoint is /v2/users"
• Store decisions: "Chose X over Y because Z"
• Store preferences: "Always use kebab-case for CSS class names"
• Avoid storing ephemeral state — use todos for that
• Periodically /dream to consolidate important session findings

Artifact System Beta

Artifacts are structured deliverables — plan documents, goal specs, and review outputs — with built-in approval workflows.

Plan Mode

Switch to read-only analysis mode. The agent produces a plan artifact without modifying any files:

# Enter plan mode
/plan

# Agent analyzes the codebase and produces:
# ┌─ Plan Artifact ───────────────────────────┐
# │ Title: Refactor Auth Module                │
# │ Status: PENDING APPROVAL                   │
# │                                            │
# │ ## Current State                           │
# │ - Auth lives in src/auth.ts (420 lines)    │
# │ - Mixed concerns: JWT, sessions, OAuth     │
# │                                            │
# │ ## Proposed Changes                        │
# │ 1. Split into src/auth/jwt.ts              │
# │ 2. Split into src/auth/oauth.ts            │
# │ 3. Create src/auth/session.ts              │
# │                                            │
# │ ## Risk Assessment                         │
# │ - Low: No API changes                      │
# │ - Medium: Migration of existing tests      │
# │                                            │
# │ [Accept] [Reject] [Comment]               │
# └────────────────────────────────────────────┘

Artifact Review Commands

Goal Mode

Set autonomy objectives with /goal. The agent works toward a high-level objective, making decisions autonomously:

# Set a goal
/goal "Achieve 90% test coverage on src/api/"

# Agent:
# Goal registered. I will:
# 1. Analyze current coverage (explore agent)
# 2. Identify uncovered code paths
# 3. Write tests for each uncovered path
# 4. Verify coverage threshold reached
# Starting...

Approval Flow

Security Features Stable

OS-level Sandboxing

Automergent enforces sandboxing at the OS level on every platform:

Path Boundary Enforcement

# Blocked write paths (cannot be modified):
/etc/
/usr/
/bin/
/boot/
/sys/
/proc/

# Allowed write paths (default):
./              # Current project directory
/tmp/           # Temp files
~/              # User home

# Custom paths in config.yaml:
security:
  allowed_paths:
    - /opt/projects/
    - /var/data/
  blocked_paths:
    - /etc/
    - /usr/

Secrets Scanning 20+ patterns

Automergent scans all file writes and shell output for leaked secrets:

Dependency Auditing

# Supported ecosystems:
#   Go      → govulncheck
#   npm     → npm audit
#   Python  → pip-audit
#   Rust    → cargo audit

# Run security review
/security-review

# Output:
# ┌─ Security Review ─────────────────────────┐
# │ Dependencies:                              │
# │   npm: 234 packages, 0 vulnerabilities    │
# │   Go: 12 modules, 1 low-severity         │
# │                                            │
# │ Secrets scan: CLEAN                        │
# │ File permissions: OK                       │
# │ Git hooks: configured                      │
# │ Status: PASS                               │
# └────────────────────────────────────────────┘

Tool Confirmation System

Every tool invocation can require confirmation depending on your approval mode. Dangerous operations always ask:

// Always confirmed (regardless of mode):
rm -rf /
sudo anything
git push --force
DROP TABLE

Per-tool Permissions

Fine-grained control over which tools can run without confirmation:

# /permissions command
/permissions

# Output:
# Tool Permissions:
#   read_file       ✓ always allow
#   edit_file       ✓ always allow  (accept-edits mode)
#   bash            ⚠ ask each time
#   web_fetch       ✓ always allow
#   git             ⚠ ask each time

Background Shells Stable

Persistent PTY sessions that survive across agent turns. Run long-lived processes, dev servers, or watchers without blocking the main conversation.

Shell Tools

Example: Dev Server

# Start a dev server in background
bash(command="npm run dev", label="dev-server")
# → Shell ID: sh-001

# Read its output after a few seconds
read_shell(shell_id="sh-001")
# → "Server running at http://localhost:3000"

# List all active shells
list_shells()
# → [{ id: "sh-001", label: "dev-server", status: "running", pid: 12345 }]

# Stop it when done
stop_shell(shell_id="sh-001")

Bottom Dock Display

Active shells appear in the bottom dock with live output tails:

// Bottom dock shows:
┌─ Shells ─────────────────────────────────────────┐
│ sh-001  dev-server    npm run dev    running  ⏱ 2m │
│   → Server running at http://localhost:3000       │
│   → 12 modules compiled successfully             │
│ sh-002  test-watch    npm test -- -w running  ⏱ 5m │
│   → 47 tests passing, 0 failing                  │
└───────────────────────────────────────────────────┘

Approval Modes Deep Dive Stable

Automergent offers four approval modes controlling how much autonomy the agent has. Choose based on your comfort level and task risk.

Mode Comparison

* Destructive operations (rm -rf, sudo, DROP TABLE) always require confirmation regardless of mode.

Per-tool Permissions

Override the mode on a per-tool basis:

# Allow bash without confirmation in accept-edits mode
/permissions allow bash

# Revoke auto-apply for edit_file
/permissions deny edit_file

# Reset to default
/permissions reset

Session-persisted Permissions

Permissions granted during a session persist until the session ends or you explicitly revoke them:

// You approve "bash" once:
// Confirm: bash "npm test" [y/n]
// y → "Remember this choice for this session?" [y/n]
// y → bash is now auto-approved for this session

Approval Flow UI

// When confirmation is needed:
┌─ Tool Confirmation ────────────────────────────┐
│ Tool:    bash                                  │
│ Command: npm test                              │
│ Mode:    accept-edits (shell requires confirm)  │
│                                                 │
│ [y] Yes, execute    [n] No, skip               │
│ [a] Always allow    [r] Remember for session    │
└─────────────────────────────────────────────────┘