🐦‍⬛ MagAgent

A terminal-native AI coding agent with persistent memory, built for developers who want an assistant that genuinely learns them.

Quick Start · Providers · Tools · Skills · Memory · Agentic Graphs · Gateway · Roadmap to 1.0 · Docs

Mag Ecosystem

MagAgent is part of a local-first AI productivity stack:

MagGraph — Rust-powered Markdown graph memory, search, backlinks, recall bundles, and Python bindings.
MagAgent — terminal-native AI coding and productivity agent powered by MagGraph memory.
Mag Command Center — cross-platform desktop app for MagAgent projects, chat, configuration, memory, plugins, and local workbench views.

Why "Mag"?

Mag is short for Magpie — a member of the Corvidae (Corvid) family.

Corvids — crows, ravens, magpies, jays — are among the most cognitively sophisticated animals on Earth. They are renowned for three traits that define what MagAgent aspires to be:

🧠 Memory — Corvids remember individual human faces for years and recall the locations of thousands of cached food items. MagAgent remembers your projects, preferences, patterns, and workflows across every session.
🔧 Tool Use — Corvids are some of the only non-primate animals that manufacture and use tools. MagAgent wields a rich toolkit: web search, file operations, databases, document generation, HTTP clients, code execution, and more.
💡 Intelligence — Corvids pass mirror self-recognition tests and demonstrate future planning. MagAgent plans multi-step tasks, spawns sub-agents for parallel work, and self-improves its knowledge graph over time.

The name also nods to MagGraph — the Rust-powered graph database that backs MagAgent's memory system, storing knowledge as plain Markdown files in Git.

What is MagAgent?

MagAgent is a CLI-first AI coding agent that:

Runs entirely in your terminal, with an optional local operations UI when you want a browser view
Configures providers, model roles, memory, gateways, and sub-agent caps through CLI commands before you ever need to open a TOML file
Presents a polished Rich terminal UI with a compact session banner, Markdown response panels, and quieter streaming
Bridges workbench state into durable MagGraph memory through context maps and explicit memory promotion
Documents architecture boundaries for memory, workbench, context, tools, CLI/TUI, and compatibility-safe refactors
Saves and runs reusable workflow recipes for release prep, bug triage, docs audits, dependency upgrades, and test repair
Defines portable, stateful Open Agent Profile v1 Level 3 agents in .magent/agents/ or .agents/, with inheritance, scoped MCP/skills/memory/subagents, safe capability narrowing, reviewed learning, and @review, @explore, and @docs invocation
Includes a complete magent profile wizard, a managed magagent personality by default, and user/global default-profile selection without hand-editing configuration
Runs project hooks around tools, edits, command failures, memory candidates, and release checks
Runs real local LSP clients for Python, TypeScript/JavaScript, Rust, and Go, with capability-aware symbols, diagnostics, definitions, references, hover, and rename
Queues background asks, recipes, plans, shell tasks, followups, and gateway tasks through magent daemon
Installs local extension packs for agents, recipes, skills, tools, and MCP configuration through magent plugin
Imports MCP, Claude, OpenCode, Gemini, Codex skill, and portable Pi package assets into MagAgent-native plugins with normalized registry metadata
Connects dual-era MCP servers over stdio or Streamable HTTP, with cache-aware tool, prompt, and resource catalogs, live invalidation, completion, and consent-gated MRTR
Reads project playbooks from .magent/playbook.toml for command routines, release checklists, review rules, and context defaults
Runs saved plans and recipes in worktree, copied, or Docker-backed sandboxes
Runs isolated real-agent eval suites with independent validators, timing/token metrics, and reproducible offline and live-provider reports
Maintains a persistent memory graph per user that grows smarter over time
Measures memory precision, stale/contradictory recall, scope, provenance, backlinks, explanations, and token budgets with reproducible local evals
Emits timed model/tool liveness heartbeats and supports in-session task recovery, spend checks, and recall explanations
Enforces quick and release performance budgets for startup, project inspection, memory search, durable event throughput, and concurrent work
Publishes a proposed 1.0 contract inventory and refuses unsafe persistent-state downgrades
Provides backup-first state migration and rollback through magent system migrate and magent system rollback
Generates dependency-audit, secret-scan, CycloneDX SBOM, SHA-256, and in-toto provenance evidence for releases
Connects to 20 provider options (local and cloud) via a single config
Has 40 built-in tools out of the box — no plugins or configuration required
Includes 10 pre-built skill libraries for docs, spreadsheets, PDFs, images, video, data analysis, REST APIs, databases, desktop automation, and Git
Uses token-efficient context management: conversation compaction, repo-map slices, memory/skill budgets, and compressed tool results
Ships built-in offline documentation and self-help search through magent docs
Creates restore checkpoints before agent file writes, edits, and deletes
Reviews memory candidates through magent memory inbox before promoting selected facts into MagGraph
Groups runtime tools into capability packs that can be enabled or disabled with magent tools
Adds optional Playwright browser snapshots/screenshots and GitHub PR/issue commands through gh
Discovers project-local test/lint/build commands and reads .magent/config.toml
Builds a lightweight local code intelligence index for symbols, imports, related files, and targeted tests
Supports memory quality controls for duplicate review, node merge, and stale-node suppression
Includes a reliability test harness for the agent loop, provider layer, DB tools, CLI smokes, and packaged docs
Supports patch-first coding workflows, workspace status reports, project command roles, and release readiness checks
Supports executable plan records, session-level undo, command learning, saved reviews, and CI repair plans
Includes a durable local workbench for tasks, artifacts, project profiles, inboxes, routines, follow-ups, API bookmarks, patch queues, session timelines, static dashboards, and a live local UI
Coordinates live local agents with authenticated session-to-session messages, explicit receiving policies, durable outboxes, receipts, and strict untrusted-input boundaries
Supports a remote gateway so you can send it tasks from Slack, Discord, or Telegram while you're away from your terminal
Applies structural shell classification, outbound SSRF protection, fail-closed gateway access, atomic workbench storage, secret-hygiene checks, and optional shell sandbox profiles
Can resume saved interactive transcripts, enforce session/daily spend budgets, audit memory hygiene, and run offline provider-conformance checks

Every session, MagAgent extracts facts, preferences, and patterns from your conversation and writes them into a MagGraph knowledge graph. Next session, it reads that graph to understand your tech stack, coding style, project context, and recurring patterns — without you having to repeat yourself.

Quick Start

Install

pip install mag-agent

# Everything, including documents, media, browser, desktop, gateway, MCP, and Python LSP:
pip install "mag-agent[full]"

# With gateway support (Slack/Discord/Telegram):
pip install "mag-agent[gateway]"

# Recommended: isolate with pipx
pipx install mag-agent

The core install keeps optional document, media, desktop, gateway, browser, MCP, and LSP dependencies out of the default environment. Run magent tools doctor for readiness and exact install commands, or see Installation Shapes.

First-time setup

magent get-started
magent configure

The wizard will:

Create a named user profile with an isolated memory graph
Walk you through selecting an AI provider and model
Let you paste an API key into local config, use an environment variable, or skip credentials for later
Test the connection live

magent get-started is a plain-language guide to sessions, permissions, profiles, web research, memory, plans, goals, and Agentic Graphs. You can rerun it at any time.

If a configured cloud provider is missing credentials, magent stops before the session starts and prints the exact magent configure, magent provider set, or export ... command to fix it.

Start a session

magent

Quick one-shot task

magent ask "Refactor the auth module to use JWTs and add tests"
magent goal "Implement the dashboard until tests pass and review is clean"
magent goal "Ship the dashboard" --orchestrated
magent goal-run plan_0001 --dry-run
magent goal-run plan_0001 --retry-step 2
magent goal "Create an Astro blog and make the build pass" --run
magent goal "Ship the landing page" --background
magent jobs
magent research "topic"
magent research "topic" --write
magent docs list
magent tutorial
magent doctor
magent recipe run release-prep
magent memory inbox
magent context audit
magent statusline
magent update
magent plan "Ship the UX fixes"
magent plan --save --executable "Ship the UX fixes" -c "pytest -q"
magent plan-sandbox <plan-id> --dry-run
magent eval init
magent onboard --profile coding-cloud
magent next

Providers

MagAgent uses LiteLLM under the hood, supporting any OpenAI-compatible endpoint.

Cloud provider credentials can be stored by the setup wizard or referenced via environment variables such as OPENCODE_ZEN_KEY, OPENCODE_ZEN_API_KEY, NOUS_API_KEY, and OPENAI_API_KEY. Config display commands redact saved keys.

Provider	Config ID	Notes
Ollama	`ollama`	Local inference, free, default
Nous Portal	`nous-portal`	Hermes 4, 200+ curated models
OpenCode Zen	`opencode-zen`	Coding-optimized models
OpenCode Go	`opencode-go`	Fast, cost-efficient coding models
OpenAI	`openai`	GPT-5.x, GPT-4o, GPT-4.1, o3
Anthropic	`anthropic`	Claude Sonnet / Haiku
Google	`google`	Gemini Flash
Groq	`groq`	Ultra-fast inference
OpenRouter	`openrouter`	200+ model aggregator
LM Studio	`lmstudio`	Local GUI-managed models
AWS Bedrock	`bedrock`	Enterprise / VPC
Mistral AI	`mistral`	Mistral-hosted models
DeepSeek	`deepseek`	DeepSeek chat/reasoning models
xAI	`xai`	Grok models
Perplexity	`perplexity`	Sonar search/research models
Cerebras	`cerebras`	Fast inference models
Together AI	`together_ai`	Hosted open models
Fireworks AI	`fireworks_ai`	Hosted open and coding models
DeepInfra	`deepinfra`	Hosted open models
Custom	`custom`	Any OpenAI-compatible endpoint

Configure multiple providers and switch mid-session: /model anthropic/claude-3-5-sonnet

CLI-first provider setup:

magent provider list
magent provider detect
magent provider matrix
magent provider recommend --goal coding
magent provider explain mistral
magent provider env
magent provider models openrouter --refresh
magent provider test-matrix
magent provider set openai --model gpt-5 --api-key-env OPENAI_API_KEY
magent provider set openai --model gpt-5 --access codex
magent provider wizard
magent provider test
magent provider doctor
magent provider cooldowns
magent provider clear-cooldown openai

magent configure and magent provider wizard dynamically load the selected provider's available models after credentials are configured. The picker ranks the provider default and likely coding/tool-use models first, accepts /search words to filter large catalogs, and always accepts a model ID entered directly. OpenAI, Anthropic, Gemini, Ollama, Groq, OpenRouter, common hosted providers, and OpenAI-compatible endpoints support live discovery. When a provider does not expose model listing or is offline, MagAgent uses its cached catalog or built-in default without blocking setup.

Provider access modes are intentionally distinct:

OpenAI API: magent provider set openai --access api --api-key-env OPENAI_API_KEY
OpenAI Codex/ChatGPT plan: magent provider set openai --access codex, then run codex login
OpenCode Zen pay-as-you-go: magent provider set opencode-zen --access payg --api-key-env OPENCODE_ZEN_KEY
- OPENCODE_ZEN_API_KEY and OPENCODE_KEY are accepted aliases.
OpenCode Go subscription: magent provider set opencode-go --access subscription --api-key-env OPENCODE_GO_KEY

Route different work to different models:

magent model roles
magent model set-role coding openai/gpt-5
magent model set-role review anthropic/claude-sonnet-5
magent model set-role memory ollama/qwen2.5:7b
magent model set-role cheap openrouter/deepseek/deepseek-chat
magent model set-role image_maker openai/gpt-image-1
magent model set-role fallback "ollama/qwen2.5-coder:32b,openrouter/deepseek/deepseek-chat"
magent model health
magent model capabilities
magent model wizard
magent model image-wizard

Credential helpers:

magent auth list
magent auth add openai
magent auth remove openai
magent provider set openai --model gpt-5 --api-key-keyring openai

When Python keyring is available, magent auth add stores the provider key in the OS credential store and config can reference it without putting the secret in TOML.

Review config changes before applying them:

magent config propose "use mistral by default, manual memory, cap 2 subagents"
magent config proposals
magent config apply <proposal-id>
magent events list

Tools

MagAgent ships with 40 built-in tools the agent can call without any setup.

Tool capability packs make selective loading explicit:

magent tools list
magent tools explain web
magent tools gateway
magent tools backend nous-portal
magent tools disable desktop
magent tools enable desktop

Browser automation is optional:

pip install "mag-agent[browser]"
playwright install chromium
magent browser snapshot https://example.com
magent browser screenshot https://example.com --out example.png

The same extra enables the built-in, origin-restricted alexmerced.app WebMCP gateway. In a normal session the agent can discover the bundled alexmerced-webmcp skill, open an app page, inspect its live tools, and invoke one under the regular network and mutation permission policy. The dedicated browser profile is stored beneath ~/.local/share/magent/webmcp/ so browser-local app data persists.

File & Code Tools

Tool	Description	Permission
`read_file`	Read file preview, with truncation for large files	Silent in project, confirm outside
`read_file_range`	Read exact line ranges from a file	Silent in project, confirm outside
`outline_file`	Compact source outline with symbols and line numbers	Silent in project, confirm outside
`write_file`	Write/create a file	Auto in project dir
`edit_file`	Replace exact string in file	Auto in project dir
`delete_file`	Delete file or directory	Confirm
`list_dir`	List directory contents	Silent in project, confirm outside
`diff_files`	Unified diff between two files	Silent in project, confirm outside
`compress`	Zip or tar.gz a file/directory	Auto
`extract`	Unzip/untar an archive	Auto
`run_shell`	Execute a shell command	Tiered by command risk
`run_python`	Run Python code in isolated subprocess	Confirm
`install_package`	`pip install` with user permission	Confirm
`search_codebase`	Ripgrep pattern search	Silent
`git_op`	Any git subcommand	Tiered

Tool calls may include optional activity metadata with phase, intent, and expected fields. MagAgent displays and logs this as user-facing status and diagnostic context, then strips it before executing the tool so it cannot break tool handlers. This metadata is not chain-of-thought.

Web & Network Tools

Tool	Description	Permission
`web_search`	DDGS/DuckDuckGo search with relevance filtering (real results, no API key)	Auto
`web_fetch`	Fetch URL, clean article extraction via trafilatura	Auto
`deep_research`	Multi-query web research with source fetches and cited evidence packets	Auto
`http_request`	Full HTTP client: GET/POST/PUT/PATCH/DELETE	Auto
`browser_snapshot`	Capture title and visible text with Playwright	Auto
`browser_screenshot`	Capture a page screenshot with Playwright	Auto
`webmcp_open`	Open an alexmerced.app page and discover its live page-scoped tools	Auto
`webmcp_list_tools`	Inspect exact WebMCP names and input schemas on the current page	Auto
`webmcp_call_tool`	Invoke one discovered alexmerced.app tool	Read calls auto; mutations confirm

Data Tools

Tool	Description	Permission
`json_query`	JMESPath query over JSON file or string	Silent
`db_query`	SELECT from a named SQLite database	Silent
`db_execute`	INSERT/UPDATE/DELETE/CREATE TABLE	Auto
`db_list_tables`	List tables + row counts	Silent
`db_schema`	Show column definitions for a table	Silent
`db_list_databases`	List all user databases	Silent

System & Desktop Tools

Tool	Description	Permission
`system_info`	CPU, RAM, disk, OS, Python version	Silent
`notify`	Desktop notification (plyer / notify-send)	Silent
`clipboard_read`	Read system clipboard	Silent
`clipboard_write`	Write to clipboard	Auto
`open_file`	Open file in default application (xdg-open)	Auto
`read_image`	Image metadata + base64 for vision models	Silent in project, confirm outside

Visual Artifact Tools

Tool	Description	Permission
`create_svg`	Create a structured SVG vector artifact	Auto
`create_diagram`	Create a Mermaid diagram file	Auto
`create_image`	Create a local PNG/JPEG from structured shapes and text	Auto
`generate_image`	Generate an AI-created PNG through the configured `image_maker` model role	Auto

Permission Modes

MagAgent uses a 4-tier risk system to auto-approve safe operations and only ask when it matters.

Mode	Behaviour
`balanced` (default)	Project reads run; outside-project reads confirm; low-risk writes auto-run; medium needs Enter; high needs typed "yes"
`silent`	Only destructive or high-risk ops prompt
`paranoid`	Everything except file reads requires confirmation
`yolo`	Fully autonomous — no prompts

magent permission status
magent permission profiles
magent permission apply-profile coding
magent permission explain paranoid
magent permission set paranoid
magent permission trust-list
magent permission trust-clear "curl * | *"
/mode paranoid

Shell prompts can be approved once, for the current session, or always. Saved approvals are stored as trusted shell patterns in the active user profile. For safe read-only fetch pipelines such as curl | grep | head, MagAgent stores a broader scoped pattern like curl * | * so similar diagnostic probes do not repeatedly interrupt the session.

When a prompt explicitly names artifacts such as cheese.html, MagAgent verifies that the expected paths exist and are not obvious placeholders before finalizing.

Pre-approve patterns in your config (e.g. trust all git and pytest commands):

[permissions]
allowed_shell_patterns = ["git *", "npm *", "pytest *", "cargo *"]

Memory Graph

MagAgent's memory is powered by MagGraph — a Rust-backed in-process graph database that stores nodes as plain Markdown files in a Git repository. MagAgent uses MagGraph's native search, recall bundles, backlinks, change feed, and memory quality primitives so recall stays compact and provenance-aware.

~/.config/magent/users/<username>/memory/
├── preference_uses_typescript.md
├── project_ecommerce_backend.md
├── pattern_prefers_async_await.md
└── ...

Node types:

Type	What it stores
`preference`	Coding style, tool choices, formatting preferences
`project`	Projects you work on, their tech stack and structure
`pattern`	Recurring problems and solutions MagAgent has learned
`skill_learned`	Techniques and APIs you've used together
`fact`	Domain knowledge extracted from conversations
`session_summary`	High-level summaries of past sessions
`error_pattern`	Bugs and their resolutions
`bookmark`	URLs and references the agent saved for you

Memory is extracted and written every N turns (configurable, default 5) and always at session end.

Memory writes use MagGraph's agent-oriented node schema helpers. Inbox acceptance and context promotion refresh only changed files and return change-feed entries instead of forcing a full graph rescan.

magent memory stats                     # Node/edge counts, disk usage
magent memory index                     # Build/update semantic search sidecar
magent memory search "JWT"              # Hybrid semantic + keyword search
magent memory search --semantic "JWT"   # Force semantic search
magent memory search --keyword "JWT"    # Force keyword/full-text search
magent memory semantic status           # Inspect semantic sidecar status
magent memory semantic reset            # Reset semantic sidecar
magent memory show project_myapp        # View a node
magent memory traverse project_myapp    # BFS from a node
magent memory review --diff             # Audit pending memory graph changes
magent memory approve                   # Commit reviewed memory graph changes
magent memory quality                   # Find duplicate-looking/suppressed nodes
magent memory merge <target> <source> --preview # Preview duplicate memory merges
magent memory merge <target> <source>   # Merge duplicate memory nodes
magent memory suppress <node-id>        # Mark stale memory suppressed
magent memory unsuppress <node-id>      # Remove suppression markers
magent memory ui                        # Open MagGraph dashboard
magent memory sync status               # Run MagGraph sync status
magent memory export --out backup.json  # Export all nodes as JSON
magent memory reset                     # Wipe all memory (with confirmation)

Token-Efficient Context

MagAgent keeps context lean while preserving useful state:

Conversation compaction summarizes older turns and keeps recent turns verbatim.
Repository map slices inject relevant file/symbol maps instead of whole files.
Memory recall budgets inject MagGraph recall bundles with compact excerpts, links, backlinks, metadata, and relevance reasons.
Semantic memory search stores local SQLite embedding sidecars, uses Ollama embeddings when available, and falls back to deterministic offline vectors.
Graph-native keyword search covers IDs, types, frontmatter/tags, body text, links, suppression, and recency before MagAgent adds semantic ranking.
Selective tool injection sends a compact relevant tool subset to the model each turn instead of always injecting every built-in tool.
Skill budgets truncate long skill guidance before it crowds out the task.
Tool result compression trims large outputs and points the agent to targeted follow-ups.
Stale result pruning removes old file-read results from live context after files are edited.
Tool output budgets cap oversized tool results with a raw=true escape hatch.
Large file reads return previews; use outline_file and read_file_range for exact context.

Local Workbench

MagAgent's workbench stores practical productivity state under each user profile:

Task ledger — magent task add/list/done/report
Artifact workspace — magent artifact add/list
Project profiles — magent project profile/list/commands/roles/doctor/config/command-history/command-promote
Code intelligence — magent code index/symbols/related
Test intelligence — magent test map/related/explain/run-related
Inbox and routines — magent inbox add/triage, magent routine add/run
Follow-ups — magent followup add/list
Knowledge commands — magent knowledge remember/recall/forget
Review and planning — magent plan --save, magent plan-exec, magent plan-preview, magent plan-run, magent plan-list, magent plan-show, magent plan-apply, magent plan-discard, magent review --json, magent review --save, magent review-show, magent run
Goal loops and jobs — magent goal --verify --review, magent goal --orchestrated, magent goal-run, magent goal --background, magent jobs, magent daemon run-once, magent statusline
Repo/test helpers — magent repo-graph, magent code graph/index/symbols/related, magent test map/related/explain/run-related, magent test-intel, magent env-doctor, magent diagnostics, magent diagnostics --deep, magent ci --logs, magent ci --repair-plan --save
Patch queue — magent patch save/list/apply/revert
Patch-first workflow — magent patch preview/explain, magent workspace status/clean-report
Checkpoint undo — magent checkpoint list/show/diff/restore/restore-last/session-list/session-diff/session-restore
Built-in docs — magent docs list/show/search/doctor/generate-reference
Artifact registry — magent artifact add/list/show/open/checksum
Data/API/notes — magent data inspect, magent api save/list, magent notes
Session and usage — magent session timeline, magent stats, magent dashboard, magent dashboard --serve, magent ui
Session coordination — magent session peers/send/inbox/accept/refuse/policy/receipts/retry

Workbench files are plain JSON in ~/.config/magent/users/<username>/workbench/.

Bundled Local Web UI

Run magent ui --open for a lightweight, local Mag Command Center alternative packaged with the CLI. It provides durable multi-conversation chat, profile-backed bots, small coordinated bot groups, profile creation, guided non-secret settings, and the existing operations cockpit.

The release-ready workspace adds three operator surfaces:

Files securely discovers and previews project files and common artifacts, accepts bounded browser uploads, and attaches up to 20 selected files to the next message. Text context is inlined within a 750 KB budget; larger and binary files are passed as confined project paths. It also exposes working/staged diffs, explicit staging/unstaging/discard controls, branch and worktree inspection/creation/removal, and a shell-free command console with output and time caps.
Runs consolidates chat runs, graph history, durable execution tasks, and interval graph schedules. Tasks retain their native pause/resume/cancel/retry controls, schedules still pass graph validation and gate approval, and opt-in browser notifications report completed work.
Tools inventories built-in tool backends (including local web and optional Playwright browser support), installed plugins with integrity state, discovered skills, and configured MCP servers. Plugins can be enabled only after their existing integrity/conformance check succeeds. Secret material is never returned to the browser.

The Graphs view can open existing .agraph files, start a blank workflow, or ask the configured planning model to propose a graph from a goal. Every card is editable before execution, including its profile, dependencies, logical tools, skills, MCP servers, workspace, and portable permission requirements. Generation is constrained to MagAgent's canonical logical-tool catalog, and invalid or invented tool names plus missing permission families are repaired or rejected before the draft is offered as runnable. Deterministic drafts use the same capability-aware baseline, so obvious web research declares web_search/web_fetch and file-building work declares write and shell access. If the planning provider times out or exhausts validation repairs, the UI identifies the result as a safe runnable fallback and preserves the provider/validation reason for review rather than showing a generic failure. MagAgent saves and strictly validates the native graph before enabling Run, then moves cards through Pending, In progress, and Complete. A durable run-health panel, event counter, last-check time, animated active cards, and per-card outcomes remain attached when you leave the view and return. The health panel also reports the active card and its latest safe lifecycle or declared-tool event; it never exposes private reasoning or tool arguments.

A turn is a run, not a request. It executes on its own thread and finishes whether or not anyone is watching, so closing the tab no longer kills the work and loses the reply. Streams read the run's event log from a cursor, so reloading mid-turn picks it back up rather than losing what was said, and Stop cancels the run itself instead of just the connection, keeping whatever had already been written.

Tool approvals reach the browser for both conversations and graph cards. The Web UI has a user but no console, so without somewhere to ask it could only refuse every tool above the permission mode's auto-approve threshold. A tool needing a decision now pauses its work and presents an approval in the browser. Graph approvals overlay whichever UI section is open and are restored after a reload; shell actions offer deny, once, session, and exact-command persistent choices. Unanswered is a denial: a closed tab must not leave a tool authorised. Delegated subagents inherit that same browser approval channel, so a bot, group participant, or graph card cannot strand a permission question on the UI process's terminal.

A Memory view browses what the agent has kept — the graph's size and health, full note text, and the notes linking to and from each one, searchable in the same modes the agent's own recall uses. Notes can be created and edited explicitly, and deletion requires browser confirmation.

Opening the UI on a machine that has never been set up shows a setup panel rather than a composer whose first message is guaranteed to fail. It never accepts a credential: keys stay in the environment or the system keyring, and it reports only whether one was found and which variable it expects.

Assistant replies render as markdown: headings, lists, blockquotes, and fenced code blocks with a copy button. Model output is treated as untrusted because it can quote a hostile file, a scraped page, or a tool result, so embedded HTML stays visible text rather than becoming elements, and only http, https, mailto, and same-document links are followed.

The server remains loopback-only and uses a per-launch token plus CSRF protection. See magent docs show ui for behavior and API details.

The interface is a React and TypeScript application under webui/, built by Vite into src/magent/webui/static/. That bundle is committed and ships inside the wheel, so installed users never need Node. Any change under webui/src must be rebuilt and committed in the same change; the Web UI workflow rebuilds and fails when the shipped assets no longer match their source.

SQLite Local Databases

The agent can create and manage structured local databases — per user, per project, or user-specified.

~/.config/magent/users/<username>/databases/
├── default.db       # General-purpose
├── myproject.db     # Project-specific
└── analytics.db     # Purpose-specific

Inside a session, the agent automatically uses these tools to store structured data — task lists, research caches, API test logs, contacts — without any setup required.

/db    # In-session: list your databases

Skills

Skills are Markdown files that teach the agent how to perform specific tasks — code patterns, library usage, common pitfalls, and decision guides. They are injected into context automatically when relevant.

Locations

Global: ~/.config/magent/skills/<skill-name>/SKILL.md
Project-local: .magent/skills/<skill-name>/SKILL.md

Built-in Skills Library

MagAgent ships with 10 pre-built skills in docs/skills/:

Skill	Triggers On	Guide
Create Word Docs	docx, word document, report	python-docx + docxtpl
Create Spreadsheets	excel, xlsx, spreadsheet	openpyxl with charts/formulas
Create PDFs	pdf, html to pdf	fpdf2 + WeasyPrint + pypdf
Create Images	image, chart, plot, PNG	Pillow + matplotlib
Create Video/Audio	video, audio, mp4, Remotion	Remotion (React) + moviepy + ffmpeg
Data Analysis	pandas, csv, dataframe	pandas + SQLite integration
REST API Testing	api, http, endpoint, curl	http_request patterns + auth
SQLite Database	sql, database, sqlite	Named DBs, common schemas
Desktop Automation	notify, clipboard, open file	notify + clipboard + system info
Git Workflow	git, branch, commit, merge, rebase	Git best practices & conflict resolution

Writing Your Own Skill

---
name: my-skill
description: Brief description — used for matching
version: "1.0"
trigger_keywords:
  - keyword1
  - keyword2
tools_required:
  - run_shell
  - write_file
---

# Skill Title

Guidance for the agent here — code patterns, library usage, pitfalls...

Sub-Agents

Spawn a parallel agent to work on a focused sub-task while you continue the main conversation:

/spawn Write unit tests for all functions in src/auth.py

The sub-agent runs an isolated session sharing your memory graph, completes the task, and returns a summary. Use this for long-running tasks that shouldn't interrupt the main flow.

Agentic Graphs

MagAgent supports Agentic Graph Specification 1.0 through conformance level 3. AGS files are portable, reviewable DAGs with typed contracts, model-tier routing, parallel branches, loops, maps, subgraphs, budgets, retries, human gates, harness-owned criteria, and portable run records.

magent graph generate "ship the next API version" --project . --out release.agraph.yaml
magent graph validate release.agraph.yaml --strict
magent graph plan release.agraph.yaml
magent graph run release.agraph.yaml --project .

Graph permissions only restrict MagAgent's existing policy; they never expand it. See Agentic Graphs, the examples, and the machine-readable AGS result for authoring, safety, runtime, and conformance details. The corresponding OAP result records the pinned profile requirements and upstream revision.

The main agent can orchestrate sub-agents, and the cap is configurable:

magent subagent configure --max 3 --parallel 2 --model-role coding
magent subagent status
magent subagent run "Audit the auth tests"

Set --max 0 to disable sub-agent spawning.

Remote Gateway

Send tasks to MagAgent from Slack, Discord, or Telegram while you're away from your terminal.

# Install gateway dependencies
pip install "mag-agent[gateway]"

# Generate config template
magent gateway init

# Configure from the CLI
magent gateway configure telegram --bot-token "$TELEGRAM_BOT_TOKEN" --allowed-user 12345
magent gateway configure slack --bot-token "$SLACK_BOT_TOKEN" --app-token "$SLACK_APP_TOKEN"
magent gateway wizard discord
magent gateway doctor

# Start (background daemon)
magent gateway start

# Platform-specific
magent gateway start slack
magent gateway start discord telegram

# Monitoring
magent gateway status
magent gateway logs --follow
magent gateway stop

How it works

When you message the bot:

It immediately replies "⏳ Working on it..."
Runs your task through the full agent (tools, memory, etc.)
Edits that message with the result when done
Sessions are persistent per channel — it remembers conversation context

Security

Allowlist — only users in allowed_user_ids can send instructions
Channel restriction — optionally limit to specific channels
Rate limiting — configurable per-user request limit (default 10/min)
Task timeout — configurable max execution time (default 5 min)
Durable execution runtime — versioned task states, parent/child work, ordered event cursors, audit evidence, and pause/resume/cancel/retry controls shared by daemon jobs, staged goals, CLI clients, and desktop integrations

Setup Guides

Platform	Guide	Notes
Slack	setup-slack.md	Socket Mode — no public URL needed
Discord	setup-discord.md	Bot token — free, 2-minute setup
Telegram	setup-telegram.md	@BotFather — simplest of the three

All Commands

User Management

magent user create <name>   # Create a user profile
magent user switch <name>   # Switch active user
magent user list            # List all users
magent user delete <name>   # Delete user + memory (with confirmation)
magent user current         # Show active user

Memory

magent memory stats                      # Node/edge counts, disk usage
magent memory search "<query>"           # Search memory graph
magent memory show <node-id>             # View a memory node
magent memory traverse <node-id>         # BFS traversal from a node
magent memory delete <node-id>           # Delete a node
magent memory export --out backup.json   # Export all nodes as JSON
magent memory reset                      # Wipe all memory (prompts "yes")
magent memory log                        # View recent session logs
magent memory ui                         # Open embedded MagGraph UI
magent memory sync status                # Git sync status via MagGraph
magent memory sync pull                  # Pull memory graph updates
magent memory sync push -m "message"     # Commit/push memory graph updates
magent memory configure --mode inbox-first --write-every 3

Gateway

magent gateway init              # Print example config
magent gateway configure telegram # Save platform tokens and allowlists
magent gateway wizard slack      # Prompt for tokens and user/channel allowlists
magent gateway doctor            # Show gateway readiness
magent gateway start             # Start all configured platforms (daemon)
magent gateway start slack -f    # Single platform, foreground mode
magent gateway stop              # Stop daemon (SIGTERM)
magent gateway status            # Is daemon running? PID?
magent gateway logs [-n N] [-f]  # View / follow gateway log

Other

magent setup           # First-run setup wizard
magent configure       # Friendly setup/configuration wizard
magent onboard         # Apply guided profile + project defaults
magent next            # Suggest useful next actions
magent profile list    # Guided configuration presets
magent profile apply   # Apply provider/memory/subagent preset
magent profile wizard  # Create a complete Open Agent Profile interactively
magent profile default # Show the profile used by ordinary sessions
magent profile set-default NAME
magent agent schema    # Machine-readable OAP editor contract and local choices
magent agent preview --input profile.json
magent agent apply --input profile.json --scope project
magent agent revisions NAME
magent config backup   # Back up global/current-user config
magent config diff     # Diff current config against a backup
magent config restore  # Restore config from a backup
magent provider list   # Known providers and default models
magent provider detect # Provider readiness from local environment
magent provider matrix # Provider catalog and readiness table
magent provider recommend # Recommend providers for a goal
magent provider set    # Set default provider/model
magent provider wizard # Interactive provider/access/model setup
magent provider models # Cached/live model discovery for one provider
magent provider doctor # Provider/config readiness
magent provider cooldowns # Show rate-limit cooldowns
magent model roles     # Show role-specific model routing
magent model set-role  # Set coding/review/memory/cheap/image_maker/fallback role
magent model capabilities # Show inferred model capabilities by role
magent model wizard    # Interactive model role setup
magent model image-wizard # Interactive image model role and credential setup
magent auth add        # Store a provider key in the OS keyring
magent subagent status # Show sub-agent caps/defaults
magent subagent run    # Run one focused sub-agent task
magent subagent wizard # Interactive sub-agent setup
magent mode <mode>     # Set permission mode globally
magent doctor          # Health check: providers, memory, deps
magent doctor --json   # Structured actionable readiness checks
magent doctor --fix    # Apply safe local config fixes
magent plan "goal"     # Generate a local implementation plan
magent run "goal"      # Record an autonomous work-session plan
magent review          # Heuristic local diff review
magent repo-graph      # Lightweight repo import graph
magent graph plan FILE # Preview a portable Agentic Graph
magent code index      # Build local symbol/import/test index
magent code symbols    # Search indexed code symbols
magent code related    # Show related tests/import peers for a file
magent test map        # Map source files to likely tests
magent test related    # Show likely tests for a file
magent test explain    # Explain why tests were selected
magent test run-related # Run likely tests for a file
magent test-intel      # Suggest tests for current git changes
magent patch preview   # Preview a saved patch
magent patch explain   # Explain patch impact
magent workspace status # Show git/workbench status
magent release check   # Run release readiness checks
magent project init    # Bootstrap .magent config and playbook
magent project wizard  # Guided project bootstrap
magent env-doctor      # Project environment checks
magent dashboard       # Export static local dashboard
magent ui              # Serve live local operations UI
magent --version       # Show version

In-Session Slash Commands

Command	Description
`/help`	All slash commands
`/compose`	Write a formatted multiline prompt
`/goal <task>`	Run a measurable goal-loop prompt with verifier/reviewer instructions
`/jobs`	Show background daemon jobs
`/context [query]`	Audit current context, memory recall, plans, and cleanup suggestions
`/config`	Show the interactive session config control center
`/statusline`	Preview compact statusline output
`/usage`	Show token, tool, cost, and slow-step diagnostics for this session
`/insights`	Summarize recent session logs
`/session`	Show this session's durable ID, display name, project, and receiving policy
`/peers`	List other live local MagAgent sessions
`/send <peer> <text>`	Send an authenticated local coordination message
`/inbox [held]`	Inspect accepted or held peer messages
`/accept <message-id>`	Accept a held peer message
`/refuse <message-id>`	Refuse a held peer message
`/receipts`	Show this session's delivery receipts
`/memory`	Memory graph stats
`/skills`	Loaded skills list
`/model`	Current model / change model
`/user`	Active user
`/mode <mode>`	Change permission mode
`/retry`	Retry the previous prompt after removing the last exchange from context
`/undo`	Remove the last exchange from conversation context
`/spawn <task>`	Spawn a sub-agent
`/db`	List your SQLite databases
`/clear`	Clear conversation history
`/exit`	End session

Prompt Caching

MagAgent keeps stable agent instructions ahead of changing memory/repo/session context so provider prefix caches have something repeatable to reuse. Inspect the current setup with magent cache doctor and review local cache telemetry with magent cache status.

In interactive sessions, use /compose for reliable multiline prompts. Shift+Enter inserts a newline when your terminal reports it distinctly. Shell permission prompts can be approved once, for the current session, or saved as an exact trusted command for future sessions.

Configuration

Prefer the CLI for common changes:

magent provider set openai --model gpt-5 --api-key-env OPENAI_API_KEY
magent provider set openai --model gpt-5 --access codex
magent model set-role review anthropic/claude-sonnet-5
magent memory configure --mode inbox-first --semantic --write-every 3
magent memory wizard
magent gateway configure telegram --bot-token "$TELEGRAM_BOT_TOKEN"
magent subagent configure --max 3 --parallel 2
magent project init

Safety and diagnostics

# Explain a command's risk tier without executing it
magent permission classify "curl -s https://example.com | head"

# Check plaintext credentials, config permissions, and gateway exposure
magent permission secrets

# Validate provider request construction without spending API quota
magent provider conformance

# Preview duplicate/stale memory; add --apply only after review
magent memory hygiene

# List and continue durable interactive transcripts
magent resume --list
magent resume SESSION_ID

Gateways deny all remote users until allowed_user_ids is configured, unless the operator explicitly enables allow_anyone. Mutating HTTP requests require confirmation, local web UIs use per-launch access tokens, and shell trust rules are matched structurally rather than as raw wildcards. See Security and hardening for configuration details.

Optional host-execution and spend guardrails live in the same global config:

[permissions]
shell_sandbox = "off"          # off, docker, bubblewrap, or sandbox-exec
shell_sandbox_network = false

[budgets]
session_usd = 0.0               # 0 disables the limit
daily_usd = 0.0
warn_at = 0.8

Where settings live, and which wins

MagAgent reads two files and merges them:

Layer	Path	Scope
Global config	`~/.config/magent/config.toml`	Defaults for every user profile on this machine
User profile	`~/.config/magent/users/<user>.toml`	One person's overrides

The user profile wins for any key both define. A few notes that are easy to get wrong:

[permissions] allowed_shell_patterns and trusted_shell_patterns merge rather than replace: profile entries are consulted first, then global ones. (Before 0.36 the global section was read for neither.)
[memory] write_every_n_turns = 0 means disable periodic memory writes. It is not the same as leaving the key out, which uses the default of 5.
magent mode and the in-session /mode command are the same setting and are both persisted to the user profile.
Project-local .magent/config.toml covers project settings (hooks, playbooks); it does not override credentials or permissions.

Full config at ~/.config/magent/config.toml:

[defaults]
provider = "ollama"
model = "qwen2.5-coder:32b"
permission_mode = "balanced"
context_window_tokens = 32000
memory_budget_tokens = 4000
repo_map_budget_tokens = 1200
skill_budget_tokens = 2000

[memory]
write_every_n_turns = 5
extraction_provider = "ollama"
extraction_model = "qwen2.5:7b"
encrypt = false
recall_body_tokens = 220

[models]
coding = "openai/gpt-4.1"
review = "anthropic/claude-sonnet-4"
memory = "ollama/qwen2.5:7b"
cheap = "opencode-go/deepseek-v4-flash"
image_maker = "openai/gpt-image-1"
fallback = ["ollama/qwen2.5-coder:32b"]

[context]
compact_every_n_turns = 10
keep_recent_turns = 6
max_history_tokens = 6000

[permissions]
mode = "balanced"
allowed_shell_patterns = ["git *", "npm *", "pytest *"]

[providers.ollama]
base_url = "http://localhost:11434"
default_model = "qwen2.5-coder:32b"

[providers.nous-portal]
base_url = "https://inference-api.nousresearch.com/v1"
api_key_env = "NOUS_API_KEY"
default_model = "nous-hermes-4"

[providers.opencode-go]
base_url = "https://opencode.ai/go/v1"
api_key_env = "OPENCODE_GO_API_KEY"
default_model = "deepseek-v4-flash"

[gateway]
username = "alex"
allowed_user_ids = ["YOUR_SLACK_USER_ID"]
rate_limit_per_minute = 10
max_task_duration_seconds = 300

[gateway.slack]
bot_token = "xoxb-..."
app_token = "xapp-..."

[gateway.discord]
bot_token = "..."

[gateway.telegram]
bot_token = "..."

Documentation

Document	Description
docs/skills/create-word-docs/SKILL.md	Word document generation (python-docx, docxtpl)
docs/skills/create-spreadsheets/SKILL.md	Excel spreadsheet generation (openpyxl)
docs/skills/create-pdfs/SKILL.md	PDF generation (fpdf2, WeasyPrint, pypdf)
docs/skills/create-images/SKILL.md	Image manipulation (Pillow, matplotlib)
docs/skills/create-video-audio/SKILL.md	Video/audio (Remotion, moviepy, ffmpeg)
docs/skills/data-analysis/SKILL.md	Data analysis (pandas, SQLite)
docs/skills/rest-api/SKILL.md	REST API testing and integration
docs/skills/sqlite-database/SKILL.md	SQLite database patterns
docs/skills/desktop-automation/SKILL.md	Desktop notifications, clipboard, system info
docs/skills/git-workflow/SKILL.md	Git workflows & conflict resolution
docs/gateway/setup-slack.md	Slack gateway setup (Socket Mode)
docs/gateway/setup-discord.md	Discord gateway setup
docs/gateway/setup-telegram.md	Telegram gateway setup
src/magent/docs/mcp.md	MCP configuration, compatibility, diagnostics, and skills status
src/magent/docs/session-messaging.md	Authenticated local agent coordination, policies, receipts, recovery, and security
src/magent/docs/agents.md	Open Agent Profile authoring, trust, narrowing, state review, and legacy migration

Development

git clone https://github.com/AlexMercedCoder/MagAgent.git
cd MagAgent
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=src/magent --cov-report=term-missing

# Lint
ruff check src/

# Built-in docs coverage
magent docs doctor

# Type check
mypy src/magent

Project Structure

src/magent/
├── agent.py          # AgentSession — tool loop, streaming, sub-agents
├── cli/
│   ├── app.py        # Typer app and command-group composition
│   ├── command_context.py # Shared command helper/context functions
│   └── main.py       # CLI entry point and command implementations
├── config/           # TOML config, user profiles
├── gateway/          # Remote gateway (Slack, Discord, Telegram)
│   └── adapters/     # Platform-specific adapters
├── memory/           # MagGraph integration — read, write, search
├── permissions/      # Risk tiers, auto-approve logic
├── providers/        # LiteLLM provider registry
├── repo_map.py       # Token-efficient repository map cache
├── records.py        # Typed record helpers for common dict payloads
├── skills/           # SKILL.md discovery, matching, lockfile
├── subagents/        # Sub-agent runner
├── tokens.py         # Lightweight token budgeting helpers
├── tools/            # 47 built-in tools (file, web/WebMCP, browser, db, system, image)
│   ├── executor.py   # Stable ToolExecutor dispatch facade
│   ├── artifacts.py  # Document, diagram, and image capability tools
│   ├── data.py       # JSON query and named SQLite facade tools
│   ├── files.py      # File, directory, diff, docs, and archive tools
│   ├── shell.py      # Shell, Python, package, and code-search tools
│   ├── system.py     # System, clipboard, notification, and image tools
│   ├── web.py        # Search, research, HTTP, and browser tools
│   └── db.py         # SQLite named database tools
├── context.py        # Context map and memory promotion bridge
├── workbench.py      # Local productivity ledgers and workflow helpers
├── workbench_domains/ # Domain import modules for future workbench extraction
├── workbench_store.py # JSON-backed workbench storage primitive
├── logging.py        # JSONL session event logging
├── setup.py          # First-run wizard
└── tui.py            # Rich terminal UI, theme, status, and streaming renderer
docs/
├── gateway/          # Gateway setup guides
└── skills/           # Built-in skill SKILL.md files
tests/
└── unit/             # Fast automated tests (no credentials needed)

License

Apache 2.0 — see LICENSE

Built with 🐦‍⬛ by Alex Merced · Powered by MagGraph

Like the Magpie — intelligent, tool-using, and never forgets.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
evals		evals
examples/plugin-sdk/review-pack		examples/plugin-sdk/review-pack
src/magent		src/magent
tests		tests
webui		webui
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
Makefile		Makefile
PRD.md		PRD.md
README.md		README.md
ROADMAP.md		ROADMAP.md
pyproject.toml		pyproject.toml

Latest commit

History

Folders and files

Repository files navigation