Magent Design Document

Author: Jamie Cui | Date: 2026

Table of Contents

Introduction
Key Features
Architecture Overview
Core Modules
Core Data Structures
Key Design Decisions
Live-in-Emacs Positioning

Introduction

Magent is an Emacs Lisp AI coding agent with a multi-agent architecture and permission-based tool access. It delegates all LLM communication to gptel (the sole external dependency beyond Emacs 27.1+).

This document provides a comprehensive overview of the magent architecture, design decisions, data structures, and implementation details.

For product positioning, especially the live-in-Emacs thesis and the elisp-first versus bash-first tradeoff, see Live-in-Emacs Positioning.

Key Features

Multi-agent system with specialized agents (build, plan, explore, general, compaction, title, summary)
Permission-based tool access control with fine-grained rules per agent
Custom agent support via YAML frontmatter + markdown files
LLM integration via gptel (Anthropic Claude, OpenAI GPT, Ollama, Gemini, etc.)
File operations: read, write, edit, grep, glob
Shell command execution via bash tool
Emacs Lisp evaluation via emacs_eval tool
Agent delegation with explore and general subagents
Web search via DuckDuckGo
Claude Code skills for interacting with the running Emacs instance
Session management with conversation history and buffer content persistence
Single in-flight request lock in the UI layer with explicit busy rejection
Streaming responses with chunk batching and async fontification
Markdown-to-Org conversion for rendering assistant output in org-mode
Context-aware prompting via magent-dwim with automatic buffer context attachment
Transient menu for command discovery

Architecture Overview

Magent follows a layered architecture built around one active FSM backend, scoped runtime overlays, and an org-mode interaction buffer:

magent.el (minor mode + lazy init)
    |
    v
runtime orchestration (magent-runtime.el)
    |
    +-- static definitions
    |     - agents
    |     - skills
    |     - capabilities
    |
    +-- project overlays
          - .magent/agent/*.md
          - .magent/skills/**/SKILL.md
          - .magent/capabilities/**/CAPABILITY.md

+------------------+------------------+------------------+
|     UI Layer     |   Agent Layer    |   Tool Layer     |
|  magent-ui.el    | magent-agent.el  | magent-tools.el  |
+------------------+------------------+------------------+
    |                |                |
    v                v                |
session state   prompt building       |
magent-session.el   + permissions     |
    |                |                |
    |                v                |
    |         FSM API + backend       |
    |     magent-fsm.el               |
    |        |                        |
    |        +-- magent-fsm-backend-gptel.el
    |        +-- magent-fsm-shared.el
    v
gptel (external)

Core Modules

Entry Point (magent.el)

The entry point defines magent-mode, a minor mode with a C-c m prefix map. Enabling the mode is lightweight: it installs the modeline indicator and defers static runtime initialization until first real use through magent--ensure-initialized.

Agent System

Built-in agents:

Agent	Mode	Description
build	primary	Default agent for building and general tasks
plan	primary	Planning mode with restricted edits
explore	subagent	Fast codebase exploration specialist
general	subagent	General-purpose research subagent
compaction	primary	Session summarization (hidden)
title	primary	Conversation title generation (hidden)
summary	primary	Pull-request style summary generation (hidden)

Tool System (magent-tools.el)

10 tools implemented as gptel-tool structs:

Tool	Side-effect	Description
read_file	no	Read file contents
write_file	yes	Write/create file (auto-creates dirs)
edit_file	yes	Replace exact text in file
grep	no	Regex search via ripgrep
glob	no	Find files matching glob pattern
bash	yes	Execute shell commands
emacs_eval	yes	Evaluate Emacs Lisp expressions
delegate	yes	Spawn nested request using subagent
skill_invoke	no	Invoke tool-type skills
web_search	no	Search the web via DuckDuckGo

Finite State Machine (magent-fsm.el)

The FSM API dispatches only to the gptel backend. Shared structs, abort state, and transient process cleanup live in magent-fsm-shared.el; streaming and tool-calling orchestration live in magent-fsm-backend-gptel.el.

Core Data Structures

magent-agent-info

(cl-defstruct (magent-agent-info (:constructor magent-agent-info-create))
  name           ; Agent identifier (string)
  description    ; Human-readable description
  mode           ; primary, subagent, or all
  native         ; Whether built-in
  hidden         ; Hide from listings
  temperature    ; Optional temperature override
  top-p          ; Optional top-p override
  color          ; Optional display color
  model          ; Optional model spec
  prompt         ; Optional custom system prompt
  options        ; Additional options (alist)
  steps          ; Optional max iteration steps
  permission     ; Permission ruleset
)

magent-session

(cl-defstruct (magent-session (:constructor magent-session-create))
  messages          ; List of messages in chronological order
  max-history       ; Max messages to keep
  id                ; Session identifier
  agent             ; Assigned agent info
  buffer-content    ; Saved buffer text for lossless restore
  approval-overrides ; Session-scoped approval memory
)

Key Design Decisions

No Custom HTTP Client

All LLM communication goes through gptel. This decision:

Reduces code maintenance burden
Ensures compatibility with gptel providers
Leverages gptel's battle-tested HTTP implementation
Simplifies tool-calling loop implementation

Agent Modes

The primary vs subagent distinction enables:

Clear API between agent types
Permission control (non-subagents cannot be delegated to)
UI filtering (only primary agents shown in agent selection)

Tool Filtering

Tools are defined once globally but filtered per-agent via permission rules. This approach:

Avoids duplicate tool definitions
Centralizes tool implementation
Enables dynamic permission changes per session