[ 00_mlx_code ]
✔ Git isn't just a backup. It's a state machine.
✔ Git commits store file changes together with the conversation that produced them.
✔ Parallel worktrees host multiple isolated agents concurrently.
✔ Agents can spawn sub-agents recursively.
[ 01_cli_demo ]
[ 02_why_git ]
| Agent | Git | What It Enables |
|---|---|---|
| Execution step changes files | commit | Inspect changes cleanly with git diff |
| Alternative approach | branch | Explore paths non-destructively |
| Isolated agent sandbox | worktree | Keep your active checkout clean and safe |
| Resuming from a past session | checkout | Rewind agent to any snapshot state |
Most agents treat version control as an afterthought.
mlx-code maps the reasoning loop directly onto Git mechanisms. Your complete agent state history lives inside git commit
history rather than an opaque database.
[ 03_primitives ]
Fork from any checkpoint
A branch opens a fresh interactive tab in an isolated worktree. Test divergent code designs securely without abandoning your active checkout.
/branch --rev 2 make it use httpx instead
Resume from anywhere
Every file-changing step is snapshot-committed with the chat/execution history. Rewind cleanly to any checkpoints.
mlc --resume abc1234
Switch configs on the fly
Swap agent configurations mid-session between planner, coder, and reviewer roles without losing your active context.
/clear --config reviewer.yaml
Concurrent multi-agent
Run multiple agents concurrently inside one batch step. Share your unified memory architecture compute pools dynamically.
mlc --engine batch
[ 04_architecture ]
Worktrees:
main ──●──●──●──●──●──●──●──●──●──●──●──●──●──●──────► Node = git commit + chat history
│ │
│ └── branch-1 ──●──●──●
│ │ ┌────────────┐
│ └─┤ branch-1-0 ├──●──●
│ └─────┬──────┘
└── branch-0 ──●──●──● │
│
Tabs: ├────────────► Tab = git branch + Agent
│
┌──────────────────────────────────────────────┼─────────┐
│ TUI tabs │ │
│ ┌──────┐ ┌──────────┐ ┌──────────┐ ┌─────┴──────┐ │
│ │ main │ │ branch-0 │ │ branch-1 │ │ branch-1-0 │ │
│ └──────┘ └────┬─────┘ └──────────┘ └────────────┘ │
└─────────────────┼──────────────────────────────────────┘
│
Agents: ├──────────────────────────────────────► Each tab runs its own Agent
│
┌────┴─────────────────────────────────────┐
│ Agent │
│ ┌────────────────┐ ┌────────────────┐ │
│ │ API: │ │ Tools: │ │
│ │ Local (mlx-lm) │ │ Read Write │ │
│ │ Gemini │ │ Edit Bash │ │
│ │ Claude │ │ Grep Find │ │
│ │ Codex │ │ Ls Skill │ │
│ │ DeepSeek │ │ Agent ─────────┼──┼─► Recursively spawns sub-Agents
│ └────────────────┘ └────────────────┘ │
│ Git worktree │
│ (isolation + session state) │
└──────────────────────────────────────────┘
[ 05_library_api ]
Use as a Library
Construct custom workflow pipelines, run programmatic background review checks, or coordinate distributed multi-agent workflows natively on your Mac.
from mlx_code.repl import Agent
from mlx_code.tools import ReadTool, WriteTool, EditTool
agent = Agent(api='claude', tool_names=['Read', 'Write', 'Edit'])
result = await agent.run('refactor utils.py to use dataclasses')
[ 06_user_manual ]
slash commands
/branch [--rev N]Fork tab from checkpoint
/diff [--all]Review worktree changes
/clear [--config F]Clear / reset session
/history [--raw]Show chat log
/toolsList active tools
!commandRun a shell command
$commandRun an interactive command
keyboard shortcuts
Ctrl-1 … Ctrl-9Jump directly to N-th tab
Ctrl-, / Ctrl-.Cycle adjacent tabs
EnterSubmit
Ctrl-JInsert newline
Ctrl-RRecall last prompt
Ctrl-CClear input or abort agent
Ctrl-DClose branch tab, or exit app