munder-difflin

Overview

munder-difflin is a local-first, multi-agent harness designed for running multiple AI agents in parallel on a single machine. With approximately 2,500 GitHub stars, it occupies a niche between heavyweight agent frameworks (LangGraph, AutoGen) and lightweight single-agent CLIs (Claude Code, Codex). Its defining characteristic is a tmux-like multiplexing model for AI agents — you can spawn, monitor, and interact with multiple agent sessions simultaneously from the terminal.

The project's name is a play on "under diff lining" — the idea that the harness sits beneath your agent workflows, managing the complexity of parallel execution while you focus on task definition. Like tmux solved the problem of managing multiple terminal sessions, munder-difflin solves the problem of managing multiple agent sessions.

munder-difflin is particularly relevant in the context of the broader "agent multiplexing" trend (see also herdr, which reached 12K stars). As AI agents become more capable, the bottleneck shifts from individual agent quality to orchestration efficiency — how quickly can you spin up dozens of specialized agents to tackle different facets of a complex problem?

Features

• Terminal multiplexing for agents: tmux-like UI for managing multiple agent sessions
• Local-first: Runs entirely on your machine; no cloud dependencies
• Parallel execution: Run N agents simultaneously, each with isolated context
• Session persistence: Agent sessions survive terminal disconnections
• Resource-aware scheduling: Automatically throttles agents based on system load
• Cross-agent messaging: Agents can send messages to each other for coordination
• Model-agnostic: Works with any local or remote LLM via OpenAI-compatible API
• Configurable agent types: Define agent roles, tool sets, and constraints per session
• Logging and replay: Full session logging with playback capability
• Plugin system: Extend with custom agent behaviors and tools

Installation

# Install via pip
pip install munder-difflin

# Or from source
git clone https://github.com/munder-difflin/munder-difflin
cd munder-difflin
pip install -e .

# Verify installation
mdf --version

Quick Start

# Start the harness
mdf start

# Create a new agent session (like creating a new tmux window)
mdf new --name "researcher" --model "claude-4.7-sonnet"
mdf new --name "coder" --model "gpt-5.6-sol"
mdf new --name "reviewer" --model "claude-4.7-sonnet"

# Send a task to a specific session
mdf send "researcher" "Research the latest developments in MCP 2.0"
mdf send "coder" "Build a Python script that parses MCP protocol messages"
mdf send "reviewer" "Review the output of the coder session"

# Switch between sessions
mdf switch researcher
mdf switch coder

# Monitor all sessions
mdf watch

# Send a message between agents
mdf broadcast "Here is the research summary: [paste]"

# Stop a session
mdf stop researcher

# Stop the harness
mdf stop

Configuration

Create ~/.config/munder-difflin/config.yaml:

models:
  claude-4.7-sonnet:
    api_base: https://api.anthropic.com
    api_key_env: ANTHROPIC_API_KEY
  gpt-5.6-sol:
    api_base: https://api.openai.com
    api_key_env: OPENAI_API_KEY

defaults:
  max_tokens: 8192
  temperature: 0.7
  system_prompt: "You are a focused agent. Do only what you are asked."

resources:
  max_concurrent: 4
  cpu_threshold: 0.8
  memory_threshold: 0.85

Core Concepts

Sessions as Windows

In munder-difflin, each agent runs in an isolated session, analogous to a tmux window. Sessions are independent: each has its own model, tools, conversation history, and file system access scope. You can have dozens of sessions running simultaneously, each focused on a different task.

Agent Archetypes

munder-difflin ships with predefined agent archetypes:

• researcher: Web search + synthesis agent
• coder: Code generation and refactoring agent
• reviewer: Code review and quality assurance agent
• planner: Task decomposition and planning agent
• test-runner: Automated testing and verification agent
• custom: User-defined with custom system prompt and tools

Cross-Agent Messaging

Agents can communicate with each other through a messaging system:

# In Python API
from munder_difflin import Harness

harness = Harness()
researcher = harness.create_agent("researcher")
coder = harness.create_agent("coder")

# Researcher sends findings to coder
researcher.send_to(coder, "Research found that FastAPI is the best fit for this use case")

# Coder can respond back
coder.send_to(researcher, "Thanks! I'll implement with FastAPI then.")

Advanced Features

Task Pipeline

Define a pipeline where output from one agent feeds into the next:

# pipeline.yaml
pipeline:
  - name: planner
    task: "Break down this project into tasks: {project_description}"
    output_to: task_list
  
  - name: coder
    task: "Implement tasks from: {task_list}"
    depends_on: planner
    parallel: true  # Multiple coders can work in parallel
  
  - name: reviewer
    task: "Review all code produced by coders"
    depends_on: coder

mdf run-pipeline pipeline.yaml --project-description "Build a blog platform"

Resource-Aware Scheduling

munder-difflin monitors system resources and automatically adjusts agent concurrency:

Active sessions: 6
CPU usage: 78% — 2 agents throttled
Memory usage: 82% — KV cache compressed for 1 agent
Disk I/O: Normal

When resources are constrained, agents are automatically paused, resumed, or downgraded (e.g., from a larger model to a smaller one) to maintain system responsiveness.

Session Replay

Every agent session is logged in full, including tool calls, model responses, and timing information:

# Replay a past session
mdf replay --session "coder" --date "2026-08-15"

# Export session as JSON
mdf export --session "coder" --format json --output session.json

Examples

Example 1: Parallel Code Review

# Create 4 reviewers, each assigned to a different module
mdf new --name "reviewer-auth" --task "Review auth module"
mdf new --name "reviewer-api" --task "Review API module"
mdf new --name "reviewer-db" --task "Review database module"
mdf new --name "reviewer-ui" --task "Review UI components"

# Wait for all to complete
mdf wait --all

# Aggregate results
mdf aggregate --format markdown --output review-summary.md

Example 2: Research-to-Implementation Pipeline

# Research phase
mdf new --name "research" --task "Research best practices for rate limiting in Python APIs"
mdf wait research

# Implementation phase (parallel)
mdf new --name "impl-fastapi" --task "Implement rate limiting with FastAPI"
mdf new --name "impl-flask" --task "Implement rate limiting with Flask"
mdf wait --all

# Comparison phase
mdf new --name "compare" --task "Compare both implementations and recommend one"
mdf wait compare
mdf send compare "Review outputs from impl-fastapi and impl-flask"

Example 3: Agent Swarm

# Spawn 10 exploration agents to analyze different parts of a codebase
for i in $(seq 1 10); do
  mdf new --name "explorer-$i" --task "Analyze module $i of the codebase and document patterns"
done

mdf wait --all
mdf aggregate --format markdown --output codebase-analysis.md

Pros

• ✅ tmux-like UX: Familiar mental model for terminal power users
• ✅ Truly local: No cloud dependencies, data never leaves your machine
• ✅ Parallel execution: Dramatically speed up multi-faceted tasks
• ✅ Resource-aware: Won't overwhelm your system with too many concurrent agents
• ✅ Cross-agent messaging: Enables sophisticated multi-agent coordination
• ✅ Session persistence: Agents survive terminal disconnects
• ✅ Model-agnostic: Works with any OpenAI-compatible API

Cons

• ❌ Small community: ~2.5K stars, early-stage project
• ❌ Terminal-only: No GUI or web interface
• ❌ No built-in tools: You must configure tools for each agent separately
• ❌ Learning curve: tmux-like UX is unintuitive for users unfamiliar with terminal multiplexers
• ❌ No cloud sync: Sessions are local-only; no cross-machine collaboration
• ❌ Limited documentation: Project is still establishing its docs

When to Use

• Parallel task execution: When you have multiple independent tasks that different agents can tackle simultaneously
• Agent experimentation: When you want to compare how different models handle the same task
• Large codebase analysis: When you need multiple agents to explore different parts of a codebase in parallel
• Pipeline orchestration: When tasks have dependencies that form a natural pipeline
• Resource-constrained environments: When you need fine-grained control over agent resource usage
• Local-first workflows: When data privacy requirements prohibit cloud-based orchestration

Resources

• GitHub Repository
• Documentation

Related Projects

• herdr — tmux-like multiplexing for AI agents (12K stars)
• LangGraph — Graph-based agent orchestration
• AutoGen — Multi-agent conversation framework
• Agency-Agents — Multi-agent platform (127K stars)