mado窓

Every part of the harness, and when it lands.

mado's plan has 31 surfaces, the parts every coding-agent harness is made of. For each one: what it is, what the first release brings and what of that already works, and what comes after the launch. As of 1 November 2026; when the plan changes, this page does too.

  1. Todayin the repository

    A working agent with seven tools, skills and compaction, on any model with your key, and the profiler: a line under every answer, /profile, mado profile.

  2. First releaseDecember 2026

    The window as one bar per slice, the TUI finished (search, approval box, session picker), the measured benchmark, signed binaries.

  3. v0.2.xright after

    Rollback, /diff /review /commit, MCP with OAuth, subagents with plan mode, the other permission modes.

  4. v0.3testability

    Comparing configurations over your own sessions, memory evals, local models, --json-schema.

  5. v0.4opening

    The event format as a public contract, mado proxy and more adapters, a server with mado attach and ACP.

  6. Laterif it earns it

    Deploy, LSP, taint tracking, native Windows, a phone client.

surface
first release · December 2026
works todaywith the release
after the launch

The core

8 surfaces
01

Canonical messages

One internal form of the conversation, the same for every provider: messages, blocks, usage.

first release
  • Works today: Switch model or provider mid-session; a reply goes back to its provider byte for byte
  • Works today: The log keeps bytes and blocks; "not reported" and zero are different facts, even on disk
  • Works today: Every reply records who gave it: provider, model asked and answering, request id, timings
  • With the release: A transcript line says when a switch loses something or another model answers
after the launch
  • v0.2.xServer tool results (web search, web fetch) as typed blocks, with counts, bytes and domains
  • Reasoning of the previous model passed as text on a provider switch, once its cost is measured
02

Provider transport

How mado talks to each provider over the wire, with cache, timings and errors recorded.

first release
  • Works today: Anthropic Messages API in full with count_tokens; Chat Completions via base_url
  • Works today: Anthropic cache always on, with a cache_ttl key (auto, 5m, 1h); positions logged
  • Works today: Each request logs hash, byte length and timings; a retry resends the same bytes
  • With the release: OpenAI Responses API, Claude cache via OpenRouter, provider errors in four categories
after the launch
  • Explicit cache breakpoints on OpenAI Responses
03

Events

Everything that happens in a session is a numbered event that every client reads.

first release
  • Works today: Every action in a session is a numbered event; the database, TUI and -p read the same ones
  • Works today: A durable event is logged before anyone sees it; a slow subscriber loses deltas, never those
  • Works today: Provider refusals (402, 403) end a run as provider_refused, not as a config error
  • With the release: Versioned event format with a docs page of types and fields; dropped deltas counted in logs
after the launch
  • v0.4Event format as a public contract, with backward compatibility
04

Session store

All sessions of all projects in one local database, nothing written in the project.

first release
  • Works today: Every session of every project lives in one mado.db; nothing is written in the project
  • Works today: A crash loses nothing, a power cut at most the last reply; a started tool never reruns
  • Works today: The database is versioned and migrates itself; one newer than the binary is refused
  • With the release: Several instances share the database; sessions export; a command prunes and compacts it
after the launch
  • Automatic retention, with a config key
  • mado import brings an exported session back into the database
05

Workspace

The layer between tools and files: your repo locally, a container when deployed.

first release
  • Works today: Tools touch files only through the Workspace, confined to the project (.., symlinks)
  • With the release: Reading outside the project needs your yes; writing outside is not possible
  • With the release: bash runs in the project folder with your environment minus mado's API keys
  • With the release: Tools declare only the operations they use; make lint fails if one uses os for files
after the launch
  • Extra directories readable without asking, from config or a command
  • laterWorkspace in a container or on another machine
06

Agent loop

The cycle that calls the model, runs tools and decides when a run ends.

first release
  • Works today: A run is a sequence of turns and ends with a typed reason; retryable errors retry up to 3 times
  • Works today: Truncated replies run no tools; unknown tools and bad arguments return as invalid calls
  • Works today: read, list, grep, fetch run in parallel, up to 8; bash, write, edit in sequence
  • With the release: Esc interrupts, Enter steers a running run, a loop detector and max_turns (default 100)
after the launch
  • strict schemas on the wire where the provider supports them
  • Tools that start while the response stream is still open
07

Configuration

The user's settings: where they live, which value wins and how to change them.

first release
  • Works today: One ~/.config/mado/config.json: default < file < flag, and an unknown key is an error
  • Works today: API keys from the environment or saved with /login; the redactor knows saved keys
  • Works today: Provider types anthropic, openai, compatible, local; /provider add in the TUI
  • Works today: /model, /effort and /set <key> <value> save only the key they change
after the launch
  • An API key read from a command, such as op read
08

Logs

The program's diagnostics, kept apart from the session events.

first release
  • Works today: Logs go to a file or stderr, never stdout; formats pretty, text, json
  • Works today: Logs hold metadata only, never the content of requests or responses
  • With the release: Every line carries the session id; the file rotates past 10 MB, keeping three
after the launch

Nothing planned yet.

The agent at work

7 surfaces
09

Models and providers

Which models you can reach, how you pick and switch them, and with how much reasoning.

first release
  • Works today: Anthropic and OpenAI with your own API key, no subscription
  • Works today: /model, /effort, /models with a live list; /route picks an OpenRouter endpoint
  • With the release: Context window from the provider API, the catalog or config; never an invented default
  • With the release: Tested live: OpenRouter, DeepSeek, llama-server, Ollama, LM Studio, plus a measured local pick
after the launch

Nothing planned yet.

10

Tools

The actions the model can ask for: read, write, edit, run, search and reach the web.

first release
  • Works today: Seven tools: read, list, grep, bash, write, edit, fetch
  • Works today: Long bash and grep output arrives as head and tail; the full text is read back with read
  • Works today: fetch turns a page into markdown for every provider and blocks private network addresses
  • With the release: edit all or nothing, write only after read; a re-read returns a stub or what changed
after the launch
  • v0.2.xAnthropic web search and web fetch, with typed results
  • read for images and bash in the background with output by reference
  • Active tools set in config, a patch-style edit, a notice when a read file changes on disk
11

Sessions and resume

Finding a conversation again and resuming it.

first release
  • Works today: Every session is stored with its folder, last activity and title; an empty one leaves nothing
  • Works today: Resuming replays the log; a tool with no result is marked interrupted and never rerun
  • Works today: mado -c resumes the last session of the folder, mado -r a session by its id
  • With the release: A session picker for mado -r and /resume; /rename sets a title by hand
after the launch
  • Fork from a past point into a child session, with the profiler showing both branches
12

Hooks

Where your code watches or changes what the agent does: before a tool, at turn end, at start.

first release
  • Works today: BeforeTool hooks answer allow, deny, modify or ask; they chain, and a failing hook means deny
  • Works today: Subscribe gives a channel of events that the loop never waits for
  • With the release: Tool inputs use Claude Code's field names, such as file_path, offset, command
  • With the release: Context a hook adds enters the window as an event with its source, and the profiler counts it
after the launch
  • v0.2.xShell hooks in Claude Code's format on seven events, so existing hooks carry over
13

Permissions

Who decides whether an action of the model runs: you, a rule, another model, or nobody.

first release
  • Works today: write, edit, bash and fetch ask before they run; reads don't; --yolo skips asking
  • Works today: "Always" saves the rule for the current folder in your global config, never in the repo
  • With the release: Answer no with a reason; rules match command prefixes, files, folders and domains
  • With the release: A pending approval survives a restart and is logged; the README lists what bash can bypass
after the launch
  • v0.2.xAccept-edits and auto (with a classifier) modes, switched with Shift+Tab
  • v0.2.xProject rules and hooks in .mado/, trusted by file hash
  • Hooks and skills from the repo's .claude/, with the same trust
14

Sandbox

An operating-system or container boundary on what tools can touch, independent of approvals.

first release
  • With the release: The README states the limits of bash and advises a container or VM for real isolation
  • With the release: bash hands the Workspace a command as data and never builds the process itself
after the launch

Nothing planned yet.

31

Secrets

Keeping keys and credentials out of the context, the logs and the saved sessions.

first release
  • Works today: A redactor on tool output, before the window, finds known key formats and secret env values
  • Works today: A secret becomes a stable placeholder; the value never reaches mado.db, logs or export
  • Works today: A call carrying a redacted placeholder is refused, so it is never written in place of the value
  • Works today: Third-party secrets stay in the command environment; the README says redaction is best effort
after the launch
  • Your own redaction rules in config, and files never read without asking, like .env

The window

6 surfaces
15

Instruction files and system prompt

The text that enters the context window before the user's first message.

first release
  • Works today: Fixed system from the first message: prompt, environment and AGENTS.md, each a named section
  • Works today: Only AGENTS.md is read, stacked from the git root down, and loaded without a trust prompt
  • Works today: Prompt under 1,000 tokens, same for every model; ~/.config/mado/SYSTEM.md replaces it
  • With the release: Changed or new instruction files enter in append, with a line naming the file and its tokens
after the launch

Nothing planned yet.

16

Skills

Instructions for a task, kept in a SKILL.md file and loaded by the model or by the user.

first release
  • Works today: Agent Skills work as written, found in .agents/skills/ of the project and home
  • Works today: Only the catalog is in the system; the skill tool loads a body once, intact after compaction
  • Works today: /name text in the TUI and -p; skills load without trust and never change permissions
  • With the release: A skill installed mid-session enters in append; the profiler counts each skill by name
after the launch
  • Skills from .claude/skills/ for users coming from Claude Code
17

Cost and profiler

What each turn costs in tokens, cache, money and time, and why.

first release
  • Works today: A line under every answer: what entered the window, the cache, the output, time and cost
  • Works today: A cache miss gets a line with its cause, read from the request, or says unknown
  • Works today: /profile and mado profile: the same table, mado's RAM; mado profile a b compares two
  • Works today: mado profile --json and mado export for scripts; the prefix counted with count_tokens
  • With the release: The window as one bar per slice, prices from models.dev, time to first token on every turn
after the launch
  • mado stats: a summary across sessions by day, project and model
  • mado profile --html: one offline file with the data embedded
  • /export in the TUI and the conversation as Markdown
18

Compaction

What the harness does when the context window fills up.

first release
  • Works today: Compacts on a full window or at a threshold, or with /compact [instructions]
  • Works today: Summary reuses the same prefix so cache holds; each compaction is a logged event with a cell
  • Works today: A failed summary falls back to a recovery without an LLM; COMPACT.md replaces the prompt
  • With the release: A no-LLM check of the summary against the log, and the compaction diff in /profile
after the launch
  • Undo a compaction with a fork from before it
  • v0.2.xExternal compactor as a user command, with shell hooks
  • Keep the last turns verbatim, once measured with evals
19

Memory

What the agent remembers from one session to the next.

first release

Nothing: all of it comes after the launch.

after the launch
  • Search past sessions of the folder, stored in mado.db
  • Notes written by the model on request, loaded as a system section with their weight
  • Measure how much context memory costs, and whether it is needed
30

Adapters for other harnesses

Reading the sessions of another harness from its logs and showing them in the profiler.

first release
  • Works today: mado profile --from claude-code [session] reads the main and the subagent transcripts
  • Works today: The same table as mado profile, with cost recalculated from mado's model catalog
  • Works today: What the transcript lacks is n/a, never an invented number
  • With the release: Read-only: no import into mado.db, and the README says what can't be seen from outside
after the launch
  • v0.4Adapters for Pi, then Codex and OpenCode
  • mado import to bring other sessions into mado.db
  • v0.4mado proxy: the traffic of any harness as mado events

The interfaces

3 surfaces
20

Headless mode

Run mado from scripts or CI: one prompt in, one result out, as text or JSON.

first release
  • Works today: mado -p "..." runs a prompt with no TUI, on the same agent and events as the TUI
  • With the release: Only the final answer on stdout, nothing there if the run fails, stdin read as <stdin>
  • With the release: --mode json for one final object, --mode jsonl for the event stream
  • With the release: Exit codes 0 to 5; with nobody to approve, a run suspends or denies
after the launch
  • v0.3--json-schema <file> for structured output
  • v0.4Answer a suspended run without the TUI, through the server
  • Permission rules from the command line
21

The TUI

A fullscreen terminal client that shows the session as it runs and reads history from the log.

first release
  • Works today: Fullscreen view paged from the log, with the context and the session's cost in the footer
  • Works today: Markdown with highlighted code, tool cells with word-level diffs, Ctrl+O to expand
  • Works today: Input with @file and its weight, history from the log, Ctrl+G to edit in your editor
  • Works today: /profile as a layer over the transcript, updated while a run goes
  • With the release: The approval box, search, grouped reads, verbosity levels, mouse selection
after the launch
  • A fixed window panel on wide terminals
  • Images pasted from the clipboard or dragged in
  • Custom themes and remappable keys
22

Commands and flags

Slash commands, subcommands and flags to drive mado from the TUI, scripts and CI.

first release
  • Works today: /model, /effort, /provider, /help; /model warns if the window is too small
  • Works today: / lists the commands and skills, then each command's choices as you type
  • Works today: mado profile, mado profile a b, --json and mado export from the command line
  • With the release: Prompt templates as your own commands, /new, /permissions, /init, /copy, !command
  • With the release: mado sessions, models, trust, doctor; flags --permissions, --config, --max-cost
after the launch
  • mado stats: a summary across sessions, with --since and --by
  • /export in the TUI
  • Commands from .claude/commands/ in the repo

Around the code

2 surfaces
23

Git

How the model works with git through bash, and the guards against destructive commands.

first release
  • Works today: Read-only git commands pass in ask mode; options that run code or retarget the repo still ask
  • Works today: Commands run with no pager, no password prompt and no hidden bare repos
  • Works today: Destructive git is never covered by a saved rule; git status is checked first
  • With the release: No attribution in commits or PRs, and a short git rules section in the system prompt
after the launch
  • v0.2.x/diff with session, tree and branch views, /review and /commit templates
  • mado -w [name]: a worktree outside the repo, removed on exit only if clean
  • A GitHub Action on top of mado -p
24

Rollback

Go back on the conversation, the files or both, without losing the abandoned branch.

first release

Nothing: all of it comes after the launch.

after the launch
  • v0.2.xRewind conversation, files or both with Esc Esc or /rewind; the old branch is kept
  • v0.2.xFile restore is all or nothing and checked by hash; edit and write save the file first
  • laterRedo and switching between branches, and /fork from any point

Extension and orchestration

3 surfaces
25

MCP

Use tools and prompts from external MCP servers, with their context cost measured per server.

first release

Nothing: all of it comes after the launch.

after the launch
  • v0.2.xMCP client for stdio and HTTP servers with OAuth, reading mcpServers and .mcp.json
  • v0.2.xTool definitions deferred or searched, and their cost shown per server in /profile
  • v0.2.xEvery MCP call asks first, and changed server definitions are shown as a diff before use
26

Subagents and plan mode

Delegate work to child sessions that share the parent's prefix, with their cost counted on the family.

first release

Nothing: all of it comes after the launch.

after the launch
  • v0.2.xagent tool: child sessions with the parent's exact prefix, permissions and cost totals
  • v0.2.xPlan mode and a /review that runs in a fresh child context
  • Background children, resumable children and agent types from files
27

Server and clients

How clients reach a session: the TUI, scripts, a second mado watching, and later a server.

first release
  • Works today: One owner per session; a second mado follows the live log read-only
  • Works today: The TUI and -p use only the public client.Session interface
  • With the release: Remote use is SSH to the machine that runs mado: no server and no daemon
after the launch
  • v0.4A server on a Unix socket: a detached client cancels nothing, and clients resume from any Seq
  • v0.4mado attach for the TUI over the socket, and mado acp for editors
  • laterA phone, web or app client on the same protocol, if it earns it

Quality and distribution

2 surfaces
28

Testing and evals

Test the loop and prompt cache from recorded sessions, compare configurations, and benchmark against others.

first release
  • With the release: Loop tests replay recorded sessions and fail on any change to system, tools or messages
  • With the release: CI runs without API keys; TUI golden tests and a memory-growth check run on every PR
  • With the release: mado eval: paired A/B runs of two configs with repeats, success interval and cost
  • With the release: Public benchmark against other harnesses: tokens from a proxy, PSS memory and startup
after the launch
  • v0.3Compare configurations as a profiler view over your own sessions
  • v0.3Memory evals, local-model evals and --json-schema
29

Install and distribution

Signed binaries, upgrade checks, supported platforms, license and privacy of the mado install.

first release
  • With the release: Signed release binaries, a Homebrew cask and go install, with verification steps
  • With the release: mado upgrade verifies signature and checksum; the default only prints a notice
  • With the release: First run finds API keys and local servers, then a provider and model picker
  • With the release: macOS and Linux, Windows via WSL2; AGPL-3.0 or commercial license; no telemetry
after the launch
  • homebrew-core, once the project meets its criteria
  • laterNative Windows
  • deb, rpm, AUR and nix packages

First release: December 2026.

Signed binaries for macOS and Linux, and the benchmark with them.

Follow the release