Multi Agent Kernel (MAK)

---

A kernel for concurrent multi-agent software development.

Multiple agents edit one shared working directory at the same time.

No worktrees, no merge step, no late-stage reconciliation.

The Multi Agent Kernel arbitrates concurrent access the way an OS arbitrates shared memory between threads.

Table of Contents

• The Idea
• Install
• Update
• Housekeeping
• Run
  • CLI App
  • CLI Command
• Configuration & API Keys
• Benchmark
• Contribute
• License

The Idea

Most multi-agent coding systems give each agent a Git branch and merge at the end. A message-passing model where conflicts surface late, after the dependency information needed to resolve them is gone.

The Multi Agent Kernel takes the shared-memory approach.

• The codebase is decomposed into independently lockable AST nodes (functions, methods, classes, headers).

• Files on disk are derived artifacts reconstructed from a versioned node store.

• The kernel owns a symbol-level lock table and resolves conflicts at scheduling time, where the dependency graph is still explicit.

• Each agent receives only the nodes it holds write locks on, edits them in isolation, and returns the modified fragments. The kernel reassembles the file.

• Around those write targets the kernel assembles the agent's read context automatically: same-file siblings, cross-file callers, and — for a task that depends on another — whatever that dependency just built, so an agent writing a brand-new module is never guessing at the API of the module beside it. Each layer is budget-bounded, so context stays relevant rather than growing with the repo. A task that would arrive with no context at all is a kernel bug, and MAK fails it rather than shipping the guess.

• After a wave, MAK re-checks what that wave left behind — callers a changed signature broke, and new modules that disagree about each other's API — and offers the fix-ups as another reviewable plan.

• Before dispatch, the kernel cross-checks the planner's proposed plan against that same AST-derived dependency graph — grounding hallucinated node ids, adding missing depends_on edges, and flagging spurious ones — so a bad LLM guess is corrected before it reaches the scheduler, not after a collision.

Check out the knowledge graph for this project. (created with graphify)

Install

Prerequisites: Python ≥ 3.11, uv (or pipx), git

With uv (Recommended)

uv tool install git+https://github.com/chaseungjoon/multi-agent-kernel

With pipx

pipx install git+https://github.com/chaseungjoon/multi-agent-kernel

mak --version

From source (for contributors)

git clone https://github.com/chaseungjoon/multi-agent-kernel
cd multi-agent-kernel
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# Run binary
./bin/mak

Update

mak update

mak update moves to the newest published release tag, prints the version it is moving to before installing, and reports honestly when you are already current. It only ever updates a uv tool install; a source checkout is left alone (use git pull). Until this repo publishes its first tag, mak update falls back to the tip of main and says so.

Housekeeping

mak gc              # prune this project's node store
mak gc /path/to/project

Every edit MAK commits writes a new version of the node into .mak/node_store/. Recent versions are kept so a bad edit can be rolled back — five by default, tunable with node_store.version_retention (minimum 2, or -1 to keep every version forever) — and anything older is pruned as the commit lands. mak gc applies that policy to a store written by an older MAK, which kept everything, and removes fragment directories that no node addresses any more.

Run

⚠️ Currently, MAK only supports Python codebases, there are plans to add other language support in the near future.

CLI App

Launch the interactive app from any directory:

mak

Features

Type / to browse all commands with one-line descriptions. (Tab autocomplete)

/help lists commands and shortcuts.

• /status - Live session status (models, planner, agents, workdir, approval, tokens)
• /apikey - Set api keys of providers
• /work-dir <path> - Set working directory
• /models <provider-1>:<model> <provider-2>:<model> ... - Set agent models
• /planner <provider>:<model> - Set planner model
• /refresh-models - Re-fetch the model list from each provider right now
• /max-agents <int> - Set number of agents
• /config - Returns to auto-discovery (see Configuration & API Keys)
• /config /path/to/config.yaml - Point to a custom config
• /no-review true - Omit user review of planner (default false, not recommended to turn on)
• /clear - clears the screen, /exit (or /quit, Ctrl+C) quits, Ctrl+J inserts a newline for multi-line tasks.

---

CLI Command

For scripted / non-interactive runs, use mak run (equivalently python3 -m mak in a source checkout). Set your API keys first — see Configuration & API Keys. You only need keys for the agents you actually run.

⚠️ Just to be safe, create a separate branch for MAK to work on

# Example with claude opus 5, gpt-5.6 sol and gemini 3.5 flash
mak run --task "your task" --work-dir /path/to/project \
  --models anthropic:claude-opus-5 openai:gpt-5.6-sol gemini:gemini-3.5-flash

# Example with claude sonnet 5 X 5 (provider default model)
mak run --task "your task" --work-dir /path/to/project \
  --models anthropic --max-agents 5

Command line arguments

# Describe task
--task "Describe your task here"

# Set working directory
--work-dir /path/to/project

# Omit human review (Not recommended)
--no-review

# Resume a crashed run from .mak/task_graph.json (no --task needed)
--recover

# Default model
--models anthropic
--models openai
--models gemini

# Set model
--models anthropic:claude-opus-5
--models openai:gpt-5.6-terra
--models gemini:gemini-3.1-pro-preview

# Use multiple providers (tasks are distributed round-robin across them)
--models anthropic openai gemini
--models anthropic:claude-opus-5 openai:gpt-5.6-sol gemini:gemini-3.5-flash

# Use single provider with multiple agents
--models anthropic --max-agents 5 
--models anthropic:claude-opus-5 --max-agents 3

# Choose a custom config file (default: auto-discovered, see below)
--config /path/to/config.yaml

Default models list for each provider — kept current automatically: MAK re-fetches each provider's model list in the background twice a month (1st and 15th), so new models show up in /models and /planner without an update. Run /refresh-models to fetch immediately instead of waiting.

Note on claude-fable-5: MAK supports Anthropic's most capable model, but it comes with caveats — it requires an org with 30-day data retention (zero-data-retention orgs get a 400 on every request), it can decline requests with a refusal stop reason (which MAK treats as a failed task), and it is priced above Opus tier ($10/$50 per MTok). MAK prints this warning whenever you select it as a planner or agent model.

Configuration & API Keys

API keys. MAK drives hosted models from three providers — Anthropic, OpenAI, and Google Gemini. Keys are read from the environment (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY) or from ~/.config/mak/.env — the TUI's /apikey command (and its first-run setup) writes them there for you, creating the file readable only by you (0600). Exported environment variables always win.

Deprecated: a source checkout's mak/.env is still read, but it lives inside the package directory and nothing enforces its permissions — a working copy is routinely left world-readable with live keys in it. MAK now warns when it reads one; move your keys to ~/.config/mak/.env (or just run /apikey). The next release stops reading the legacy location.

Config file. When --config (or /config) is not given, MAK auto-discovers its configuration, first match wins:

1. ./mak.yaml — a per-project config in the current directory
2. ~/.config/mak/config.yaml (respects $XDG_CONFIG_HOME) — your user default
3. The built-in default shipped with the package (view it)

To customize, copy the built-in default to either location and edit it.

What MAK reads. node_store.include_patterns / exclude_patterns decide which files are ingested. Setting exclude_patterns replaces the defaults, so start from the shipped list rather than writing a shorter one — it excludes generated and vendored directories (.git, build, dist, .tox, .mypy_cache, .pytest_cache, site-packages, node_modules, .venv, __pycache__) as well as MAK's own .mak/ store. MAK skips its own .mak/ directory regardless of what you configure, and prunes any node left behind by an older version that did ingest it — if you have a .mak/ from before v0.5.3, the next run cleans it up (deleting the directory yourself is the blunt alternative).

Capping what a run costs. Nothing bounds a run's spend by default: retries, iterations, and cascade waves multiply out. Set session.max_total_tokens to cap it — input plus output, every agent call plus the planner's, counted from what each provider reported on its own response. On a breach MAK stops dispatching, lets what is already in flight finish and commit, and reports the run as failed naming the budget. It never interrupts a commit, so the working tree is never left half-written.

session:
  max_total_tokens: 2000000   # unset (the default) is unbounded

Where .mak/ lives. MAK's node store, task graph, and session log always live under --work-dir (default session.mak_dir is .mak, relative to the project) — never relative to the directory you happened to launch mak from. This matters when you drive more than one project from the same shell: each project keeps its own state, so a run against ../other-project can never read or write another project's .mak/. If a stale .mak/ from before this was fixed sits next to your shell, MAK reports it on stderr and leaves it alone rather than adopting it — delete it by hand once you've confirmed you don't need it.

Benchmark

benchmark/ pits MAK against a traditional git-worktree multi-agent workflow on the same workload with the same agents (3× claude-sonnet-4-6). Every operation must edit one shared registry function. The numbers below are the mean of 10 independent runs

• benchmark/project_template_2/ — 90 operations, 9 modules

  	MAK	Git worktrees
  Avg. Tokens	18,339	23,760
  Avg. Time	226.5s	99.5s
  Avg. Accuracy	94% (253.1/270)	93% (251.6/270)
  Avg. Merge conflicts	0	2

MAK spends 23% fewer tokens and hits zero merge conflicts by construction. It also has a slight edge in accuracy.

More statistics

Both sides got a few of the harder algorithms wrong, but the worktree side additionally resulted in 2 merge conflicts.

MAK is slower than traditional worktree based operations because every task contends on that one symbol, so MAK serializes those writes while the worktrees edit in parallel and reconcile afterward: the trade is correctness by construction and token efficiency for execution time on a deliberately maximally-contended workload.

Run it yourself (all targets) with

python3 benchmark/run_benchmark.py --mode real \
  --models anthropic:claude-sonnet-5 anthropic:claude-sonnet-5 anthropic:claude-sonnet-5

Contribute

CONTRIBUTING.md is the full guide — architecture, every subsystem in depth, setup, the quality gates, coding standards, and where to help.

Everyone participating in this project is expected to follow the Code of Conduct.

License

MIT © 2026 Seungjoon Cha