Introduction

meka is a general-purpose AI agent harness, the layer that wraps a large language model with everything it needs to act as an autonomous agent: a tool set, working memory, context management, persistent sessions, a permission model, and several ways to drive it. You bring a model (Claude or OpenAI, API key or subscription); meka turns it into an agent that can read and edit files, run commands, fetch web pages, call MCP servers, and delegate to sub-agents to get real work done.

The name reflects the design: the model is the pilot, and meka is the mech it operates. The pilot (the model and the backend serving it) is swappable; the harness around it stays the same.

> find all Rust files in this project and count the lines of code

You describe the goal in natural language and the agent decides which tools to use to reach it.

Use it however you work

The same agent core is exposed through four front-ends:

• Interactive: a permission-gated screen for conversational work in your terminal
• One-shot: meka --oneshot -p "..." for scripts, pipelines, and CI
• Editor (ACP): run as an Agent Client Protocol agent inside editors like Zed
• HTTP service: meka serve exposes the agent over HTTP+JSON for bots, web UIs, and other programs

What the harness provides

• Built-in tools: file read/write/edit, glob search, regex content search (ripgrep), web fetch and shell command execution
• Pluggable backends: anthropic-messages, claude-subscription, openai-chat-completions, openai-responses, chatgpt-subscription, and any endpoint serving one of those protocols
• MCP support: extend the agent with tools, resources, and prompts from external MCP servers
• Permission model: control what the agent can do (none/read/workspace/unrestricted), switchable mid-session
• Sessions: conversations persisted in SQLite; resume, export, or compact any session
• Working memory: a session-scoped scratchpad for intermediate results that stays out of the context window
• Sub-agents: delegate research or analysis to sub-agents that can orchestrate their own sub-agent teams and be run at a restricted permission level
• Skills: load reusable, user-authored instruction packages on demand
• Context management: automatic compaction keeps long sessions under the model’s context limit
• Extended thinking: anthropic-messages and claude-subscription support extended thinking for complex reasoning

How it works

1. You give meka a goal in natural language, interactively, one-shot, over ACP, or over HTTP.
2. meka sends it to the configured model along with a system prompt, the tool schemas, and a context block describing the current permission level, working directory, tools, and skills.
3. The model decides which tools to call (if any) and returns text and/or tool calls.
4. meka enforces the current permission level, executes the tool calls, and feeds the results back to the model.
5. The loop repeats until the model is done; the final response is returned (streamed as Markdown in the terminal).

Installation

meka is written in Rust and builds as a single binary.

Pre-built binaries

Download the latest release for your platform from the GitHub Releases page.

Extract the binary and place it somewhere on your $PATH:

# Linux/macOS
tar -xzf meka-*.tar.gz
cp meka ~/.local/bin/

mekabox

scripts/mekabox runs the meka installed on the host inside a stock archlinux:latest container, with no image of its own to build or pull: the binary is bind-mounted in, ~/.config/meka read-only, and ~/.local/share/meka writable, since that is where meka.db keeps every session and credential. The agent starts at unrestricted with instructions saying it may install whatever the task needs, and that it must not create memories or scheduled jobs unless asked, since the store it writes is the host’s. It is the answer to “let it do anything, just not to my machine”: the container is disposable and the host config cannot be written. The store is the one host file the box shares, and nothing sandboxes a command at unrestricted, so a command in the box can read every credential in it: the boundary is around your filesystem, not your accounts. It picks podman over docker when both are present.

Cargo install

If you have Rust installed, you can install meka directly from the Git repository:

cargo install --locked --git https://github.com/k4yt3x/meka.git

This builds the latest version from source and installs it to ~/.cargo/bin/.

Building from source

Prerequisites

• Rust 1.95 or newer, the version Cargo.toml declares
• A C compiler (for the bundled SQLite)

Build

git clone https://github.com/k4yt3x/meka.git
cd meka
cargo build --release

The binary will be at target/release/meka. Copy it somewhere on your $PATH:

cp target/release/meka ~/.local/bin/

Verify

meka --version
meka --help

Quick start

1. Add an account and a profile

Before the first run, configure an account and a profile on it. meka account add runs the right credential flow (OAuth login or API-key prompt) and writes the account to ~/.config/meka/config.toml; meka profile add names the model to ask it for:

# Claude Code subscription (OAuth)
meka account add claude --backend claude-subscription
meka profile add work --account claude --model claude-opus-5-5

# or a Claude API key
meka account add anthropic --backend anthropic-messages
meka profile add work --account anthropic --model claude-opus-5-5

# or OpenAI
meka account add openai --backend openai-chat-completions
meka profile add work --account openai --model gpt-6-astra

account add prompts for the backend you omit and acquires the secret (browser OAuth for claude-subscription / chatgpt-subscription, an API-key prompt otherwise), keeping it in the store. profile add prompts for the account and model you omit. A sole profile is the default; add more later and switch with meka profile use <name> or the per-run --profile <name> flag.

If you launch meka with no profile configured, it errors and tells you to run meka account add and meka profile add. See Configuration for all options and the full meka account / meka profile reference.

2. Start using meka

After setup, run meka. The screen opens on the conversation, with a composer at the bottom, a bar down its left edge in the permission level’s color, and a status row under it that opens with the level: read by default. The agent can read files, search, and run shell commands in a sandbox that blocks writes. It cannot modify your files.

3. Ask it something

> what files are in the current directory?

The agent will use the file_find tool to list files and describe them.

4. Enable the workspace level

Press Shift+Tab to cycle the permission to workspace, where the agent may write inside your working directory. Now it can modify files too, and its shell may write inside the same boundary:

> create a file called hello.txt with the text "hello world"

5. One-shot mode

For quick tasks without opening the screen:

meka --oneshot -p "what is my current working directory?"

The process exits after the agent responds. Without --oneshot the same prompt runs as the first turn and then drops you into the interactive shell.

6. Continue a previous session

To pick up where you left off, continue the last session:

meka -c

Or resume a specific session by its id:

meka -r 550e8400-e29b-41d4-a716-446655440000

See Sessions for more details.

Upgrading

Most upgrades are a binary swap: stop every meka process on the store (a meka serve unit, an open screen, an editor’s meka acp), replace the executable, and carry on. An upgrade that changes the store’s schema migrates it on the first open, and refuses while another meka process of 0.87 or later has the store open, since that process would go on writing the shape the migration replaced; an older process goes unseen, which is why it is stopped first. This page covers the upgrades that are more than a swap.

Copying a store

The store under MEKA_DATA_DIR runs in WAL mode, so the most recent writes, including a schema migration, can sit in meka.db-wal beside meka.db until SQLite checkpoints them. A copy that takes meka.db alone can therefore carry a schema version its tables have not caught up with. meka checks for that on open and refuses the store rather than running against it. Copy the -wal and -shm companions with the file.

0.87 to 0.88

Nothing in config.toml is renamed, but display.status_row and display.turn_end_summary refuse a fact listed twice: name it once. The store moves forward on its first open, and 0.87 refuses a store 0.88 has opened; downgrading means restoring the backup the upgrade took. The conversions need nothing from you:

• Every turn records the permission level it ran under. A turn written before takes the level the first of its own messages that names one told the model, its opening in a turn meka wrote; one where none does takes its session’s level, or read on a session at a level meka does not know.
• A tool result written before records nothing of how the screen draws it, so a resumed session draws those calls as 0.87 did: an edit’s diff from its arguments, a write with none, and a failed command as failed, its exit code in its output.
• A compaction written before records no checkpoint turn, so its row opens to the memories its checkpoint wrote, by name, and its summary. The summary is read out of the message the compaction wrote, up to the first section meka adds after it, so a summary that held one of those headings itself shows only what came before it.

Session archives are format_version 21. A 0.87 archive imports as it is, its turns and compactions converted the same way.

An ACP client that did not advertise session.compaction is shown each compaction as a tool_call of kind think, closed under the sentence for what set it going, where 0.87 told it in a [meka] chunk or a notice. A client that matched those for a compaction should match the card, or advertise the capability and read compaction_update.

0.86 to 0.87

Nothing in config.toml is renamed. The store moves forward on its first open, and 0.86 refuses a store 0.87 has opened; downgrading means restoring the backup the upgrade took. The conversions need nothing from you:

• A cron job written before names no time zone and keeps running in the machine’s.
• Reasoning a chatgpt-subscription profile sealed names that endpoint, and is sent back to it alone; reasoning from anywhere else names none and is sent nowhere. Naming it reads config.toml’s profiles, so an upgrade of a store holding sealed reasoning refuses while the file cannot be read.
• The copies of the recent turns earlier compactions kept are linked to the rows they copy, so history shows each such turn once; a copy whose row a turn sweep has already taken, or that no row matches, stays in history as the record of what it says.
• The session search index is rebuilt once.

Session archives are format_version 18. A 0.86 archive imports as it is: its kept copies are linked the same way, and its sealed reasoning names no endpoint, since the archive does not say which.

Two environment values, a handful of flags, two OpenAI request shapes, two HTTP shapes, an ACP field and a tool’s argument types are refused or read differently.

openai-responses asks for encrypted reasoning, a reasoning summary and a cache key. Every request carries include: ["reasoning.encrypted_content"], reasoning.summary and a prompt_cache_key naming the session, as OpenAI’s own client sends them. A model that does not reason refuses the first two, on OpenAI’s own API as well (gpt-4.1, gpt-4o): set encrypted_reasoning = false and reasoning_summary = false on its profile (meka profile set). An endpoint behind base_url that refuses one is answered by turning that one off the same way, and prompt_cache_key = false in the account’s table of config.toml.

openai-chat-completions asks for usage on every streamed request (stream_options.include_usage), where it asked only some endpoints. An endpoint that refuses the field is answered by stream_usage = false in the account’s table of config.toml.

A relative MEKA_CONFIG_DIR or MEKA_DATA_DIR is refused. meka stops at startup naming the variable, where it used to fall back to the platform directory with a warning and so ran against the real store. Set each to an absolute path.

meka serve and meka acp refuse the flags that belong to a run. Both refuse --prompt, --skill and --oneshot, and meka serve refuses the directory flags too, where they were silently ignored. Remove them from the unit file or the editor’s agent command.

meka profile add and meka profile set refuse a flag the account’s backend never sends, as meka account add already did, where they wrote a key nothing reads. Drop the flag; nothing is written when it is refused.

Feed event ids start from the clock. Each meka serve process issues ids above the clock’s microseconds at its start, so a Last-Event-ID saved before a restart is read as a gap (a feed.gap with no count) rather than as a position in the new process’s feed. A client that handles feed.gap by re-reading GET /messages needs no change; one that compared ids against small numbers should treat them as opaque, increasing integers.

GET /v1/instructions shows path and source to a token with config:r or config:w alone. A token with sessions:r still reads the text. Grant config:r to a client that needs to know where the file is.

ACP: a prompt response’s usage is the turn’s, as the protocol defines it, where it was the session’s running total. An editor that showed it as the session’s cost should sum it across turns.

A tool’s boolean, number and object arguments are read strictly. A boolean is true or false, a number an integer (2.0 counts as 2, as JSON Schema has it), an object an object (web_fetch’s headers an object of strings), or the field is left out. Anything else, a string such as "true" or "3", a fraction, a negative where a count is asked for, or an object spelled as a JSON string, is refused naming the field, so a model corrects the call rather than having it read as false, as the default or as absent. memory_search read a quoted limit as the number it spelled, and now refuses it.

0.85 to 0.86

Nothing is renamed and no key is refused; one archive version moves.

Session archives are format_version 17. A 0.85 archive imports as it is; a 0.86 archive can record where a session stopped sending Claude its earlier thinking, which 0.85 refuses to read by its version.

0.84 to 0.85

One config key is retired, and the store gains a table and a column, which the first run adds on its own; the HTTP API grows a surface and four of its shapes change, a start refuses a profile that cannot run, two shell commands refuse where they warned, and an ACP client sees two things differently.

The installation is managed over HTTP, under two new scopes. /v1/accounts, /v1/profiles, /v1/mcp and PUT /v1/instructions do what meka account, meka profile, meka mcp and the instructions file do in a shell, and a change made through them is served at once; an edit made in a shell is served by the next of them, or by POST /v1/config/reload. They sit behind config:r and config:w, which no existing token holds: grant them to the token that administers the installation and to no other, since config:w is shell on the host. GET /v1/config names where the installation is (config_path, data_dir), when config.toml was last read and written, and config_changed, whether an edit made in a shell awaits POST /v1/config/reload, which reads the file again; every write of the server’s own ends with the same whole read. The server now starts with no profile configured, so an installation can be set up over the API; the refusal moved to the session that names none, and over HTTP it names POST /v1/accounts and POST /v1/profiles rather than the shell’s commands. Adding a second profile names the one that was alone as default_profile, in a shell as over HTTP, where it used to leave the installation with no default; and removing the default while two or more profiles would remain is refused, in a shell as over HTTP, where meka profile remove used to warn and unset it. Point default_profile elsewhere first, with meka profile use or PATCH /v1/profiles/{name} and "default": true. meka account add refuses --client-id and --oauth-token-url on a backend that never reads them, where it dropped them with a warning, as it already refused --interleaved-thinking.

Every profile must be able to run. A start, a reload and every write of the installation refuse a config.toml holding a profile whose account is not configured, that names no model, or whose max_output_tokens does not exceed its thinking budget, where only the default was held to it. The refusal names the profile; repair it with meka profile set or remove it.

An MCP credential is bound to the endpoint it was stored for. A connect presents OAuth tokens to the exact url they were issued for alone, and a bearer or a client secret to the scheme, host and port of the url it was stored with, so a credential never follows a server to another host. The first run binds every credential already stored to its server’s url as config.toml states it then, which is where it has been presented all along, so nothing changes for a server that stays put; it stops, naming the file, while a credential is stored and config.toml cannot be read, and naming the server while a credential is stored for one whose url holds a ${VAR} the environment leaves unset, since a binding made from the literal would hold the credential for a URL nothing reaches. The binding is made from that first command’s environment: a variable it holds differently from the server’s own runs, or a ${VAR:-default} it leaves to its default, binds the credential where its expansion points, and the server’s connect then refuses it, naming the origin it was stored for. Run the first command after the upgrade with the environment the server runs under. Storing a secret for such a server, with meka mcp add, meka mcp login --auth-token-stdin or --client-secret-stdin, or over the API, is refused the same way where the variable is unset. A server whose url moves to another host afterwards fails to connect, saying so, until it is logged in again or its secret stored again. meka mcp get and GET /v1/mcp/{name} list as credentials the kinds presented to the url, and the kinds held for another endpoint under credentials_for_another_endpoint, with the origin each was stored for; credential_origin and credential_origin_matches_url are gone.

resource is retired from [mcp.servers.auth]. A client_credentials or client_credentials_jwt token request names the server’s own url as its resource, as the MCP authorization spec requires, so the key would only restate it or contradict it; a file that still carries it is refused at startup, naming the key and its line. Delete the line.

GET /v1/mcp is an object, and a server’s auth is the block. GET /v1/mcp answers {"servers": [...]}, with orphaned_credentials beside it when a credential is stored under a name no entry claims; a client that read the bare list reads servers. GET /v1/mcp/{name} and meka mcp get --format json carry every key the entry states, and auth is the block as written, {"type": "oauth", ...}, where it was the type string alone; required and deferral are what the server runs under, and inherited names those the entry leaves to [mcp].

OpenAPI: the responses body’s outcome schema is ResponseOutcome. It takes the three answers an elicitation takes (accept, decline, cancel) beside the four an approval takes. A client generated from the spec regenerates; one that sends the approval answers is unaffected.

context.measured on the session feed. After every provider round, and after a compaction or rewind, the feed says what is in context (used, and window once known), the figure GET /v1/sessions/{id}/context answers with, so a client that polled it for a gauge can follow the event instead. A client that ignores events it does not know needs no change.

An ACP client’s gauge moves per round, and a background report is a notice. usage_update arrives after every provider round, and once on session/new, session/load, session/resume and session/fork with what the session’s row recorded, rather than at a turn’s end. Finished background work is no longer pushed as a user_message_chunk carrying the report the model read: a client that advertised session.notices gets a notice titled in the screen’s words, with the task’s label as its description and the tasks under _meta.background; one that did not gets the same words as a parenthesized agent_message_chunk, which is also what a session/load replays where the report landed. A client that matched on the [Background task header reads the notice or the chunk instead. A scheduled job’s prompt is still a user_message_chunk.

0.83 to 0.84

Nothing is renamed; one value is refused where it never applied, the store is migrated on first open, and one wire shape grows.

[shell].sandbox_backend takes this platform’s values only. A value from another platform was ignored on macOS and Windows; it is now refused: shell_execute at read fails and startup warns, naming the values this platform takes. Linux takes bubblewrap, bubblewrap-landlock and landlock, Windows takes appcontainer and restricted-token, and macOS takes none. A config.toml shared across machines leaves the key unset, or sets it per machine through MEKA_SANDBOX_BACKEND. Windows now chooses its backend by probe: a build without the AppContainer API, or whose API speaks schema 1.0, warns once at startup that the restricted token is in use and what it cannot hold; pinning sandbox_backend = "restricted-token" accepts that and silences the warning, as pinning landlock does on Linux, and on a schema 1.0 build pinning sandbox_backend = "appcontainer" takes the AppContainer with network = "host" held as remote.

A Windows 11 build with the process security environment API runs commands in an AppContainer. On 26H2, and on 24H2 and 25H2 from the August 2026 update as Microsoft lists them, read and workspace now confine a command through the OS’s own environment: meka’s config directory and store are unreadable, confine_reads and network hold for the shell as they do for the file tools, and no ACE is written to your directories. Four limits of the mechanism come with it: cd into a read-only directory fails (git’s -C and Python’s os.chdir included; the initial directory, PowerShell’s Set-Location and cd into a workspace directory work), msys2 bash.exe cannot start, a removable FAT32 volume and a mapped network drive are out of reach, and an app execution alias such as the Python install manager’s python.exe does not start, while the real executable runs by its path. Pin sandbox_backend = "restricted-token" to keep the previous mechanism. On both backends a confined command can no longer read or set the clipboard, drive other windows or inject input.

Every compaction records what it was. The boundary a compaction writes now carries what set it going (reactive, proactive, manual, requested, emergency or retention), which strategy wrote the summary, the memories the checkpoint wrote and whether the recent turns were kept, so the screen’s row, the editor’s entry and the HTTP marker say the same thing live and on a replay of the log. A boundary written before 0.84 recorded none of that, and nothing in the store says, so the migration gives every one of them the commonest case: an automatic compaction at the ceiling (reactive), written by the checkpoint, with no memories written and the recent turns kept. A resumed older session therefore replays each earlier compaction as Autocompacted the conversation after context usage crossed the ceiling., whatever set it going at the time.

Session archives are format_version 16. An archive written by 0.79 through 0.83 is brought forward on import, its boundaries given the same record.

context.compacted says more, and has company. The stream event and the compaction object on GET /messages carry trigger, memories_written and kept_recent beside source, replaced_count and generation; the event also names its compaction_id. context.compacting opens a compaction under that id before any request is made, and context.compaction_failed closes one that did not land. The one-shot JSON report lists the turn’s compactions under compactions.

An ACP client sees the compaction it asked to see. One that advertised session.compaction gets compaction_update, in_progress then completed with the summary, in place of the [meka] chunk; one that did not gets the advisory, a notice if it advertised session.notices and the chunk otherwise, now in the screen’s words (The agent compacted the conversation. rather than Compacted the conversation: 545 messages replaced by a summary (checkpoint, compaction 8)). A client matching on the old sentence should match on [meka] alone or advertise a capability.

0.82 to 0.83

Nothing is renamed and no key is refused; one thing changes what a memory does.

load decides how a memory reaches the context; priority is importance alone. A memory stored at priority 0 before 0.83 is migrated to load: inline, so what sat in every turn’s context stays there. A memory written from now on is index unless the write says inline or search, whatever its priority: memory_write’s load, meka memory add --load, or load on PUT /v1/memory/{name}. Every existing memory is marked verified as of its creation, since nothing has verified it since; memory_search’s unverified filter and --unverified count from there.

0.81 to 0.82

The Swagger UI is gone. /v1/docs answers 404 whatever [serve].docs says, and the key still serves /v1/openapi.json. To browse the API, import that URL into one of the tools the HTTP API page lists.

0.80 to 0.81

Two keys move to the section that governs them. config.toml refuses the old key, naming its line; move it.

A profile’s keys are ordered by how many backends read them. meka profile add and meka profile set write max_request_bytes after max_output_tokens and deferred_tools after vision, and the next write to a profile puts an existing one in that order. Nothing is renamed and no value changes.

0.78 to 0.79

Nothing is renamed and no key is refused; two things change what a running deployment does.

Every MCP connect opens with a protocol probe. A server that answers it is spoken to as MCP 2026-07-28; one that does not gets the initialize handshake it had. A stdio server from before the probe existed may swallow it and answer nothing afterwards, so such a server is given up to ten seconds, or half of [mcp].connect_timeout when that is less, on its first connect in a meka process before a fresh child gets initialize; the verdict is kept for the process, so later connects pay nothing. See Connection lifecycle.

Session archives are format_version 15. A 0.78 archive imports as it is; a 0.79 archive carries the allow-list keys on every sub-agent spec, which 0.78 refuses to read by its version.

0.77 to 0.78

A blocking POST /turn holds its turn. A request with stream: false whose client disconnects now stops the turn at its next round boundary once the connection has been gone for [serve] stream_reattach_grace, the way a dropped stream always did, and the turn ends with reason: "abandoned". Until 0.77 such a turn ran to its end and the client read the reply out of GET /messages. A client that cannot hold a connection for the length of a turn sends detach: true and reads the turn from the resource the 202 names, or follows the session feed; see Holding a turn. A feed subscriber counts as a listener, so a client that keeps the feed open is unaffected.

The message a turn opens with is on the feed as message.appended. A scheduled fire’s prompt and a background report that opened a turn used to reach the session feed as an info notice holding the text; they now arrive as message.appended, the message as GET /messages types it, under the turn’s id, and so does every other turn’s opening. A client that displayed those notices reads the scheduled and background_report blocks of the new event instead; a client that logs notices stops seeing prompt bodies in them. See the session feed.

A blocking POST /turn answers with the opening message first. messages begins with the user-role message the turn opened with, as the history reads it back, where it used to begin with the assistant’s first message. A client that read messages[0] as the reply filters by role.

Session archives are format_version 14. A 0.77 archive imports as it is; a 0.78 archive names why a canceled turn stopped and which fallback profile served a turn, which 0.77 refuses to read.

0.76 to 0.77

Nothing is renamed and no key is refused; three things change what a running deployment does.

Deferred tools are declared natively on the official endpoints. A profile on claude-subscription, chatgpt-subscription, or anthropic-messages and openai-responses without a base_url now declares every deferred tool from the first request with defer_loading, and a load no longer rewrites the prompt cache. Set deferred_tools = "append" on a profile to keep the 0.76 shape. A profile behind a base_url keeps append unless it states native.

The first request of every live session rewrites its prompt cache once. The tools array and the shape of a successful tool result both change, so a session resumed on 0.77 reads nothing back on its first request and everything from the second.

A claude-subscription session has no MCP meta-tools. The mcp_resource_* and mcp_prompt_* tools leave the request and the catalog on that backend, because its endpoint refuses their names; see Deferred tools. They are back the moment the session moves to another profile.

0.75 to 0.76

A sub-agent’s scope is three fields. agent_spawn’s writable_roots and readable_roots are gone. A call names working_directory, where the sub-agent works, and may add additional_workspace_directories, more of its workspace with the working directory’s rights, and additional_readable_directories, what it reads beyond its workspace. A call naming none of the three gives the sub-agent the parent’s whole scope, as before; a list needs working_directory beside it, and "." is the parent’s own directory. Stored specs are converted when the store is opened: the first writable root becomes the working directory and the rest the workspace list, and the readable roots become the readable list beside the directory the sub-agent was spawned in. A sub-agent that had only readable roots no longer follows the parent’s other directories. The common calls, before and after:

A list no longer runs the sub-agent at workspace on its own: it runs at the parent’s level unless permission lowers it, and a list beside unrestricted is refused. A permission above the parent’s is refused rather than clamped. The result of a spawn and of a follow-up opens with Agent:, Permission: and the scope the sub-agent holds, in the lines the environment block uses; a script that read agent: from the first line reads Agent:.

A sub-agent’s reads follow its spawn. [permissions].confine_reads governs root sessions alone. A sub-agent reads what its spawn call stated, or what its parent reads when it stated nothing, on every installation. A parent whose reads are not confined hands reads anywhere only by stating no scope.

Every surface says directory. One table of the renames:

What meka relays into a user message has its own block. An inbox item, a scheduled job’s fire and a background report were text blocks, or for a report a section of the turn_context block; they are inbox, scheduled and background_report blocks now, on GET /messages, in a blocking turn’s messages and in an archive, each carrying text as the model read it and the facts a client labels it by. The store converts what it holds on the first open, and a resumed screen shows an item as the labeled prompt it was and a fire or a report as the stage direction the live screen said, where it used to show meka’s header as something you typed.

The account views take the account. meka account usage, whoami and stats take the account by name, as login does, and lose --profile; named nothing, they ask the account the default profile bills, or the one account. An account with no profile answers. profile leaves their output, plain and JSON.

The two config keys are refused by name, with their line, until renamed. An archive of version 10 or older is converted on import. The store’s columns are renamed on the first open, behind the usual backup; a hand-written query names the new ones. ACP’s additionalDirectories keeps its protocol name, and /cd keeps its verb.

0.73 to 0.74

A one-shot run prints the answer alone, as markdown. meka --oneshot writes the last text block the model wrote to stdout when the turn ends, as source rather than rendered, terminal or pipe alike, and nothing else: no tool indicators, no thinking, no session id line and no usage line, on either stream. --format json is unchanged and carries the session id, the calls and the usage; -v logs the process. A script that read the session id from stderr reads it from the JSON report instead.

Three keys are gone, and the file refuses them by name. [display].tool_params and [thinking].show_content chose what a tool call or a thinking block showed before you expanded it. The screen expands and collapses either on a click or a key, so a call starts with its summary and a thinking block collapsed, and a one-shot run shows neither. [display].max_width capped the width meka laid text out at; the screen uses its window and a one-shot run its terminal. Delete the three from config.toml.

[display].show_token_usage is a fact of turn_end_summary. The screen now closes every turn with a row saying when it ended and how long it took, and the tokens used are one of the facts that row can state. show_token_usage = true becomes turn_end_summary = ["time", "duration", "usage"]; the old key is refused by name.

0.72 to 0.73

meka session delete is meka session remove. The session command now uses the verb every other object command uses; its flags are unchanged. A script or a cron line that runs meka session delete --older-than-days <DAYS> changes the one word. Tool names such as agent_delete, the HTTP DELETE routes and [serve].delete_on_idle keep theirs.

0.71 to 0.72

The interactive terminal is a screen, not a line editor. meka without --oneshot now takes over the terminal the way an editor does: the conversation fills the screen, the composer stays at the bottom, and you can type while the agent works. What that changes for an existing setup:

• Six [display] keys are gone, and the file refuses them by name. render_mode, input_style, newline_before_prompt and newline_after_prompt described a stream the screen no longer writes. Delete them from config.toml. --render-mode and MEKA_RENDER_MODE are gone with the first; a one-shot run now renders markdown when stdout is a terminal and writes the source as written when it is a pipe, so a script gets the words without asking. show_path_in_prompt and show_context_in_prompt are replaced by status_row, a list of what the status row shows in order. The default shows the path; to have the gauge back, list it: status_row = ["path", "profile", "context", "tasks", "subagents"].
• Answers no longer go to stdout in interactive mode. The screen draws on one stream. meka --oneshot and the HTTP API are the doors for a script, and both keep their contracts.
• A terminal is required. A pipe on stdin or stdout is refused with a line naming --oneshot. A harness that drove the old prompt through pipes drives --oneshot or the HTTP API instead.
• !command output is captured into the transcript rather than the child taking the terminal. A command that needs a terminal of its own runs in a shell beside meka.
• The syntect and raw views are gone. The screen renders markdown; a thinking block or a tool call expands to its whole content on a click or a key, so the source views have nothing left to show that the screen cannot.
• /history and /clear are gone, and display.resume_show_recent with them; the file refuses the key by name. The screen opens on the last page of the session’s log and reads older turns as you scroll up, however long the session is, so there is nothing left for either command to do. Delete resume_show_recent from config.toml.
• A slash command’s answer is a panel, not rows of the transcript. /help, /status, /usage and every listing open in place of the composer until Esc closes them; a bare /permission, /approvals or /profile is a picker. A command is no longer echoed as a prompt.
• The approval prompt is a picker. The four answers are picked with the cursor, their keys (y, a, n) or their numbers; always and never are no longer typed. Esc denies.
• Every row has a glyph. [tool name(...)], Thinking..., Error:, (interrupted) and the bracketed usage line are replaced on the screen by one register: •, ! and ■ in column 0 and the text at column 2. A one-shot run keeps the old spellings on its stream, with one change: consecutive tool indicators at the summary level now have a blank line between them, as every other pair of blocks does.

Two keys are new: display.mouse, on by default, and session.send_class, steer by default. Interactive mode describes the screen.

0.70 to 0.71

A hole in a feed is a feed.gap event, no longer a notice. A client that resumed a session feed, a sub-agent’s feed or the server feed from a Last-Event-ID the replay ring no longer reached was told so by a warn notice, and so was one that fell behind while connected. The first case is now a feed.gap event, with session_id on a session’s feed and dropped when the server can count the hole; a client that matched the notice’s text, or treated a notice without a turn_id as a hole, switches on the event name instead. The second case no longer reaches a client: a reader that falls behind is caught up from the ring, and only a POST /turn stream whose client was the sole reader still ends, with the sse-lag failure as before. notice now carries only what the agent or a provider said. See Falling behind.

0.69 to 0.70

The HTTP API changes shape in the places below. The store gains a table of turns and a column naming each message’s turn, the three todo tools become the checklist tools, every compaction boundary takes a checklist, and the message meka writes to send the model back to work (after a reply with no visible text, or with checklist items open) becomes a block of its own; the migration runs on open and needs nothing from you, and an older archive converts on import.

todo_write, todo_edit and todo_read are checklist_add, checklist_edit and checklist_read, and the list is binding. A turn can no longer end while an item on the list is pending or in progress: the model is sent back to its open items, up to three times in a row without a tool call, before the turn is allowed to end with them open. There is no title and no replace-all; items have ids, checklist_edit changes one at a time, and completed and canceled take an item off the list, the latter with a reason. Checklist has the rule. The old names in a session’s history, in a sub-agent’s denied tools and in an archive are renamed on open and on import; a list from before 0.70 is not recovered, since it never survived a restart anyway. A [tools] filter or a skill that names a todo_* tool needs the new name.

The per-turn context no longer carries the list. The model sees it in every checklist_* result, in the nudge, and through checklist_read; compaction copies the open list into the summary.

A blocking turn’s response carries the turn’s messages, and final_text and tool_calls are gone. messages now holds what the turn added to the conversation, in the shape GET /v1/sessions/{id}/messages reads it back: the assistant’s messages with their text, thinking and tool calls, and the tool-result messages that answered them. The reply a bot shows is the text blocks of the assistant messages, joined; a tool call is a tool_use block and its result the tool_result block on the user-role message after it.

last_turn_at is gone from the session record; last_turn replaces it. The old field named the last turn of any outcome, only while this server held the session. last_turn is the session’s latest turn, recorded for every host’s turns, and says how it ended: status, ended_at, and a stop_reason or an error. GET /v1/sessions/{id}/turns lists them all.

turn_id on a message is the turn’s id; the positional label is turn_label. A message’s turn_id was a dense label (t_0001, …) derived from its position; it is now the id of the turn that added the message, the one turn.started announced and GET /v1/sessions/{id}/turns lists, and the label moved to turn_label unchanged. A client that groups by the label reads turn_label; one that joins the feed to the history reads turn_id.

used_percent is gone from GET /v1/sessions/{id}/context. Divide used by window; both are present exactly when the percentage was.

vision left GET /v1/info for GET /v1/profiles. Read it on the entry of the profile a session runs on; the entry marked active is the one a session gets when it names none.

GET /v1/sessions/{id}/schedule is gone. List one session’s jobs with GET /v1/schedule?session=<id>; creating a job keeps its route.

DELETE /v1/schedule/{job_id} and DELETE /v1/sessions/{id}/tasks/{task_id} take the full id. A prefix matches nothing and answers 404. meka schedule cancel and the task_cancel tool keep taking the short form.

subagent.activity is gone from the HTTP feed. A sub-agent’s tool calls are no longer summarized under the parent’s agent_spawn call; while the parent runs a sub-agent, the sub-agent’s own id answers GET /v1/sessions/{id}/stream with its feed, every call in full. The permission_required a sub-agent’s call parks still arrives on the parent’s feed, now naming the sub-agent in subagent_id. ACP clients are unaffected.

GET /v1/sessions/{id}/stream on a sub-agent’s id answers 409, not 422. While the parent runs the sub-agent it is the sub-agent’s own feed; otherwise it is 409 subagent-not-running, a type of its own, where 0.69 answered 422 session-not-drivable. A client that branched on the 422 to recognize a sub-agent reads parent_id on the record instead.

Session archives are format_version 9. Each session carries its turns, each event names the turn that added it in turn_id, so an import keeps a session’s turns under ids of its own, each compaction boundary carries the checklist as it stood, and a nudge is a block of its own. An archive of version 3 through 8 still imports, with no turns and no turn named where it had none, an empty checklist on its boundaries, and every nudge it wrote as text taken as the block.

0.67 to 0.68

headers_helper is a path beside config.toml, or absolute. A relative name is resolved against the directory config.toml is in and nowhere else; it is no longer tried against the working directory meka was launched from, and a bare name is no longer searched on PATH. A helper that lived beside the config keeps working; one that relied on the launch directory or on PATH needs its path written out.

An MCP server whose url or args name an unset ${VAR} is refused. The literal used to be sent to the other side; a key in a query string or a token on a command line is a credential, so these fields now fail closed as env and headers always did. Set the variable, or give it a default with ${VAR:-default}. A reference the grammar does not accept (an unclosed ${, an empty name, a default that opens another reference) is refused the same way in every field that reaches the other side. To hand a child shell a variable it expands itself, write it without braces (args = ["-c", "srv --token $MY_TOKEN"]); meka leaves that alone.

[serve] values take ${VAR:-default} and no longer take $$. The one ${VAR} grammar serves every field of config.toml; $$ in a [serve] value is now two dollar signs, and $${VAR} is a $ followed by the expansion.

meka mcp add, remove, enable and disable refuse to write a config.toml that would not read back, as account and profile always have. A file broken elsewhere is fixed by hand first; an entry whose own keys broke the file is still removable.

[background] max_tasks = 0 is refused at startup while enabled = true. It offered background to the model and refused every call; set it to 1 or more, or turn the switch off.

A session expires as a tree. The retention sweep and meka session delete --older-than-days judge a root by its own age and take its sub-agents with it, and keep every sub-agent of a root that is pinned or owns a scheduled job. Before, an old sub-agent under a kept root was deleted on its own and agent_followup on it then failed. Every delete now locks the session with its sub-agents: meka session delete <id>, --all and the servers’ deletes refuse while another process is running a sub-agent under it, where they took the sub-agent from under that process.

GET /v1/sessions/{id}/stream loads an evicted session only for sessions:w. A token with sessions:r alone attaches to a session the server has loaded and is answered 409 (/errors/session-not-loaded) otherwise, where it used to revive the session and hold it, under its cross-process lock, for as long as the stream stayed open. A bridge that subscribes before it submits already holds sessions:w; a dashboard that only reads keeps reading resident sessions.

Below unrestricted, the in-process readers refuse a process’s own /proc entries. file_read and file_search refuse /proc/<pid>, /proc/self and /proc/thread-self, whose environ, cmdline, fd and mem carry what a process was given; the system-wide files (/proc/meminfo, /proc/cpuinfo, /proc/mounts) stay readable.

A skill’s bundled files in meka’s own store are readable at every level. file_read and file_search reach skills/ under the config directory below unrestricted, where they refused it; the rest of the directory stays private, and the shell sandbox still masks all of it, which the header a skill is served with now says.

interleaved_thinking on an account. anthropic-messages still sends the interleaved-thinking beta whenever thinking is on; [accounts.<name>] interleaved_thinking = false, or meka account add --interleaved-thinking false, withholds it for an endpoint that refuses the header. Nothing changes for an account that does not set it.

Wire changes. schedule.fired carries status: "not_run" for a job whose session could not be opened for it, where it said "failed"; turn.started carries source: "compaction" for the checkpoint turn POST /compact runs, with a turn.finished that closes it; meka account whoami --format json carries auth.expires_at as RFC 3339 rather than Unix seconds; DELETE /v1/sessions/{id} answers 409 while a scheduled or background turn is taking the session, as fork and PATCH do. A script that matched refusals from meka mcp, schedule, background, memory or skill on configuration error: will not match them any more: they print what happened, without that prefix. meka session list -n 0 and meka session search -n 0 show every session where they showed none, and meka --format json <subcommand> is refused where the flag was ignored.

0.66 to 0.67

Session archives are format_version 6. Each session’s stats carries a turn_position, the pair the Claude subscription wire reports, or null for a session that numbers nothing. An archive written by 0.59 through 0.66 still imports, brought forward at the door. A session that already had turns before this release never numbers them, on the store and in an archive alike, because nobody numbered those; every session created from now on does.

0.65 to 0.66

A shell under Landlock alone has no temporary directory. 0.65 gave each Landlock-confined command a private directory under /tmp, named by TMPDIR. That was the one thing meka wrote outside its own store below unrestricted, and it is gone: mktemp, Python’s tempfile, gcc and patch fail at read under Landlock as they did through 0.64. Install bubblewrap, whose private /tmp is a tmpfs inside the sandbox and touches nothing real, or add the directory a tool needs as a writable root at workspace.

Command output is bounded at 64 MiB and never spooled to disk. A command that prints more than that across stdout and stderr is stopped, and the result carries everything it printed up to the stop. The capture files that used to hold an overflowing stream, under the platform cache directory or MEKA_DATA_DIR/command-output, are no longer written; any left from earlier releases can be deleted. A command killed at its timeout now keeps what it printed before the kill.

0.64 to 0.65

Landlock on its own needs ABI v9 (kernel 7.1). Below that the kernel cannot refuse a connect() to a Unix socket on disk, so a shell at read could reach D-Bus and systemd-run --user and have them act on its behalf. meka now reports the backend unusable on such a kernel instead of warning, and shell commands at read fail until a usable backend exists. Install bubblewrap, which works on any kernel with user namespaces; on a kernel of 6.12 or newer the command also runs inside meka’s Landlock ruleset there. Affected as of this release: Debian 13, RHEL 10, Ubuntu 24.04 and 26.04 LTS without Bubblewrap.

Session archives are format_version 5. Every field is written, and the ones that used to default when absent are now required: blobs on the archive, and approvals, additional_roots and profile on each session. An archive written by 0.59 through 0.64 still imports, brought forward at the door, so only an archive written by hand has to change.

The checkpoint_text compaction source is gone. POST /v1/sessions/{id}/compact and the context.compacted stream event report source as checkpoint or summarizer only. A checkpoint turn that ends without calling context_replace now falls back to the summarizer instead of having its closing text taken as the summary. A client matching on the old value should treat it as summarizer, which is what those compactions now produce.

file_read and scratchpad_read take start and end. Both name the first and last line to return, counted from 1 and inclusive, the way a regex match reports its line; offset and limit are gone. file_read counted offset from 0, and scratchpad_read took both as bytes. A call that still passes the old names reads from the top. A scratchpad_read reply now ends on a whole line and names the line to continue from rather than a byte offset, and returns as much as fits by default. A client that read file_read’s offset to show a location should read start, which needs no adjustment.

0.63 to 0.64

The first open builds the session search index. meka session search reads a full-text index over the words of every conversation, and the first launch of 0.64 fills it over every session in the store, which takes a moment on a large one and is logged at info. The index is a few percent of the store’s size. Nothing else changes about the store’s contents.

A title or a pin does not move updated_at. PATCH /v1/sessions/{id} used to move updated_at for any field; title and pinned leave it alone, so renaming a session does not reorder the listing or change which session meka -c continues. A client using updated_at to detect changes sees a title change only in title.

Pinned sessions are listed first. GET /v1/sessions, ACP session/list and meka session list put pinned sessions ahead of the rest, newest pin on top; the unpinned sessions keep their order. A next_cursor taken from a 0.63 server is refused by 0.64 as invalid; start the listing again.

0.62 to 0.63

An inbox item’s source is optional. An item posted to POST /v1/sessions/{id}/inbox without a source used to be given one by meka: the token’s description, else client. It now has none. GET /v1/sessions/{id}/inbox omits the field for such an item, so a client that reads source as required must treat it as optional; a client that sends one sees no change. The model reads such an item under [Message arrived <time>] rather than [Message from <source>, arrived <time>], and the notice an interrupt raises says “Interrupted the answer to read a message.” with no name. Send a source if you want the model to know who is writing: who sent a message is the client’s to say.

The system prompt states how the harness works and nothing else. It no longer tells the model what it is (“a general-purpose agent”), what to do (“complete the user’s task”), or how to conduct itself. The conduct sentences that left, for an instructions file that wants any of them back, where they were always yours to set:

• “Explain consequential or destructive actions before proceeding.”
• “Recover from routine tool errors when possible; report unresolved failures and their impact.”
• “Lead with the outcome and relevant evidence; keep progress updates brief.”
• “Batch independent work; sequence dependencies and changes to shared state.”
• “Apply relevant skills and server guidance within these constraints.”
• “Do not poll or duplicate running work.” and “Keep work needed for your answer in the foreground.”
• “Prefer to finish or checkpoint work before then.” and “save essential state with the available tools before another pass” (the context window)
• “Check here before creating one, so you do not duplicate.” (scheduled jobs)
• For a sub-agent: “Complete the assigned task without follow-up questions. Report the outcome, relevant evidence or verification, and unresolved limitations.”

What stays is what the model needs to use the harness: the permission levels, how tools, background work, scheduling, memory and the context window behave, and that replies are rendered as Markdown.

0.59 to 0.60

Every built-in tool is named <noun>_<verb>. The noun is the class a tool belongs to and the verb its one operation, so the tools that act on one thing sort as one block. Nine names change:

todo is three tools. todo_write takes title and items and replaces the list, todo_edit takes set and updates statuses by task number, todo_read takes nothing. The single tool’s “items then set in one call” is two calls now.

tool_search is new: keyword search over every registered tool, deferred ones included, that says for each whether the current permission level allows a call.

What is converted for you, the first time the store is opened and behind the automatic backup: the calls in every stored session (so a resumed session keeps the tools it had loaded and its history shows one set of names), the denied_tools of every sub-agent, the tool a finished background task reports, and the tool a scheduled job’s gate calls. A session archive written by 0.59 (format_version 3) still imports; new archives carry format_version 4.

One narrow case to know about: the conversion reads every stored message that can hold a call, and a prompt you typed that was, in its entirety, the JSON of a tool call under an old name is converted like a call. Prose around such JSON leaves it alone.

What is not: a [tools] or [subagents] list, a tool_permissions key, a skill, standing instructions, or a client that matches on a tool name must be edited. The startup warning and the model’s unknown-tool reply suggest the new name when the old one is a reordering of it (read_file, write_file, edit_file, render_image, load_tool) or a family’s bare noun (todo); the other four are named only here.

0.58 to 0.59

meka is licensed under the GNU Affero General Public License, version 3 or later. Releases up to 0.58.0 were published under MIT and remain so. From 0.59.0 on, conveying meka or a modified copy, and offering a modified copy to users over a network, carries the AGPL’s obligation to make the corresponding source available.

The problem type URIs moved to meka.run. Every error document meka returns now names a type under https://meka.run/errors/ where it used to sit under https://meka.so/errors/. The identifier after the last slash is unchanged, as are the HTTP status, the title and every other member of the document. A client that matches the whole URI must update its table; one that reads only the final segment is unaffected.

0.54 to 0.55

GET /v1/sessions/{id}/stream is the session’s event feed and no longer ends with a turn. It used to rejoin the current turn and close after that turn’s terminal; it now carries every turn on the session, whoever started it, for as long as the connection is held, and opens the feed of a session that has not streamed yet instead of answering 404. A client that read the stream to its end must stop at the terminal it was waiting for. POST /turn with stream: true is unchanged and still closes after its own terminal. The replay ring spans turns, so a Last-Event-ID from an earlier turn resumes across them rather than reporting a gap.

Every SSE event carries turn_id and session_id, and turn.started carries source. A client that compared an event’s data whole sees two extra members; one that read named fields is unaffected.

Scheduled fires and background-outcome turns are on the feed. They used to be invisible over HTTP until GET /messages. Nothing changes on the webhooks: a fire still posts schedule.fired and nothing else.

agent_steer is a new built-in tool. A session that lists tools by name, or a skill that denies agent_spawn to take the lifecycle tools with it, now covers five names rather than four.

0.53 to 0.54

The store renames its tables and columns in place. The upgrade runs on the first open, behind the usual pre-migration backup, and needs nothing from you. A tool that reads meka.db directly sees scratchpad_entries for tool_outputs, messages.kind for messages.role, background_tasks.tool and scratchpad_entry for tool_name and scratchpad_name, mcp_credentials.server for server_name, blobs.size_bytes for size, and the session counters without their stat_ prefix; the provider_credentials view and memories.last_read_at are gone. Sessions has the full layout.

Three surfaces say the new names too. GET /v1/sessions/{id}/tasks and the task.finished webhook carry tool and scratchpad_entry in place of tool_name and scratchpad_name. A memory’s creation stamp is created_at on GET /v1/memory and in --format json, and created in a file meka memory export writes. A session archive holds its scratchpad entries under scratchpad_entries rather than tool_outputs and is format_version 3; meka session import refuses an older archive, so export it again from the meka that wrote it, or rename the key and set the version in the file by hand.

0.52 to 0.53

[session].context_messages is gone. Delete the key from config.toml; a file still carrying it is refused at startup, naming the key and the line. It cut every request to the newest 200 messages, and a conversation that outgrew it lost its oldest messages from the request with no summary in their place: context usage fell instead of climbing, and the agent forgot what it had been told before the cut. Every request now carries the whole conversation, and the context ceiling ([session].context_ceiling_percent, 90% of the profile’s context_window by default) with auto-compaction is the only bound. A long session reaches the ceiling and compacts where it used to slide; with auto_compact = false it grows until the provider rejects a request.

Nothing in the store changes. A session already past 200 messages resumes with all of them in the request, so its first turn back may compact.

The container image is gone. ghcr.io/k4yt3x/meka receives no new tags, and the Dockerfile went with it. What the image was for, running the agent unrestricted against a disposable filesystem, is what mekabox does with the meka installed on the host, inside a stock archlinux:latest container with your config mounted read-only; install the binary from the release archive or with Cargo and run the wrapper. The wrapper itself moves from contrib/container/mekabox to scripts/mekabox, so a link or PATH entry that named the old path needs the new one.

0.49 to 0.50

meka tools is meka tool. Every top-level command names the object it manages in the singular, and this was the one that did not. meka tools list is meka tool list; the flags and the JSON envelope are unchanged. meka mcp tools <name> keeps its name, since it lists the tools of a server rather than managing tools.

/tasks is /task in the REPL, for the same reason: /skill, /memory and /schedule are singular. /task, /task show <id>, /task cancel <id> and /task cancel --all do what the plural did. The HTTP route /v1/sessions/{id}/tasks is unchanged.

0.46 to 0.47

search_web is gone. It scraped DuckDuckGo’s HTML and was turned away by the bot detection more often than not. Web search now comes from an MCP server, which packages one engine’s key, quota and response shape without meka embedding any of them:

meka mcp add exa https://mcp.exa.ai/mcp

A [tools] list that still names search_web warns at startup and otherwise works. Existing sessions that called it resume unchanged: their tool results are text, and nothing re-runs them.

0.45 to 0.46

The store migrates itself, as every release since 0.43 has. config.toml does not, and this release changes its shape: a [providers.<name>] profile is now an [accounts.<name>] table plus a [profiles.<name>] table, default_provider is default_profile, and the ask permission level is gone. A config in the old shape is refused at startup, naming the first key meka does not know, rather than read with a guess at what it meant. The conversion is a one-shot script, migrate-0.45-to-0.46.py, attached as an asset to the 0.46 release.

Beyond the config shape, this release renames several tool parameters, changes a handful of HTTP fields and status codes, and makes ACP answer InvalidParams where it answered InternalError. Everything a client, a skill or a script could depend on is listed below under “What else changed” and “Tool parameters”, each with its remedy. Run the script, launch once, and work down those two lists for anything you automated.

Order

1. Run the script against your config, first as a dry run, then with --apply. It needs Python 3.11 and the tomlkit package (pip install tomlkit), which is what lets it keep every comment and the order of everything it does not touch.

   python3 migrate-0.45-to-0.46.py            # prints a diff; writes nothing
   python3 migrate-0.45-to-0.46.py --apply    # rewrites config.toml in place
   

   It finds meka’s config the way meka does, honoring MEKA_CONFIG_DIR; --config PATH points it at a copy instead. --self-test checks the script against its own fixture and exits.

2. Install 0.46 and launch it once. The store migrates on that open, behind an automatic copy beside it named for the schema version it came from (meka.db.v9.bak for a store 0.45 left), in ten ledger steps. The first creates the REPL’s prompt_history table where a store lacks one, a no-op otherwise. The other nine: sessions.provider becomes sessions.profile, and provider_credentials becomes account_credentials, keyed by account, both renames of what was always there; an approvals column is added, every ask session becomes none with it on, and a root session that never recorded a level (one an ACP client created) adopts [permissions].default; each stored turn’s inline <context> preamble becomes its own turn_context block; every image’s bytes move out of its message row into blobs, leaving a reference; every column and index takes one naming rule, with the JSON in two of them following suit; a repair row’s own thinking blocks take that rule’s tag too, which the step before it passed over; a root session still without a level after all that takes [permissions].default, and a launch that cannot read the file refuses here rather than skipping the stamp; and a stopped task’s stored status is spelled canceled. Four of these walk every message row, so a store with years of image-heavy sessions takes a moment on that first launch and grows a copy of the same size beside it. A store restored from a .dump replays the whole ledger, and if no default profile can be resolved when it does, the frozen 0.44 step warns with its old --provider advice; read it as --profile.

Run the script before you launch 0.46, not after. A meka launched against an unconverted config warns that it cannot read the file and then refuses whatever needed it; only the commands that edit it through toml_edit (meka account remove, meka profile remove, meka mcp remove) and the ones that read the store alone still run. The store migrates on that launch only if no step needs the file. A root session that never recorded a level needs [permissions].default from it, and a migration that cannot read the file refuses and rolls back rather than stamping nothing, so the store keeps its 0.45 shape until the launch after the script has run.

What the script converts

Every profile becomes one account and one profile of the same name, so nothing you named changes its name and every session still resolves. Two old profiles on one login stay two accounts with two copies of the credential; merge them by hand if you like, by pointing both profiles’ account at one and running meka account remove on the other once nothing names it. A key the script does not know is carried into the profile table and reported, where meka will refuse it by name; a duration key whose value is not a whole number is left under its old name and reported, with the same result.

What else changed

• The meka provider suite is gone. meka account add/login/list/remove manage accounts and their credentials; meka profile add/set/use/list/remove manage profiles. meka account usage/whoami/stats are where they were, and take --profile <name> instead of a positional name. account add takes --backend where provider add took --type.
• The prompt is a flag. meka "text" is meka -p "text", and -p - reads the prompt from stdin. There is no positional prompt, so meka unknowncommand is an error rather than a session.
• --provider is --profile, long form only: -p is the prompt.
• --format json on a --oneshot run prints one object for the turn; see One-shot mode.
• HTTP API: the provider field on POST /v1/sessions, PATCH /v1/sessions/{id} and every session response is profile, and GET /v1/providers is GET /v1/profiles, whose rows carry account and backend in place of type. A session export archive’s provider field is profile, and its format_version is 2, so an archive written by 0.45 is refused by version; re-export it from a migrated store.
• ACP: the configOptions entry provider is profile.
• REPL: /provider is /profile, and /status shows the profile with its account.
• One spelling per value. --permission and MEKA_PERMISSION take a level’s full name (n, r, w, u are gone), and --render-mode, MEKA_RENDER_MODE and [display].render_mode take termimad, syntect or raw (rich is gone). The flags and the config key refuse anything else; the two variables warn and fall through to the next source, as they always have. The undocumented text spelling of --format plain is gone too.
• A [permissions].default or enabled entry naming a level meka does not have is refused at startup, with the line, the way an unknown key is, instead of being dropped with a warning. The script rewrites ask; anything else you spelled yourself.
• The ask permission level is gone, replaced by the approvals switch beside the level: a call above the level is refused, or put to you when the switch is on. /approvals on|off in the REPL, approvals on POST /v1/sessions and PATCH /v1/sessions/{id}, and the ACP config option of the same name set it; [permissions].approvals is what a new session starts with. The store migration turns an ask session into none with approvals on, which asks about every call as ask did. An approved call now runs at the session’s level, so an approved write at read lands only under the workspace roots where ask wrote anywhere; raise the level if an approved call needs the reach. See Permissions.
• A user message is two blocks. What meka injects ahead of the words for a turn (permission and environment context, todos, catalog changes, background outcomes, the resume notice) is its own turn_context content block, first, and the words are a text block. GET /v1/sessions/{id}/messages returns the block typed, so a client reading content[0].text as the prompt now reads the context; take the text blocks. A migration splits every stored turn once.
• Image bytes live in a blobs table. The migration moves every inline image out of its message row and leaves a reference by content hash, so a screenshot read twice is stored once. A session export carries a blobs list with the bytes its sessions reference, and an archive that references a blob neither it nor the store holds is refused. Over HTTP an image block reports media_type and hash, and GET /v1/sessions/{id}/blobs/{hash} serves the bytes.
• A scheduled job runs at its session’s recorded level and nothing else. The polling process’s own --permission no longer stands in for a session row that records no level; every surface records one at creation, and the migration stamps the configured default on any older root row that never got one. A sub-agent’s row now records its level too.
• Every config duration is a humantime string. [web].request_timeout, connect_timeout and read_timeout, [mcp].grace and connect_timeout, [session].retention ("30d"); the script converts the _seconds and _days keys by value, and "0s" is refused where zero is meaningless. [mcp].strict is default_required and [thinking].budget_tokens is budget, both converted. MEKA_MCP_STDIO_CONCURRENCY and MEKA_MCP_HTTP_CONCURRENCY are gone: set [mcp].stdio_concurrency and http_concurrency (3 and 20 by default, zero refused). MEKA_MCP_TOOL_TIMEOUT takes a duration such as 10m, not milliseconds; a bare number is ignored with a warning and the default of ten minutes applies.
• One exact spelling per value, everywhere. --permission, --render-mode, --sandbox-backend, --format and mcp add --transport refuse case variants (Read, JSON), session export and GET /v1/sessions/{id}/export drop the md alias of markdown, mcp add --auth takes oauth, client_credentials or client_credentials_jwt as the [auth] block spells them (the hyphenated forms are gone), and [mcp].default_permission, a server’s permission and tool_permissions, and [tools].tool_permissions refuse a level meka does not have at startup, naming the line, where they warned and ignored it.
• HTTP API: an unloaded session whose row records no level omits permission (it sent ""); every optional field is omitted rather than null, display_summary included; GET /v1/health/ready reports profile_configured (was provider_configured); the permission_required event carries input and stays answerable for 30 minutes (was 60 seconds); a body that fails to parse says which field on every endpoint; POST /v1/sessions/{id}/responses/{request_id} at a sub-agent’s id answers 422 session-not-drivable; a fork of a session another meka process holds answers 409 session-locked; a session’s title is the first user words with whitespace collapsed, cut at 80 characters, and meka session show labels it title (was opening). Four status codes move: a [web] or base_url misconfiguration is a sanitized 500 (was a 422 naming the operator’s path), and a session lock meka cannot open is 500 (was 409 session-locked); meka’s own request-ceiling refusal is 422 with the new type request-too-large (was 502 provider); GET and PATCH /v1/sessions/{id} answer 404 or 500 for a row they cannot read (was 200 with profile: ""); and POST /v1/sessions/{id}/schedule with scheduling disabled is 404 (was 422).
• ACP: a locked session, a sub-agent’s id, a profile the config no longer has and every other refusal the caller can act on answer InvalidParams (was InternalError); session/set_config_option refuses a profile switch while a turn is in flight instead of writing the row and deferring; session/new, load, resume and fork refuse a cwd that is not an existing directory and record it canonically; tool-call and permission titles read <tool_name> <argument> (read_file src/x) and permission requests carry rawInput with a JSON content block.
• Terminal output: every timestamp is local time with its UTC offset (2026-09-07 14:03 +02:00), sizes print as MiB, KiB or B, and every listing command takes --format json, printing the HTTP API’s record shapes. Tool-call indicators and the approval prompt show a tool’s real name (read_file, not ReadFile); the prompt is headed [approval] and takes always and never.
• Skills you wrote that name a renamed tool parameter (next table) or the old [ask] prompt must be edited by hand; meka does not rewrite skill files.
• A gate’s pointer test is not_empty (was not-empty) in schedule_create, POST /v1/sessions/{id}/schedule and meka schedule add; stored jobs are converted by the store.
• canceled, one l, on every wire meka owns. Match turn.canceled as the SSE terminal event, https://meka.run/errors/turn-canceled as the problem type, and status == "canceled" in task views (GET /v1/sessions/{id}/tasks, DELETE .../tasks/{task_id}), task_list output and schedule.fired webhook bodies; the reason values are unchanged. The store rewrites its stored task rows on first open (the tenth ledger step). ACP’s stopReason: "cancelled" and MCP’s notifications/cancelled are those protocols’ own spellings and stay.

Tool parameters

Six built-in tool parameters are renamed so that one name means one thing across the catalog: is_regex for a boolean, glob for a glob, limit for a result cap, id for an identifier.

A call spelling the old name is missing its required parameter (glob, id) or, where the parameter was optional, has it ignored in favor of the default. search_contents gains a limit (1 to 100, default 100) beside its unchanged pattern.

meka does not rewrite what names these. A skill under the skills directory (~/.config/meka/skills/<name>/SKILL.md) that spells out a find_files or agent_followup call must be edited by hand, and a scheduled job whose gate calls one of these tools with the old argument must be recreated. Past calls in a session’s history keep the old names, which is harmless: the model reads the current schema on its next turn.

The sections below predate 0.46 and use its old names: --provider is --profile, meka provider … is meka account … and meka profile …, the positional prompt is -p, and the ask level is none with approvals on.

0.43 to 0.44

A binary swap, and the store migrates itself as promised below, unless you authenticate an MCP server with auth_token or client_secret, which are no longer config keys. Read the next section first if you do; meka will refuse to start otherwise. Then the behavior changes below, worth reading before you resume an existing session or run a scripted meka, several of which apply only if you run meka serve or meka acp.

MCP secrets moved out of config.toml. auth_token on a server, and client_secret in a [mcp.servers.auth] block, are gone. Both were secrets sitting in a plaintext file people commit and sync; they now live in the store beside the OAuth tokens, which is where the login credentials have always been.

meka cannot move them for you. The store migrates itself because it has a ledger recording what it has already done; config.toml has none and may be older or newer than the binary at any moment, so a key left behind is a parse error naming the key and the line rather than a value silently ignored:

$ meka mcp list
Error: database error: schema migration 3 ('sessions_name_their_provider') failed: Invalid
parameter name: cannot record a provider for 4 carried-forward session(s) while config.toml
cannot be read; fix the file and start meka again. The store is unchanged

The parse error itself is a warning just above it, naming the key and the line:

WARN meka: failed to read config.toml, so no profile can be adopted for older sessions:
configuration error: failed to parse …/config.toml: TOML parse error at line 12, column 1
   |
12 | auth_token = "…"
   | ^^^^^^^^^^
unknown field `auth_token`, expected one of `name`, `transport`, …

Two messages because two things are stuck: the file will not parse, and the migration that has to name a profile for your existing sessions cannot ask it which one. Fixing the file fixes both, and nothing has been written in the meantime: “The store is unchanged” is literal, and the copy taken before the attempt is still beside your store. (On an installation with no sessions to carry forward, only the parse error appears.)

For each server, delete the line and store the secret instead. Which command depends on which key you deleted, and the two are alternatives, not a sequence: a bearer belongs to a server with no [auth] block, a client secret to one that has it.

$ # for a server whose `auth_token` you deleted (no [auth] block):
$ pass show api-token | meka mcp login api --auth-token-stdin

$ # for a server whose [auth] block's `client_secret` you deleted:
$ pass show acme-secret | meka mcp login acme --client-secret-stdin

meka mcp get <name> then lists the kinds it holds without printing any of them. --auth-token and --client-secret are gone from meka mcp add for the same reason: an argument is visible in ps output and in the shell history of every user on the machine. Use the -stdin forms, which add also takes.

If you were using auth_token = "${API_TOKEN}" to keep the token out of the file, a header does the same job and still expands: headers = { Authorization = "Bearer ${API_TOKEN}" }. Storing it is the better answer, since it survives without the variable being set.

Nothing else about a server moves. env, args and headers stay in config.toml with ${VAR} expansion, because they configure a process or a request and merely may contain a secret.

isolated scheduled jobs are gone; every job fires in the session that created it. The mode ran a job’s turn in a fresh session rather than the conversation that made it, to avoid replaying that conversation’s history. Only meka serve ever honored it: the REPL and ACP already ran such a job in the open conversation, with a warning, so for two of the three hosts nothing changes at all.

Existing jobs are not deleted and do not need touching. The store drops the column and the job keeps its schedule and its prompt, firing into the session it belongs to from then on.

What it cost is why it went. The fire inherited the creating session’s authority (its permission level, its working directory, its profile, its MCP servers) and dropped the conversation, which is where anything you told the agent that never reached a memory or an instructions file lives. Its result landed in a session nothing linked to, and the turn could not even cancel its own job, because schedule_cancel resolves against the session it is running in.

meka acp and meka serve clients: POST /v1/sessions/{id}/schedule now refuses isolated with a 422 naming the field, rather than accepting and ignoring it. GET /v1/schedule and the schedule.fired webhook no longer carry it either.

If you were relying on the mode, an external timer does the same job with the level and profile stated outright instead of inherited (0.44 syntax):

meka --oneshot --permission read --provider work "summarize today's alerts"

Often a gate is the better answer: it means a frequent job takes no turn at all on the ticks where nothing happened, which saves more than skipping the history did.

A session another one spawned is driven only by its parent. POST /v1/sessions/{id}/turn answers 422 for a sub-agent’s id, meka -r <sub-agent-id> refuses by name, and a scheduled fire aimed at one does the same. Both agent builders now check, rather than the scheduling door alone.

What this closes is that a sub-agent’s restrictions live in its spawn record, which those builders never read: the [subagents] denials it was created under, its memory and instruction grants, and the permission ceiling its spawn call set. Driving one from a host therefore ran a conversation that was deliberately given narrow tools with the full built-in set at the host’s level. agent_followup was and remains the door that reconstructs those terms, so nothing meka does for you changes.

Reading a sub-agent is untouched: meka session export, GET /v1/sessions/{id}/messages and meka session list --include-children all still serve it.

Forking one does not promote it, and that is the other half of the change. A fork of a sub-agent now carries parent_session_id and the spawn terms, so the copy is a sibling under the same parent rather than a new root; without that, POST /v1/sessions/{id}/fork was a one-call way around the refusal above, handing back a live session over a sub-agent’s whole conversation with none of the terms it was spawned under. The two doors that have to hand back a live session therefore refuse a sub-agent’s id up front: POST /v1/sessions/{id}/fork answers 422, and ACP’s session/fork answers InvalidParams. meka session fork still makes the copy: it takes no runtime, and the copy is readable like any other sub-agent. Forking an ordinary session is unchanged. If you want a sub-agent’s conversation as a root session of your own, copy the text out rather than expecting a command to promote it.

meka session list --long is gone, along with the columns it showed. If a script parses that output, it needs updating; the default columns are unchanged.

/cd with no argument returns to the directory meka was launched from, not $HOME. /cd ~ still goes home. The old behavior made a bare /cd a surprising way to leave the project you were working in.

render_mode = "silent" is gone, as are --render-mode silent and MEKA_RENDER_MODE=silent. Delete the setting: termimad is the default.

A config still carrying it fails to parse, naming the value and the line, and --render-mode silent is refused by clap. MEKA_RENDER_MODE=silent is the quiet one: an unreadable value there has always been dropped in favor of the next source, so it falls through to your config file or the default rather than saying anything.

It never did what it says. It suppressed the model’s answer and nothing else, so a run under it printed the session id, the reasoning line, tool indicators, todo lists, notices and token usage, and dropped the one thing you were waiting for. Both things it might plausibly have meant are shell redirections that already work, and work the right way round: meka … 2>/dev/null keeps the answer and drops the chrome, meka … >/dev/null 2>&1 drops both.

SSE thinking.delta now carries one chunk of reasoning per event. It used to send one event per completed block, so a client that opted into supports_reasoning_stream and rendered each event as a whole block will now show fragments. Concatenate the deltas to rebuild the block, exactly as you already do for assistant_text.delta. A client that concatenated needs no change, and one that never set the capability sees nothing new. A turn the provider answered without streaming still arrives as a single delta, so there are no two shapes to tell apart, and stream: false still reports each block whole in thinking.

One consequence worth planning for: a session receiving reasoning gives up its retry on a transient provider failure, because the deltas have already reached you and a second attempt would repeat them. Leave supports_reasoning_stream off if you would rather have the retry.

meka session delete refuses ids given alongside --all. It used to take both and quietly do the wider thing, so meka session delete "$ID" --all with $ID unset deleted every session and then reported the empty id as a failure: a complete wipe reported as an error. Naming sessions and asking for all of them are two different requests; say one or the other. --older-than-days has conflicted with both for the same reason since 0.44.

Every command taking a session, job or task id now accepts a unique prefix of one, which is what the listings print. Full ids still work, so nothing that already worked stops. An ambiguous prefix is refused with the candidates named, and an empty one matches nothing rather than the only row: meka schedule cancel "$JOB" with $JOB unset used to cancel whatever job was alone.

meka mcp logout <name> clears every credential that server holds, not only its OAuth tokens. If you were using it to drop a stale token from a server that also has a stored bearer or client secret, you will now need to store that again with meka mcp login.

A scheduled job is refused on a sub-agent session. POST /v1/sessions/{id}/schedule answers 422 if the session was spawned by another. Sub-agents never had the schedule_* tools, so no job meka created can be affected; what this closes is a client planting one directly, which would have woken the sub-agent without the tool restrictions or memory grants it was spawned under.

ACP session/load and session/resume refuse a sub-agent’s id. Both used to take the session’s lock, rewrite its cwd, retire its background work and replace its roots before failing with Internal error; both now decline with InvalidParams before touching anything, naming the parent to use agent_followup from. An editor that stored a sub-agent’s id from session/list gets a clear refusal instead of a mutated row and an opaque failure. Over HTTP the same holds for every write-side endpoint: POST /v1/sessions/{id}/turn and its neighbors refuse before taking the sub-agent’s lock or marking its background tasks interrupted.

A session that carries spawn terms is refused even when its parent is not in the store. That shape has one source, and it is a pair of documented commands: meka session export <sub-agent> --format json followed by meka session import. The archive’s parent_id points outside it, so the import re-roots the row while copying the spawn terms faithfully. The result reads as a sub-agent’s conversation to every door, so meka -r on it, and POST /turn, /fork, /schedule and PATCH against it over HTTP, all refuse. meka -c skips it and meka session list shows it only under --include-children, both so nothing offers you a session it will then decline. If you were using export-then-import to promote a sub-agent into a standalone session, that no longer works; there is no supported replacement, because the tools and permission ceiling a sub-agent ran under live in the terms its parent set and nothing outside that parent can reconstruct them. The conversation itself stays fully readable, and importing a whole tree (the root and its sub-agents together) is unaffected, since each child keeps its parent.

This upgrade deletes the pre-migration copy 0.43 left, and keeps one from now on. Before it migrates, meka copies the store aside; until now nothing removed those, so a full duplicate of your whole history accumulated per schema-changing release. From 0.44 a fresh copy supersedes the one before it. In practice that means meka.db.v1.bak in your data directory, the copy of your pre-0.43 store, is removed on this upgrade and replaced by a copy of your pre-0.44 one. If you want the older file, move it somewhere else before upgrading.

Two things worth knowing about what is kept. Peak disk during an upgrade is higher than the steady state, because the new copy is written before the old ones go: budget for the store plus every copy already beside it plus one more, and expect to settle back at twice the store. And the copy is taken per schema-changing upgrade, not per release, so one file can span several versions if you skip some.

What keeping only the newest copy costs, stated plainly. The copy you hold is of the store after the migration before this one. So it undoes the most recent conversion and nothing earlier: if a migration converts something wrongly, you do not notice, and you then take another schema-changing upgrade, the only copy predating the fault is gone. That is a real limitation rather than a technicality, and it is the reason to move a copy of your own aside if a particular upgrade worries you. It is accepted because the alternative was an unbounded pile of full-size duplicates, whose cost is certain where this one is conditional on a bug outliving a release.

A resume now starts at the level the session recorded. Both CLI hosts do this: the REPL and meka --oneshot -c / -r. The scripted one is where a silent change matters most, since a --oneshot run that passes no --permission used to start at the config default and now starts at whatever the session was last set to. A session you created with --permission unrestricted comes back at unrestricted without the flag. Before, the row said one thing and the run did another; every other surface already read the row, and these two were the ones that did not. Pass --permission on the resume to move it. A level that is no longer in [permissions].enabled is not granted: the session drops to the configured default with a warning.

A session now runs on the profile it was created with. Every existing session is recorded as running on your current default profile, which is what they were in fact running on, so nothing moves. From here meka -p openai then meka -c stays on openai. If nothing could be resolved when the migration ran (no profile configured yet), sessions are left without one and say so; resume such a session once with --provider <name> to record it. The migration says which profile it recorded and on how many sessions; run once with -v if you want to see it.

A 502 from meka serve now carries the provider’s own response text, as a provider_response member on the Problem Detail. It used to be withheld and written only to the server log.

The reason for the change is that the redaction defended less than it appeared to: meka acp has always handed the same text to its client, so withholding it on HTTP left the text just as public while making the one surface quieter. What it cost was the upstream’s error type, which is the one part of a failed turn a client can act on.

Know who can read it before you leave it on. An upstream refusal can name your account with the provider, your organization, and your rate-limit posture. Submitting a turn takes sessions:w, but the failure is also carried by the terminal turn.failed event, and re-attaching to a stream takes only sessions:r, so a read-only token sees it too. If you issue read-only tokens to people who may observe a session but are not entitled to the account behind it, set [serve] relay_provider_errors = false. Nothing else changes: detail carries the same sentence either way, and with the key off the member is simply absent.

The 503 for a required MCP server that is down is not affected and still reports only the server names. That reason is meka’s own subprocess text and has carried a command line and its filesystem path, which is a different disclosure and not one this key governs.

GET /v1/info no longer returns provider or model. Read them from GET /v1/providers instead, which lists every configured profile with its name, its type (the backend), its model, and active: true on the one a session gets when it names none. The old fields held the default profile’s backend under the name provider, while provider on POST /v1/sessions names a profile, so a client that read one and posted it to the other got a 422. They were duplicates of the active row besides.

If you ran a 0.44 development build, your store repairs itself on the next run. One such build removed a migration from the middle of the ledger instead of appending its reversal. user_version is a positional index, so that renumbered every later step, and a store sitting between the hole and the new head skipped a step it had never run while stamping itself current. The symptom was every MCP connection failing with no such table: mcp_credentials after a migration that reported success.

Nothing is needed from you: an appended step recreates the table and carries the old MCP credentials into it, because a store already stamped past the missed step is only reachable by appending. Released 0.43 stores were never affected; they sit at the baseline and migrate straight through.

--model, --base-url, --thinking and --thinking-budget are gone. A profile is an indivisible bundle: the backend, the endpoint, the credential keyed to it, the model, and every model-tied setting. A session selects one by name and records that name. A flag that moved one field of the bundle left the rest behind, so --model against a profile stating context_window = 1000000 ran a 200K model while gauging its context against a 1M window, and never auto-compacted.

Change a setting on the profile (0.44 syntax):

meka provider set work model claude-opus-5
meka provider set work effort --unset

Or make a second profile and select it with --provider, which is now the only provider flag on a run. meka provider add has a flag for every profile field except device_id, which meka resolves and persists itself, so one command creates a whole profile (0.44 syntax):

printf '%s' "$ANTHROPIC_API_KEY" | meka provider add fast \
    --type anthropic-messages --model claude-haiku-4-5 \
    --context-window 200000 --api-key-stdin

The thinking budget is per profile. [providers.<name>].thinking_budget takes precedence over [thinking].budget_tokens, which stays as the installation-wide fallback and needs no edit. The global was previously cross-checked against a per-profile max_output_tokens, so a profile could be refused over a number stated nowhere in it, and told to fix it by lowering a value every other profile also read.

meka acp and meka serve refuse -c and -r. Both name one run’s session, and a long-lived host has no such thing: it creates one per session/new or per POST /v1/sessions, each naming its own profile. They used to be accepted and quietly misapplied: -c / -r switched off the default-profile check a host with no default needs most. Over HTTP, name a provider on POST /v1/sessions; under ACP, session/new creates on the host’s default and session/set_config_option moves it. --provider is still accepted, because it selects which configured profile the host defaults to, which is a property of the host rather than of one session.

Also on the HTTP side, and not a break: PATCH /v1/sessions/{id} with a body naming only a provider now works on a session that is not loaded, which is how you move one whose profile has left config.toml. It takes the session lock to do it, so if you run more than one meka on the same store, send it to whichever process has the session; another one answers 409 session-locked rather than moving a row the running host would ignore.

0.42 to 0.43

Nothing to do. Start 0.43 and it brings the store forward itself, on the first open, before anything reads it.

This is the first release that migrates its own store, and from here on that is the rule: upgrades from 0.43 onward are a binary swap, whatever the schema does.

What it changes, if you want to know what happened. A scheduled job’s gate used to be two columns, gate_command and gate_fire; it is now gate_kind plus a JSON gate_spec, which is what lets a gate call a read-only tool instead of a shell command. And a due job is now claimed by leasing it rather than by consuming its row, which adds claimed_by, claimed_until and attempts, so a host that crashes mid-delivery no longer loses the occurrence, or for a one-shot the whole job. Each gate’s stored baseline is preserved, so a changed gate does not fire spuriously on its first evaluation afterwards.

Before it writes anything, meka copies the store to meka.db.v1.bak beside it. That doubles the space the store takes until you delete it, which is worth knowing if yours is large. Start with -v once if you want the exact path in the log; the copy is otherwise silent. It records the version it was taken at, so if you ever restore it, the next start migrates it again correctly rather than mistaking it for a store that is already current.

The whole thing is one transaction, so an interruption leaves the store exactly as it was rather than half-converted. Running two hosts at once is fine: the first takes the schema lock and the second waits, then finds nothing to do.

Coming from 0.41 or older, run migrate-0.41-to-0.42.py once first, as described below. 0.43 recognizes a 0.41-shaped store and refuses it by name rather than converting it into something still unreadable, and it changes nothing when it does.

A gate that cannot be read

Rare, and worth knowing the shape of. If a job’s gate was already unreadable under 0.42 (a hand-edited row, or a gate_fire value meka never wrote), it cannot be converted, because there is nothing to convert it from. Such a job never fired under 0.42, and it does not fire under 0.43 either: the migration leaves it in the same refused state rather than guessing at what it meant or deleting it. It is logged once, by id, at warn.

The consequence is that the row stays inert and invisible, as it already was: it will not appear in meka schedule list and meka schedule cancel cannot reach it. Recreate the job if you still want it. The original row is in the backup 0.43 took, meka.db.v1.bak. Note that from 0.44 a later schema-changing upgrade deletes that file, so put a copy somewhere of your own if you want to keep it.

0.41 to 0.42

A store written by 0.41 needs five conversions before 0.42 reads all of it. They are performed by migrate-0.41-to-0.42.py, a one-shot script attached as an asset to the 0.42 release. Download it, run it once, and you are done with it.

This one stays a script, and 0.43’s own store migration does not replace it: 0.42 carried no migration code to reach back with, and conversion B below has to guess. 0.41 recorded nothing about which provider a thinking block came from, so the script tells them apart by the shape of the blob, and it reports what it read before it writes. A guess wants a human reading the counts, which is the one thing a migration that runs on every start cannot offer.

Order

1. Run 0.41 once, before you replace it. It brings a store from an older release fully up to date; 0.42 carries no migration code and cannot.
2. Install 0.42 and launch it once. This is what creates the tables the script writes into, so it is not an arbitrary step you can move: run the script against a store that predates 0.42 and it stops with an explanation rather than guessing.
3. Run the script, first as a dry run, then with --apply.

python3 migrate-0.41-to-0.42.py            # reports what it would change; writes nothing
python3 migrate-0.41-to-0.42.py --apply    # does it

Read the dry run before you apply it. Conversion B in particular reports how many thinking blocks it read as Claude’s and how many as OpenAI’s, and 0.41 did not record which was which. If those counts do not match the providers you actually used, stop: the blocks it could not place are left alone, but the ones it places wrongly are not recoverable from the row afterwards.

The dry run is the only place to read that. Its per-class counts and its warning about a session holding both kinds describe the write it is about to do, so once the blocks are converted a later run has nothing left to report about them.

Between steps 2 and 3 the store is live but incomplete: memories are absent from the agent’s index, and any session affected by conversion E below is already broken. Step 3 is part of the upgrade rather than cleanup to get to later.

The script finds meka’s own directories by default, honoring MEKA_CONFIG_DIR and MEKA_DATA_DIR; --root, --skills-root and --database point it at a copy instead. --self-test checks the script against its own fixtures and exits, touching nothing of yours.

What it converts

The two that matter

A and B announce themselves: a memory you saved is missing from the index, or a thinking block is not replayed. Both are recoverable by running the script later.

D and E are the ones that damage silently. D changes which skills the [Skills] index shows first and which its cap drops, with nothing on screen to say the rank it used was not the one in your file. E can leave a session unusable: it loads cleanly, and then the next turn is refused by the provider because a tool_use in the history has no matching result. See Sessions if you have already met that error.

Configuration overview

meka is configured with named accounts and profiles in a config file at ~/.config/meka/config.toml, plus secrets kept in the store. An account is where a request goes and who meka is when it arrives: a backend, an endpoint, and the credential a login produced. A profile is what meka asks that account for: a model and every model-tied setting. The quickest way to get started is to let the two command suites write both for you:

$ meka account add claude --backend claude-subscription
$ meka profile add work --account claude --model claude-opus-5-5

The first command writes an [accounts.claude] table to the config file, runs the OAuth login (or prompts for an API key, depending on the backend), and saves the secret to the store. The second writes a [profiles.work] table naming that account. With one profile configured, it is the default. The resulting config looks like:

default_profile = "work"

[accounts.claude]
backend = "claude-subscription"

[profiles.work]
account = "claude"
model   = "claude-opus-5-5"

See Config file for the full reference and the meka account and meka profile command suites.

Required settings

To run a turn, meka needs an active profile that names an account and a model, and a stored credential for that account. If no profile can be selected, or the active profile’s account has no credential, meka prints an error pointing at meka profile add / meka account login.

A profile is indivisible

A profile is a named bundle: the account it bills, the model, the profiles that stand in for it, and every model-tied setting (context_window, max_output_tokens, max_request_bytes, effort, vision, deferred_tools, thinking, thinking_budget, cache_control, thinking_display). A session selects one by name and records that name. Nothing overrides a field inside one.

There is deliberately no --model, --base-url, --thinking or --thinking-budget. A flag that moved one field of the bundle left the rest behind, so a session could run a 200K model while gauging its context against the 1M window its profile still stated, and never auto-compact.

To change a setting, edit the profile:

meka profile set work model claude-opus-5-5

To run something different, make a second profile on the same account and select it:

meka profile add fast --account claude --model claude-haiku-5-5 --context-window 200000
meka --profile fast -p "quick question"

Override layers

Profile selection is layered as follows; higher-priority layers override lower ones:

1. The session’s own row: the profile it was created with. A session that exists runs on what its row says, whatever default_profile later becomes.
2. --profile <name>: on a new session this chooses what the row records; on a resume it rewrites the row, so the change holds for every later turn and from every surface. See what a resume restores.
3. Config file: persistent accounts and profiles in ~/.config/meka/config.toml.
4. Built-in defaults: permission defaults to read, streaming defaults to on.

There is no environment-variable tier for accounts or profiles; an ambient OPENAI_API_KEY or MEKA_PROFILE has no effect (see Environment variables).

Credential resolution

The credential for a session’s profile is loaded from the store, keyed by the profile’s account name. It is acquired interactively:

• meka account add <name> runs the OAuth login (claude-subscription, chatgpt-subscription) or prompts for the API key (anthropic-messages, openai-chat-completions, openai-responses) when the account is created.
• meka account login <name> re-acquires it for an existing account (rotate an API key, recover from a dead OAuth refresh token), keeping every setting on the account and every profile on it. Add --api-key-stdin to pipe the key in for scripted rotation.
• meka account remove <name> deletes the stored credential and the account, once no profile names it.

Because secrets are keyed per account, two accounts on the same backend (for example, two Claude subscriptions) keep independent credentials, and every profile on one account shares its login.

Deleting an [accounts.<name>] block by hand removes the settings but not the secret, which stays in the store under that name. meka account list names any credential left that way, and meka account remove <name> deletes it; see Leftover credentials.

Why some settings have no config key

A few things are deliberately CLI-only, with no config.toml key and no environment variable. --additional-workspace-directory is the current example: which directories a run works in is a per-run scope, like the working directory itself, not a preference worth persisting. Writing it into a file would make the boundary depend on where the file lives rather than on what you asked for this time.

This is the same reasoning that keeps the working directory out of config, and it is the exception to “config.toml is the complete source of truth”: that rule covers persistent settings, and a per-run scope is not one.

When edits take effect

meka in the terminal reads config.toml and your instructions files at startup, so anything you change applies from the next command. A long-lived host is different: meka serve and meka acp read both once, when the process starts, and keep what they read for as long as they run.

Two consequences worth knowing:

• meka profile add or meka account add while a server is running does not reach it. The new entry is on disk and the listings show it, but POST /v1/sessions and ACP’s profile picker answer “not configured” until the server is restarted. The same applies to editing an existing profile or account. The one exception is a write meka serve made itself: an account or profile added, changed or removed through its own API is served from the next session on, because the server reads the whole file again after each write of its own, which also serves an edit made in a shell before it.
• Editing your instructions files does not reach it either. They are read once and go into the cached prompt prefix that every session shares. The same exception applies: instructions.md written through PUT /v1/instructions is read again by the server that wrote it, for the sessions that open from then on.

Restart the server to pick either up, or ask meka serve to read the file again with POST /v1/config/reload, which applies the accounts, profiles, MCP server entries and instructions.md as they stand, with [thinking] and [session].context_window, which complete the profiles, an MCP server’s credentials a shell stored, and [[serve.tokens]], and nothing else: not the [mcp] table’s own keys, nor any other section. A token removed or rescoped there applies to the next request, and a stream it holds open ends once the token no longer grants what the stream reads. Its answer, and GET /v1/config, name in restart_required the sections the file has changed since the server started that only a restart applies, and a reload refuses a file the server could not start on, naming the setting. Everything else follows a live source and needs no restart: skills are re-read per turn, memories per turn, and MCP tool lists follow the server.

A rotated credential sits between the two, and the distinction matters if you are rotating because a key leaked. meka account login <name> from a second process is picked up without a restart by anything that builds a provider after it: newly created sessions, ones the server re-attaches after eviction, and ones explicitly repinned by PATCH /v1/sessions/{id}, session/set_config_option or /profile.

A session already resident in memory holds the provider it was built with. For an API-key account that means it keeps presenting the old key until it is evicted ([serve] idle_timeout, 24 hours by default) or the server restarts. For the OAuth backends (claude-subscription, chatgpt-subscription) the live provider re-reads the stored bundle when it next refreshes its token, so a rotation is usually adopted sooner, but nothing makes that happen on demand.

To be certain a revoked credential is out of use, restart the host.

Config file

meka looks for a TOML configuration file at a platform-specific location:

The config file is optional. If it does not exist, meka silently skips it.

meka refuses unknown keys: a typo (contex_window) or a removed key (reasoning_effort) fails the load with an error naming the offending key, rather than being silently ignored. Fix or remove the key to continue.

The commands that edit the file are exempt, so a broken config can still be repaired from the CLI: meka mcp add / remove / enable / disable, meka account remove / rename and meka profile remove / rename work on the raw document and don’t care about an unknown key elsewhere in it. Everything that reads config fails instead of answering from empty defaults, because “No MCP servers.” over a file full of them is indistinguishable from the truth.

Those editors only reach the keys they own, so a bad key anywhere else ([session], [permissions], a top-level typo, a raw syntax error) has to be fixed in an editor. The error names the file, line, column, and offending key.

Set the MEKA_CONFIG_DIR environment variable to override the default location entirely. The value points at the meka directory itself (contains config.toml and skills/). Useful for tests, portable installs, and isolating a per-project config from your global one.

The directory holds two more things that are not config keys. Standing instructions live at a conventional path beside the file, because prose long enough to be worth writing is miserable to maintain inside a TOML string, and skills have a directory of their own:

~/.config/meka/
├── config.toml
├── instructions.md      # or instructions/*.md
└── skills/

Write instructions.md, or split a large set across instructions/*.md, and meka reads it at startup into the ## Standing instructions section of the system prompt; see Instructions. To pass the text as a string instead (containers, CI), use MEKA_INSTRUCTIONS, MEKA_INSTRUCTIONS_FILE, or --instructions. Files beyond that path, a project’s AGENTS.md for one, are named under [instructions].

Everything in that directory is content you put there, so it is safe to keep under version control. Commands that edit the config take a cross-process lock on the directory itself, as does claiming a skill store, so neither leaves a lock file behind; a write is published by renaming a short-lived config.toml.<pid>.<seq>.tmp over the target, so that name can appear for the duration of one write. If you are upgrading from a version that wrote .config.toml.lock, or .meka-store.lock inside a skill store, delete them: nothing reads or writes them any more.

Windows still writes both, because its file locks are mandatory rather than advisory: a lock held on config.toml would make the file unreadable to the command holding it, and LockFileEx refuses a directory handle outright. If you keep a meka config directory under version control on Windows, ignore .config.toml.lock and skills/.meka-store.lock.

The sections below are in the order a file is best written in: the blocks with many entries first (default_profile, accounts, profiles, MCP servers), then each single table from the most to the least consequential, and [serve] last.

Accounts and profiles

Where a request goes and what it asks for are configured separately. An account is a backend, an endpoint and the credential a login produced: [accounts.<name>] in config.toml, with the secret in the store under the same name. A profile is an account plus a model and every model-tied setting: [profiles.<name>]. A session records the profile it runs on; the profile names its account. Two profiles on one account share one login; one account on two endpoints is two accounts.

Secrets are never stored in the config file. API keys and OAuth token bundles live in the store, keyed by account name, and are acquired through the meka account command suite (meka account add runs the API-key prompt or the OAuth login for you). The config file holds only the non-secret settings shown below.

default_profile = "work"

[accounts.claude]
backend = "claude-subscription"

[accounts.ollama]
backend  = "openai-chat-completions"
base_url = "http://localhost:11434/v1"

[profiles.work]
account = "claude"
model   = "claude-opus-5-5"

[profiles.fast]
account        = "claude"
model          = "claude-haiku-5-5"
context_window = 200000

[profiles.local]
account = "ollama"
model   = "llama3"

Selecting the active profile

For each run meka picks one profile using this precedence:

1. --profile <name> CLI flag.
2. default_profile in the config file.
3. The sole profile, if exactly one is configured.

If none of these resolve (no profiles configured, or more than one with no default_profile / --profile), meka errors and points you at meka profile add / meka profile use. Resuming a session is the exception: it runs on the profile it recorded and never consults this, so an ambiguous default does not block meka -c. meka serve is the other: it starts, and refuses the POST /v1/sessions that names no profile with the same sentence, since each of its sessions may name its own. There is no environment-variable tier for profile selection; the config file (plus the per-run CLI flag) is the source of truth.

Timeouts

Every backend connects with a 30-second handshake deadline and fails a stream that produces nothing for five minutes, which surfaces as a retryable error rather than a hung turn.

Neither is a limit on the turn. There is deliberately no cap on how long a turn may run, how many tool calls it may make, or how many tokens it may spend: those ceilings belong to your API key and your provider plan, not to the harness. What these bound is silence. A model that is still thinking is still sending, so a stream that goes quiet for five minutes has died, and waiting on it forever is not patience.

A whole reply (--no-stream, and the summary a compaction asks for) is silent until it is finished, so it gets no clock at all: a reply may take as long as it takes. A connection whose peer has gone is found by TCP and HTTP/2 keepalives instead, which a busy server answers and a vanished one does not, so a dropped route still surfaces as an error within a minute or two. A peer that is up and never answers is not found this way: such a request waits until it is canceled, which is the trade a base_url behind a gateway with no timeout of its own makes. A cancel drops a pending reply at once, in either mode.

default_profile

Top-level field naming the profile to use when --profile isn’t passed. Set it with meka profile use <name>. A sole profile is the default by the selection rule, so the first meka profile add leaves the key unset; the second names the profile that was alone, so the default stays where it was.

Account fields

backend

The driver the account uses (required).

An API-key backend is named for the protocol it speaks, because base_url decides the endpoint and the same protocol is served by many vendors. A subscription backend is named for the product, because the endpoint is fixed and what the account holds is a billing relationship. See Providers overview for which servers implement which protocol.

base_url

Custom API base URL. Useful for:

• Self-hosted models via Ollama (http://localhost:11434/v1)
• OpenRouter (https://openrouter.ai/api/v1)
• Other OpenAI-compatible API providers

If not set, defaults to:

• https://api.openai.com/v1 for the openai-chat-completions and openai-responses backends
• https://chatgpt.com for the chatgpt-subscription backend (request path is /backend-api/codex/responses)
• https://api.anthropic.com for the anthropic-messages and claude-subscription backends

Set it with meka account add <name> --base-url <url>, or edit the account table by hand.

The URL is used as given. An endpoint that answers with a redirect is refused, naming the location it pointed to, rather than followed, so a credential never leaves the host you configured; set the final URL.

The two API families end their base URL in different places, and that is not meka’s choice. An OpenAI-compatible base includes the version segment, which is why every provider documents one ending in /v1 and why meka appends only /chat/completions. A Claude base is the host root, because meka reaches two different roots off it: /v1/messages for the turn, and /api/oauth/... for the subscription usage and profile endpoints. A base ending at /v1 could not reach the second set. The official SDKs draw the line the same way.

A gateway that fronts both APIs therefore publishes two URLs, and its Anthropic one is often written with the /v1 its OpenAI sibling needs (https://api.synthetic.new/anthropic/v1). Paste it as-is: for an anthropic-messages or claude-subscription account meka drops a trailing /v1, since it re-adds that segment on every request and the alternative is a request to /v1/v1/messages. Only a trailing one goes, so a base whose path legitimately contains /v1 earlier (https://gateway.ai.cloudflare.com/v1/{account}/{gateway}/anthropic) is left alone. Trailing slashes are trimmed for every backend.

The reverse is not inferred: an openai-chat-completions base is used exactly as written, because a gateway serving /chat/completions at its root is legitimate and meka cannot tell that apart from a missing /v1. If an OpenAI-compatible endpoint 404s, check that the base carries the version segment its documentation shows.

oauth_token_url

The OAuth token endpoint meka posts to, for the initial code exchange at meka account add / login and for every refresh thereafter. Both, not just refreshes: it overrides a constant, so it overrides it everywhere that constant is used. Defaults:

• https://platform.claude.com/v1/oauth/token for claude-subscription
• https://auth.openai.com/oauth/token for chatgpt-subscription

It exists because that endpoint is the provider’s fact, not meka’s, and a value baked into the binary either goes stale or sits on the far side of a proxy your network makes you use. Set it with client_id when your route out needs both.

There is deliberately no authorize_url to go with it, and the asymmetry is not an oversight: meka never requests the authorization URL, it hands it to your browser, so an egress proxy is never in that path. The two legs meka makes itself are the code exchange and the refresh, and this covers both.

client_id

OAuth client id override (advanced; claude-subscription / chatgpt-subscription only). Leave unset to use meka’s built-in default client ids.

interleaved_thinking

Whether the endpoint takes the interleaved-thinking beta header, which anthropic-messages sends whenever thinking is on. Unset is true, which is what Anthropic’s own API needs to think between tool calls; an endpoint that refuses the header sets it false. The other backends never read it, and meka account add --interleaved-thinking refuses it for them. The other switch an endpoint decides, the cache breakpoint, is a profile field, because its answer varies by model on a gateway; see cache_control.

[accounts.gateway]
backend = "anthropic-messages"
base_url = "https://gateway.example.test"
interleaved_thinking = false

prompt_cache_key

openai-responses only. Whether the request carries prompt_cache_key, OpenAI’s hint for routing one conversation’s requests to the cache holding its prefix; meka sends the session’s id, as chatgpt-subscription does. Unset is true, which is what OpenAI’s own API takes. An endpoint that refuses the field sets it false; most servers ignore a field they do not know.

stream_usage

openai-chat-completions only. Whether a streamed request asks for its usage with stream_options.include_usage, without which OpenAI’s own API reports none and the context gauge and automatic compaction read zero. Unset is true. An endpoint that refuses the field sets it false, and its usage is then whatever it reports unasked (OpenRouter reports it either way).

[accounts.strict]
backend      = "openai-chat-completions"
base_url     = "https://llm.example.test/v1"
stream_usage = false

max_tool_name_bytes

anthropic-messages, openai-responses and openai-chat-completions only. The longest tool name the endpoint takes, in bytes. Unset is the wire’s own limit as its owner documents it: 128 on the Messages and Responses APIs, 64 on Chat Completions. A namespaced MCP tool name longer than this is sent cut to it, ending in a hash of the whole name, and read back as the whole name. A gateway that holds names to less states what it holds them to; at least 16, which a cut name needs.

device_id

claude-subscription only. Stable per-device identifier embedded in metadata.user_id to mirror Claude Code’s ~/.claude.json device id (getOrCreateUserID in utils/config.ts).

If unset, meka first tries to adopt userID from ~/.claude.json (so meka and Claude Code on the same machine look like the same device). If that file is missing or has no userID, meka generates a 64-character hex string. Either way, the resolved value is persisted back to the account under [accounts.<name>].device_id, the first time a process reads the account: at startup, or when meka serve serves the file after a write or a reload. This file write only happens for the claude-subscription backend; other backends don’t need a device id.

You can supply your own value if you want to control attribution explicitly:

[accounts.work]
backend   = "claude-subscription"
device_id = "your-stable-id-here"

Profile fields

account

The account the profile bills (required). Must name an [accounts.<name>] table; a profile whose account is missing is refused by name when a session tries to run on it, and meka profile list says so.

model

The model identifier to send to the provider, forwarded verbatim. Optional in the file, but a session cannot run without one: a profile that names no model is refused by name when a session tries to run on it. meka does not gate which strings are valid, so an OpenAI-compatible endpoint accepts whatever that server exposes.

meka profile add suggests claude-opus-5-5 for a profile on a Claude account and gpt-6-astra for one on an OpenAI account. For the current line-ups, see Anthropic’s models overview and OpenAI’s models overview; naming them here would go stale on someone else’s schedule.

Change it with meka profile set <name> model <value>.

fallbacks

Profiles to serve a turn from when this one cannot, in order of preference: list the profile you would rather run on first, since every turn starts on the first profile, this one included, whose upstream is not known to be down, and a switch rebuilds the prompt cache at the new profile once. A turn falls back when the profile’s upstream is still failing once the retry budget is spent (an outage, a rate limit, a dropped stream), or when it refuses for quota or billing by a signal it documents (a 402, a quota code on a 429, the Claude subscription’s exhausted window). It does not fall back on a context overflow, an invalid request, a tool refusal or an authentication failure, which another profile would not fix. The whole profile is swapped, so no setting of this one is ever mixed with another’s. Each fallback must be able to carry the sessions of the profile it backs: the same vision, and a context_window and max_request_bytes no smaller, each resolved as a session resolves it. A larger window or cap on a fallback is never drawn on: while a fallback serves, the session keeps gauging against its own profile’s window, so when it compacts does not depend on who answered.

The session keeps naming this profile. A fallback serves one turn, the rest of that turn stays on it, and the next turn starts here again, or on the first fallback whose upstream is not known to be down: a profile that failed over is skipped for five minutes, or until the upstream’s stated reset when that is sooner, never longer. Once a turn is running, a failure moves it to the next profile in the list it has not tried, so it fails only when every one has refused it. What served a turn is on its record (profile on GET /v1/sessions/{id}/turns and on turn.finished) and in a notice on the feed and the screen. See Fallback profiles.

Each entry must name another configured profile, once. meka profile remove refuses a profile another’s fallbacks names, and meka profile rename moves the name.

[profiles.main]
account   = "anthropic"
model     = "claude-opus-5-5"
fallbacks = ["backup"]

[profiles.backup]
account = "openrouter"
model   = "anthropic/claude-sonnet-4-5"

Change it with meka profile set <name> fallbacks backup,last-resort (comma-separated), or --unset to remove it. meka profile add takes --fallback <name>, repeatable.

context_window

The model’s context window (total tokens it can hold), used for the /status gauge and auto-compaction. Takes precedence over [session].context_window; when neither is set, meka assumes 1000000.

meka never infers this from the model name and never asks the provider for it, so this is where a model smaller than the default gets stated. It is a local budgeting number that is never sent on the wire, so a wrong value can’t fail a request, but leaving it at 1M for a smaller model means planned compaction never fires, and every compaction instead happens after the provider rejects the request as too large, costing a wasted round trip each time.

The window belongs to the session, not to the process: each session is measured against the profile it recorded, so two sessions in one meka serve can sit on profiles with different windows.

[profiles.work]
account        = "openai"
model          = "my-128k-model"
context_window = 131072

max_output_tokens

Override the per-request output (completion) token cap. When unset, each backend keeps its built-in default:

The Claude figures are meka’s own defaults for the two Anthropic backends. The adaptive one is what Claude Code 2.1.310 sends for Opus 5.5, the model meka profile add suggests, and the most any model that takes adaptive thinking accepts; Claude Code’s per-model catalog says the same for Sonnet 5.5 and Haiku 5.5 and 64000 for the rest of the line-up, and stating a figure here replaces the default. The OpenAI backends send no cap unless the profile states one, because each reaches whatever base_url names and the endpoint’s default is that endpoint’s fact.

Under thinking = "budgeted" the value must exceed the profile’s resolved thinking budget (thinking_budget, else [thinking].budget, else 16000). meka profile add and meka profile set both refuse a profile that fails this, and it is validated again at startup.

[profiles.work]
account           = "anthropic"
max_output_tokens = 16000

max_request_bytes

Largest request body, in bytes, before the oldest tool-result images are redacted to fit; a body that still does not fit is refused, and the turn retries without its newest attachments. Unset, the Anthropic backends use 31457280 (30 MiB), which is Anthropic’s 32 MiB cap less headroom, and the OpenAI backends apply no ceiling until one is stated: their endpoints’ caps are the endpoints’ own facts. An account reaches whatever its base_url names, so a profile on an endpoint with a smaller cap states it here. Redaction removes tool-result images, oldest first; an image attached to the newest message is never removed, and a body that still does not fit is refused so the turn can degrade its own attachments instead. openai-chat-completions never sends tool-result images (that API’s tool messages are text), so there the ceiling only refuses. The Anthropic backends also send at most 100 images in one request, the Messages API’s own limit, redacting the oldest past it the same way.

[profiles.local]
account           = "gateway"
max_request_bytes = 8388608

effort

One knob for reasoning effort across every backend: Claude sends it as output_config.effort (claude-subscription under the effort-2025-11-24 beta, anthropic-messages directly), openai-chat-completions as reasoning_effort (with max_completion_tokens for the output cap), and the two Responses backends as reasoning.effort (with max_output_tokens).

When unset the field is omitted, and the provider applies its own default. claude-subscription is the exception: it sends medium, Claude Code’s default for Opus 5.5. That is the point of leaving it unset: effort is a request parameter the provider owns, and omitting it is how you ask for whatever that provider considers right. meka picks no tier of its own, because it cannot know which tiers a given endpoint implements: anthropic-messages and openai-chat-completions reach any compatible server, including local ones serving weights that never had a reasoning knob, and a tier the backend doesn’t implement is a rejected request rather than a graceful ignore.

An explicit value is absolute: sent verbatim (trimmed and lowercased), with no validation or clamping, whatever model it is aimed at. You own correctness for your model and endpoint; an invalid value is rejected by the API. A blank value reads as unset.

Typical values: low, medium, high, xhigh, max.

[profiles.work]
account = "anthropic"
effort  = "xhigh"

vision

Whether this profile’s model accepts image input. Defaults to true. Set false for a text-only model so attachments are refused rather than sent to a model that cannot read them. A turn on such a profile is refused, before anything is sent, while the session’s history holds an image: switch the session to a profile with vision. A profile’s fallbacks share its vision, so a fallback never meets that refusal.

Refusal is per session, from the profile that session recorded, on both ACP and POST /v1/sessions/{id}/turn. What ACP advertises in promptCapabilities.image is necessarily per connection: initialize is answered before any session exists, so it reports the default profile’s flag. A client on a vision-capable connection can still have its attachment refused by a session pinned to a text-only profile. See ACP.

[profiles.local]
account = "ollama"
model   = "llama-3-8b"
vision  = false

deferred_tools

How a request carries the tools the agent has not loaded: native or append. Every backend but openai-chat-completions reads it. Under append a deferred tool is absent from the request until tool_load adds its schema to the tools array; the array heads the cached prefix, so the request after a load rewrites the whole cache once. Under native every deferred tool is declared from the first request with defer_loading, the array never changes, and tool_load and tool_search answer with a reference the endpoint expands in place: Anthropic’s tool_reference block on anthropic-messages and claude-subscription; on openai-responses and chatgpt-subscription the endpoint’s own tool_search item, which replaces the two discovery tools there and takes a query to find or a list of names to load. Unset is native on the two subscription backends and on anthropic-messages and openai-responses without a base_url, and append elsewhere: a gateway that ignores defer_loading accepts it silently and shows the model every deferred schema from the first request, which costs more than append and is invisible. Whether a gateway honors it varies by model and by the upstream it routes a request to, so check a profile before setting native on it: a deferred tool called with the right arguments and no load means the schema was shown. See Deferred tools for the cost model and for deferral, the registry setting that decides which tools are deferred at all.

[profiles.claude-via-openrouter]
account        = "openrouter"
model          = "anthropic/claude-opus-5-5"
deferred_tools = "native"

thinking

Claude-only. How the request encodes extended thinking, and whether it asks for it at all:

One knob rather than two: it replaces both the old on/off switch and the encoding meka used to infer from the model name. The right value depends on the model and on what the endpoint implements, which meka can’t determine, so the profile states it, and a profile whose model later changes is yours to keep correct.

[profiles.local]
account  = "gateway"
thinking = "budgeted"

thinking_budget

Tokens the model may spend thinking. Read only under thinking = "budgeted"; the other two settings send no budget at all. A profile that states none falls back to [thinking].budget, and then to 16000.

Per profile because it is a parameter of thinking, and thinking is per profile. It was one installation-wide value until 0.44, which meant a profile could be refused over a number stated nowhere in it, and told to fix it by lowering a global every other profile was also budgeting against. Under thinking = "budgeted" this profile’s max_output_tokens must exceed the resolved budget, and the remedy now names this profile’s own keys.

[profiles.work]
account         = "anthropic"
thinking        = "budgeted"
thinking_budget = 20000

cache_control

anthropic-messages only. Whether each request carries the moving cache_control breakpoint on the last block it sends. Unset is true, which is what Anthropic’s own API needs to cache the prompt incrementally: the breakpoint moves with the conversation, and each turn is billed a write for the new suffix alone. What an endpoint does with the breakpoint is the endpoint’s fact, and on a gateway it varies by model, which is why this sits on the profile rather than beside interleaved_thinking on the account. OpenRouter turns it into Gemini explicit caching, which bills a write of the whole prompt on every turn the breakpoint moves, so a Gemini profile there pays more with the breakpoint than without it. The symptom in the usage is a cache write equal to the cache read on every turn with no live input, and a /status gauge at twice the real occupancy, since the two tiers are counted as separate tokens. Such a profile sets false, which sends no breakpoint at all and leaves the endpoint’s own implicit caching to work; a Claude model on the same account keeps the default. The other backends never read it: claude-subscription pins its own breakpoint and the OpenAI wires have none, so meka profile add --cache-control is dropped for them and meka profile set refuses it.

[profiles.gemini]
account       = "openrouter"
model         = "google/gemini-3.8-flash"
cache_control = false

thinking_display

claude-subscription only. How the model’s thinking is presented, one of Claude Code’s three display modes:

• summarized (the default): the server streams a short summary of the reasoning, shown as thinking text (a dimmed preview row, the whole summary when expanded). Sent as thinking.display = "summarized", which is what Claude Code sends with its showThinkingSummaries setting on.
• updates (Claude Code’s own default): the server streams a running token count in place of the text, and the screen draws • Thinking · 150 tokens from it, redrawn as the count climbs and left on screen when the phase ends. Sent as thinking.display = "updates" under the thinking-display-updates-2026-08-18 beta.
• redacted: the server withholds the text and may return opaque redacted_thinking blocks. Sent as the redact-thinking-2026-02-12 beta with no display field.

Every mode returns signed thinking blocks, which meka stores and replays verbatim, so multi-turn continuity holds in all three. With thinking off there is nothing to display, and meka sends the redaction beta as Claude Code does.

[profiles.work]
account          = "anthropic"
thinking_display = "updates"

encrypted_reasoning

openai-responses only. Whether the request asks for the model’s reasoning sealed, with include: ["reasoning.encrypted_content"], and sends it back on the turn’s later requests, so the model reasons on between its own tool calls rather than starting over at each. Defaults to true, what OpenAI’s own API carries for a reasoning model. A model or endpoint that refuses the field sets it false: OpenAI’s API refuses it for a model that does not reason, such as gpt-4.1 or gpt-4o, with Encrypted content is not supported with this model naming include. Reasoning goes back only to the endpoint that sealed it: a session that ran on another endpoint, chatgpt-subscription included, keeps its reasoning on that endpoint.

reasoning_summary

openai-responses only. Whether the request asks for reasoning.summary, the digest of the model’s reasoning meka shows as its thinking. Defaults to true. A model or endpoint that refuses the field sets it false, as a model that does not reason does on OpenAI’s API, and the thinking then shows only what the endpoint streams unasked (vLLM and Ollama stream their reasoning text either way).

[profiles.gpt41]
account             = "openai"
model               = "gpt-4.1"
encrypted_reasoning = false
reasoning_summary   = false

[mcp]

Which MCP servers to connect to, and what their tools are allowed to do. The MCP page covers the rest: the meka mcp command suite, where a server’s secrets live, the OAuth flows, the connection lifecycle, and the resource and prompt tools.

[mcp] top-level table

[[mcp.servers]]

An array of MCP server configurations. Each entry defines a server to connect to at startup.

Permission resolution

Every MCP tool’s required permission is resolved through a five-step chain; the first match wins:

1. server.tool_permissions[<raw-tool>]: explicit per-tool override.
2. server.permission: explicit server-level override. Applies to every tool on that server regardless of what the server advertises.
3. tool.annotations.readOnlyHint from the server: true → Read, false → Unrestricted. The true half is skipped when the server sets trust_read_only_hint = false, and a hint skipped that way also bypasses step 4, landing on step 5.
4. [mcp].default_permission: global fallback. Not consulted for a hint that step 3 refused.
5. Hardcoded Unrestricted: strict ultimate fallback.

User-supplied config (1, 2, 4) always beats the server’s self-classification; if a server lies about a tool, you can override. But when no user config says anything, the server’s hint is trusted for that specific tool so readOnlyHint = false destructive tools don’t silently become Read-accessible just because the user opted into a lenient global default.

Hint spoofing: readOnlyHint is asserted by the server and not verified by meka, and MCP tools run in the server’s own process with no sandbox. A server that claims readOnlyHint = true for a tool that in fact writes therefore gets to write your tree while meka sits at read: MCP tools are outside the read filesystem boundary that covers meka’s built-ins (see Permissions).

Three defenses, in increasing order of bluntness:

• tool_permissions on the specific tools you want pinned (step 1 wins).
• trust_read_only_hint = false on the server, which makes its hints advisory for display only. A refused hint drops straight to the strict unrestricted fallback, deliberately skipping [mcp].default_permission: that key is a global default, and letting it answer would mean default_permission = "read" silently re-granting exactly what the per-server flag refused. None of that server’s hinted tools is reachable at read without an explicit override.
• server.permission = "unrestricted" on the whole server (step 2 wins), or disabled_tools to remove the tool entirely.

The hint is trusted by default because most servers annotate honestly and requiring per-tool config for every server would make read impractical. trust_read_only_hint is the switch for a server you have not audited.

Stale config: entries in allowed_tools / disabled_tools / eager_load_tools / tool_permissions that don’t match any advertised tool get a warn! line at connect time. The server still connects; you just see a heads-up so you can clean up after the server renames a tool. A name that appears in both eager_load_tools and disabled_tools also warns: the disabled filter wins, so eager-loading the disabled tool is a no-op.

Visibility across levels: the resolved permission doesn’t hide a tool from the agent. Every registered tool is listed in the per-turn context with its required level noted inline, and a [Permission context] section names the current level and whether approvals are on (what each level allows is stated once in the system prompt, and the per-tool levels are in the catalog above it). The agent can still reason about an inaccessible tool and suggest /permission <level> to enable it; the permission gate is enforced at dispatch time. Keeping the tool catalog visible across levels is also what lets the Claude prompt cache survive mid-session permission toggles.

The stdio server’s environment

A stdio server is a child process that talks to the network, and it does not inherit meka’s environment. It receives the same curated base a shell at read gets (PATH so it can resolve its own binaries, HOME, locale, TMPDIR), plus whatever the server’s own env table sets.

Configuring a server is a decision to run its code, not a decision to hand it every credential on the machine: without this, ANTHROPIC_API_KEY, AWS_* and GITHUB_TOKEN all rode along into every server you had ever added.

The base also carries the machine’s network configuration (HTTP_PROXY, HTTPS_PROXY, NO_PROXY, SSL_CERT_FILE, SSL_CERT_DIR, NODE_EXTRA_CA_CERTS and the usual siblings), because a server that cannot see them connects to nothing behind a corporate proxy and fails every call with an error naming none of the cause. Those say where to go and whom to trust; they grant nothing.

Three families are deliberately left out and have to be requested per server: SSH_AUTH_SOCK, which is a live credential agent; NODE_OPTIONS, which takes --require and therefore arbitrary code; and the import paths PYTHONPATH / NODE_PATH / VIRTUAL_ENV, which change what a program loads. A server that genuinely needs one takes it explicitly:

[[mcp.servers]]
name = "tooling"
transport = "stdio"
command = "my-tooling-server"
env = { PYTHONPATH = "${PYTHONPATH}" }

A server that genuinely needs a secret asks for it by name, and ${VAR} still reads meka’s environment at connect time:

[[mcp.servers]]
name = "github"
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "${GITHUB_TOKEN}" }

Examples

Exa: web search, which meka has no built-in tool for. The free tier works without an API key; paste a key into the headers table for the paid tier:

# Free tier, no key required
meka mcp add exa https://mcp.exa.ai/mcp

# Paid tier, expands from EXA_API_KEY at connect time
meka mcp add exa https://mcp.exa.ai/mcp --header "x-api-key=${EXA_API_KEY}"

Well-annotated server: no config needed. Every tool is classified by its own readOnlyHint (read tools Read, write tools Write):

[[mcp.servers]]
name = "notion"
transport = "http"
url = "https://mcp.notion.com/mcp"

User-declared trust on an unannotated server (all tools accessible in Read):

[[mcp.servers]]
name       = "internal"
transport  = "http"
url        = "https://mcp.internal/…"
permission = "read"

Overriding a mis-annotated or distrusted tool (one specific tool requires unrestricted):

[[mcp.servers]]
name      = "notion"
transport = "http"
url       = "https://mcp.notion.com/mcp"

[mcp.servers.tool_permissions]
"notion-do-something-scary" = "unrestricted"

Subset of a server’s tools (only query registers, all others are ignored):

[[mcp.servers]]
name          = "pg"
transport     = "stdio"
command       = "npx"
args          = ["-y", "@modelcontextprotocol/server-postgres"]
allowed_tools = ["query"]

Block-list with a narrow exception (all fs tools are Read-accessible except the two destructive ones, which are never registered):

[[mcp.servers]]
name           = "filesystem"
transport      = "stdio"
command        = "npx"
args           = ["-y", "@modelcontextprotocol/server-filesystem"]
permission     = "read"
disabled_tools = ["delete_file", "move_file"]

MCP tools are registered with namespaced names in the format servername__toolname to prevent collisions with built-in tools or between servers.

Tool and resource descriptions returned from MCP servers are truncated at 2048 characters to keep the rendered catalog bounded.

Environment variable substitution

Every string field listed above (command, args, env values, url, headers values, headers_helper) supports ${VAR} and ${VAR:-default} expansion from the process environment. A missing variable with no default is logged at startup. In command or headers_helper it is left literal, naming a program that will not be found; in args, env, url or headers, which reach the other side, it fails closed instead: the server is marked failed and never connected, so a literal Bearer ${TOKEN} or ?key=${KEY} is not sent to anyone. A reference the grammar does not accept (an unclosed ${, an empty name, a default that opens another reference) is treated the same way. A $NAME without braces is not a reference and is passed through, for a child shell to expand. Use this to avoid committing secrets:

[[mcp.servers]]
name = "github"
transport = "http"
url = "https://mcp.github.com"
headers = { X-Api-Key = "${GITHUB_MCP_TOKEN}" }

env, args and headers may contain a secret, but they are not one: env sets a subprocess’s whole environment, args carries connection strings, and headers carries X-Tenant-Id as readily as X-Api-Key. meka cannot tell which is which, so they stay in config.toml and ${VAR} is how you keep a value out of it.

A bearer token and an OAuth client secret are unambiguously secrets, so they are not config at all. They live in the store and are set with meka mcp add --auth-token-stdin / --client-secret-stdin, or afterwards with meka mcp login. See Credentials.

A stored credential is bound to the url it was stored for, ${VAR} expanded, and presented there alone: an OAuth login’s tokens to that exact URL, the resource they were issued for, and a bearer or a client secret anywhere on its scheme, host and port. Point url at another host and the server stops presenting what it holds, and fails to connect saying so, until it is logged in or given its secret again; meka mcp get lists what it holds for another endpoint. A ${VAR} in url that the environment leaves unset binds nothing: storing a secret for the server is refused where it is unset.

[mcp.servers.auth]

OAuth authentication for HTTP MCP servers. Set type to choose the authentication method. This is mutually exclusive with a stored bearer token. Every token request names the server’s own url as its resource (RFC 8707), as the MCP authorization spec requires, so no key states it.

The client secret is not a field here. It is a secret, so it lives in the store: set it with meka mcp add --client-secret-stdin or meka mcp login <name> --client-secret-stdin. See Credentials.

Examples

Stdio server

[[mcp.servers]]
name = "postgres"
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
permission = "unrestricted"

HTTP server

[[mcp.servers]]
name = "web-tools"
transport = "http"
url = "http://localhost:8080/mcp"
permission = "read"

HTTP server with authentication

The bearer token is not in the file. Store it once with meka mcp add api https://api.example.com/mcp --auth-token-stdin, or meka mcp login api --auth-token-stdin for a server that already exists.

[[mcp.servers]]
name = "api"
transport = "http"
url = "https://api.example.com/mcp"
permission = "unrestricted"

[mcp.servers.headers]
X-Custom-Header = "value"

Stdio server with environment variables

[[mcp.servers]]
name = "github"
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
permission = "read"

[mcp.servers.env]
GITHUB_TOKEN = "ghp_..."

Multiple servers

[[mcp.servers]]
name = "filesystem"
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
permission = "read"

[[mcp.servers]]
name = "github"
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
permission = "unrestricted"

HTTP server with OAuth client credentials

[[mcp.servers]]
name = "api"
transport = "http"
url = "https://api.example.com/mcp"
permission = "unrestricted"

[mcp.servers.auth]
type = "client_credentials"
client_id = "my-client-id"
scopes = ["read", "write"]

client_credentials needs a client secret, which is stored rather than written here: pass --client-secret-stdin to meka mcp add, or meka mcp login api --client-secret-stdin afterwards.

HTTP server with JWT client credentials

[[mcp.servers]]
name = "api"
transport = "http"
url = "https://api.example.com/mcp"

[mcp.servers.auth]
type = "client_credentials_jwt"
client_id = "my-client-id"
signing_key_path = "/path/to/private-key.pem"
signing_algorithm = "RS256"
scopes = ["admin"]

HTTP server with OAuth authorization code flow

On first connection, meka opens a browser for authorization and stores the token for future use.

[[mcp.servers]]
name = "github-mcp"
transport = "http"
url = "https://mcp.example.com"

[mcp.servers.auth]
type = "oauth"
client_id = "my-app-id"
scopes = ["repo", "user"]
redirect_port = 8400

If client_id is omitted, meka attempts dynamic client registration with the server.

[permissions]

Controls which permission levels are reachable at runtime and which level the session starts at. See the Permissions page for what each level does.

A level meka does not have is refused at parse, with the line. An enabled list that names nothing falls back to read alone, with a warning, rather than to the default set, so an empty list cannot widen authority. If default is not in enabled, meka logs a warning and falls back to read if it’s enabled, otherwise the lowest enabled level (in none → read → workspace → unrestricted order). Same behavior if --permission or MEKA_PERMISSION selects a disabled level: meka warns and starts at the configured default rather than refusing to launch.

[permissions]
default = "read"
enabled = ["none", "read", "workspace", "unrestricted"]
approvals = true     # ask me about anything above the level instead of refusing it
confine_reads = true # reads stay within the roots, as writes do at workspace
network = "none"     # cut off the network; "remote" keeps other machines reachable

[shell]

Settings for shell command execution.

shell.sandbox

Whether to enable read-only filesystem sandboxing for shell commands at read. When enabled (default), shell commands can be executed at read and workspace but with the filesystem write-protected outside the workspace roots. When disabled, shell commands require unrestricted.

Default: true

[shell]
sandbox = false  # disable the sandboxed shell at read

The sandbox uses Bubblewrap or Landlock on Linux, sandbox-exec on macOS, and an AppContainer or a restricted token on Windows, chosen by shell.sandbox_backend where the platform has a choice. On platforms where no backend is usable, shell commands always require unrestricted regardless of this setting.

shell.sandbox_backend

The mechanism a confined command runs under. Each platform takes its own values, and a value from another platform is refused where it would be used: shell_execute at read fails and startup warns, naming the values this platform takes. A config.toml shared across machines leaves the key unset or sets it per machine through MEKA_SANDBOX_BACKEND. macOS has one backend, sandbox-exec, and takes no value.

Linux takes "bubblewrap", "bubblewrap-landlock" and "landlock":

• Bubblewrap ("bubblewrap") wraps the command in bwrap with read-only bind of /, tmpfs masks over /run / /tmp / /var/tmp / $XDG_RUNTIME_DIR, and --unshare-user --unshare-pid --unshare-uts --unshare-ipc. The tmpfs masks hide the dbus session bus and the systemd-user socket, so state-changing IPC calls like systemctl --user start and dbus-send fail. Network is intentionally not unshared so curl http://x | pdftotext still works. On a kernel with Landlock ABI v6 (6.12) or newer the command also runs inside meka’s Landlock ruleset, enacted by meka confine after the mounts, which closes the abstract namespace, signals and device ioctls, and from kernel 7.1 the sockets the masks do not cover. Requires the bubblewrap package and a kernel with user-namespace creation enabled.
• Bubblewrap with Landlock ("bubblewrap-landlock") is Bubblewrap with the Landlock layer inside required rather than added where the kernel allows: on a kernel below 6.12 the backend is unusable and shell_execute at read fails, so a pinned value guarantees the layer is applied. What the layer closes still follows the kernel: the abstract namespace, signals and device ioctls from 6.12, sockets on disk outside the masks from 7.1. Auto-detection never picks it; pin it on a host where that guarantee matters more than a working shell.
• Landlock ("landlock") uses the Landlock LSM to block filesystem writes, and requires ABI v9 (kernel 7.1+): the first ABI that can refuse connect() to Unix sockets on disk, which is the dbus / systemd-user route out of the sandbox. On an older kernel meka reports the backend unusable rather than leave that door open; install Bubblewrap there. Closing it also costs socket-based clients like docker and psql at read. meka’s own directories are hidden by per-sibling read grants, and each command gets a private temporary directory named by TMPDIR. No ABI mediates file metadata, so chmod, chown, touch and setxattr still succeed at read; that is what the startup warning names.

Windows takes "appcontainer" and "restricted-token":

• AppContainer ("appcontainer") runs the command inside a process security environment the OS enforces, on a Windows 11 build that has the API: 26H2, where meka measured it, and 24H2 and 25H2 from the August 2026 update, where Microsoft lists it. meka’s config directory and store are denied, the read boundary holds for the shell as it does for the file tools, network = "none" cuts a command off, and nothing is written to your directories’ ACLs. See Shell for what it covers and its limits.
• Restricted token ("restricted-token") runs the command under a token derived from meka’s own: Low integrity at read, write-restricted to the workspace roots at workspace. It confines writes only: a command can read meka’s store, confine_reads holds for the file tools alone, and network = "none" for web_fetch alone. That is what the startup warning names when it is the automatic choice.

When omitted, meka probes the platform’s stronger backend once at startup, Bubblewrap on Linux and AppContainer on Windows, and auto-picks it when usable; AppContainer counts as usable at schema 1.1, and a build whose API speaks 1.0 is named in the warning, since pinning "appcontainer" takes it there with network = "host" held as "remote". Otherwise it auto-picks the fallback, Landlock or the restricted token, and emits a one-shot warning naming what the fallback gives up. Set the field explicitly, to the fallback included, to suppress that warning. No command writes this field; leave it unset to keep auto-detection.

If the configured backend can’t be used at runtime (bwrap not installed, user namespaces denied, the AppContainer API missing on this build, a value from another platform), shell_execute at read hard-errors with a message naming the configured backend, the specific failure reason and the key to fix. read is not blocked for other tools; only shell_execute requires a usable sandbox.

Overridable for one run with meka --sandbox-backend <value>, and for a whole environment with MEKA_SANDBOX_BACKEND. Precedence is flag, then environment, then this field.

Default: unset (auto-detect).

[shell]
sandbox = true
sandbox_backend = "bubblewrap"  # Linux; "appcontainer" or "restricted-token" on Windows

shell.additional_readable_directories

Directories every confined command may read beyond the system directories, wherever reads are confined: with permissions.confine_reads on, and for every sub-agent, whose reads its scope confines. Additional beyond the system directories, as the flag --additional-readable-directory is per run. The system directories are where the operating system keeps the programs, libraries and configuration a command needs to run at all, and the list is deliberately system-level: on Linux /bin, /sbin, /usr, /lib, /lib32, /lib64, /etc, /proc, /dev, /nix/store and /run/current-system/sw; on macOS /bin, /sbin, /usr, /etc, /System, /Library/Apple, /Library/Preferences, /Library/Filesystems/NetFSPlugins, /var/db, /opt/homebrew, /Library/Developer and /dev, plus the active developer directory xcode-select records, since the developer commands in /usr/bin are stubs that run the real binaries from there. Each is taken only where it exists. The skill directories [skills].additional_directories names are readable too. Add here what else this machine keeps system software under: /opt, /snap, a toolchain outside the home directory. An entry is warned about and dropped when it does not resolve, when it is relative, or when it is a directory the sandbox masks (/tmp, /run, the runtime directory, the filesystem root, meka’s own directories), since Bubblewrap binds the readable directories after its masks and /run named here would hand the session bus back to a confined command. On Windows the system directories are the Windows directory, Program Files, Program Files (x86) and ProgramData, located by the environment; under the restricted token the shell’s reads are not confined, so the list reaches the file tools alone there.

Default: []

[shell]
additional_readable_directories = ["/opt", "/snap"]

[tools]: built-in tool filters

The three knobs [[mcp.servers]] exposes for MCP tools also apply to meka’s built-in tools (file_read, file_write, shell_execute, etc.) via a top-level [tools] table. MCP per-server filtering is separate from this and keeps its own namespaces; this block only affects the built-ins.

Stale entries (a name that matches no built-in) emit a warn! at startup. meka still starts; the warning just flags a likely typo or a tool the binary renamed.

Restrict a session to read-only inspection:

[tools]
allowed_tools = ["file_read", "file_find", "file_search", "web_fetch"]

Force shell_execute to need unrestricted, so a session below that with approvals on prompts for every shell call:

[tools.tool_permissions]
shell_execute = "unrestricted"

Disable web access entirely in a locked-down environment:

[tools]
disabled_tools = ["web_fetch"]

Sub-agents spawned via agent_spawn inherit the same filter; a disabled built-in is disabled everywhere. To take something away from sub-agents only, use [subagents]. Run meka tool list to see every built-in’s effective required permission, whether a [tools.tool_permissions] override is in effect, and whether the current config enables it.

[subagents]

How deep sub-agents may nest, what one may never hold, and the one choice its parent may make for it. Where [tools] restricts everyone, this block applies only to sub-agents.

[subagents]
max_depth = 2
disabled_servers = ["mekabridge"]
disabled_tools = ["mcp__notion__create_page"]

max_depth bounds nesting through agent_spawn. The root agent spawns at depth 1, its sub-agents at depth 2, and so on; each level below the cap is granted its own agent_spawn. 1 lets the root spawn and nothing below it; 0 withholds agent_spawn from everyone, and the four lifecycle tools with it. An agent can narrow a subtree with the tool’s max_depth parameter, never widen it, and a built-in absolute cap bounds real nesting whatever either says.

disabled_servers is the one that matters. Naming a server removes everything it offers from every sub-agent: its tools, its resources, and its prompts. Reach for it when a server exists to talk to you or to act on your behalf. The motivating case is a server that can message the user: without this, a sub-agent three levels down can send a message the user has no way to distinguish from the one they are actually talking to.

disabled_tools takes names as they appear in the tool list, so built-ins (file_write) and namespaced MCP tools (mcp__notion__create_page) share one namespace. For a whole server, prefer disabled_servers: it covers the resource and prompt surfaces that a tool-name list cannot reach.

An entry matching nothing emits a warn! at startup, the same way [tools] does. A typo here denies nothing while reading as a restriction, which is worse than writing no config at all.

These are floors. An orchestrator can restrict a particular sub-agent further with agent_spawn’s allow_servers, allow_tools, deny_servers and deny_tools parameters, and each level of nesting inherits everything above it, but nothing can grant back what this block took away: a call-site allow-list only narrows, and a tool named here is withheld whatever an allow-list says.

agent_chosen_profile = true lets an orchestrator run a sub-agent on a profile other than its own: agent_spawn gains a profile parameter whose choices are every configured profile, so a mid-tier model can dispatch hard tasks to an expensive one and trivial ones to a cheap one. It is off by default because a sub-agent then bills whatever account the chosen profile names, and that is a decision to make once, in the config, rather than one the model makes on every spawn. The agent only sees profile names, so say in your standing instructions what each profile is for. A sub-agent spawned with a profile keeps it on every follow-up; one spawned without follows its parent’s profile.

Why memory and instructions are not configured here

Two things a sub-agent might inherit are deliberately absent: the memory store and the instructions file. Both are granted per call by agent_spawn and default to nothing.

The distinction is what config can actually enforce. A capability can be withheld: a tool the registry never registered cannot be reached, however the parent phrases the task. Context cannot. An agent holding the instructions has them verbatim in its own system prompt, and one with memory_read can read any memory, so either can be copied into a sub-agent’s prompt whatever config says. A [subagents].memory = "none" key would look like a boundary while stopping only the sub-agent’s own browsing, not the content reaching it, and a control that reads as a guarantee but isn’t one is worse than none.

The other half of the argument is that the config guardrail existed for a failure mode that no longer applies. It was there because the parent might forget, which only matters for things that are on by default. Both of these now default to off, so forgetting produces a clean sub-agent.

[instructions]

Where the standing instructions are read from beyond the conventional path. See Reading a project’s AGENTS.md in the Instructions guide.

[instructions]
files = ["AGENTS.md", "~/notes/meka-site.md"]

A relative entry resolves against the session’s working directory, which is how AGENTS.md names whichever project the session opens in; an absolute one is read as given, and a leading ~ is expanded. The text follows the standing instructions under the same heading. It is read when the session opens rather than at startup, so a meka -c or a new serve session sees an edit. An entry that is not there is skipped without a word; one that cannot be read is skipped with a warning.

Empty by default, and deliberately so: a relative entry lets whatever sits in a session’s directory speak with the operator’s authority, and under meka serve the client chooses the directory. Name one only where every directory a session may open in is yours to trust.

[skills]

Controls the skill store. See the Skills guide.

[skills]
enabled = false

Setting enabled = false keeps every skill tool’s schema out of every request and renders no skills section. Files already in ~/.config/meka/skills/ are left untouched.

agent_managed = true lets the agent author its own skills. It is off by default because you normally curate that store yourself; it exists for a long-running agent that dispatches sub-agents, where a skill is the only artifact that both survives the session and can be handed to a sub-agent as its task. Sub-agents never receive the authoring tools whatever this is set to. See Letting the agent manage skills.

additional_directories adds directories to the scan beyond meka’s own store. They are strictly read-only: meka never creates them and never writes into them, so an entry that does not exist is simply skipped and leaves nothing behind. A leading ~ is expanded. Where reads are confined, these directories stay readable, as meka’s own skills store does, so a skill’s bundled files can be read; see the read boundary.

[skills]
additional_directories = ["~/.agents/skills"]

~/.agents/skills is the cross-client convention, so pointing at it makes skills installed by other Agent Skills clients visible here. It is not a default: reading a directory outside meka’s own namespace is your call. meka’s own store is searched first and wins a name collision. There is no automatic project-level scan, for the same reason meka reads nothing from the working directory that config does not name, the files under [instructions] included; name the path here if you want a project’s skills read. See Reading skills from other directories.

An entry that repeats an earlier one, or that names meka’s own skills directory, is dropped with a warning: it would otherwise be scanned twice and every skill in it reported as shadowed by itself. An empty string is dropped too, since it would expand to your home directory.

[memory]

Controls the agent’s durable note store. See the Memory guide.

[memory]
enabled = false

Setting enabled = false keeps the five memory_* tool schemas out of every request and renders no memory section, which is worth doing for lean sessions that will never use it. Memories already stored are left untouched, and meka memory still reaches them.

inline_max_bytes bounds what the agent carries whole in its context. The inline band is rendered into the opening message once per session and again after each compaction, so a larger budget costs prefix tokens the cache holds rather than tokens on every turn. A write that would take the inline tier past it is refused at every door, the operator’s included, and a store already past it (the key lowered, or rows written past meka’s doors) shows the bodies that fit and lists the rest by description until they are trimmed; see The inline budget. Zero is refused at startup.

There is deliberately no environment variable and no CLI flag here: whether an agent keeps memories is a property of the installation, not something to vary per run.

[schedule]

Controls the wakeups the agent schedules for itself. See the Scheduling guide.

[schedule]
enabled = true
poll_interval = "10s"
missed_grace = "24h"
gate_timeout = "30s"
claim_lease = "1h"
max_jobs = 50
max_consecutive_fires = 5

poll_interval is the real resolution floor: a job whose interval is shorter than the tick fires once per tick, not once per interval.

missed_grace applies only to one-shot jobs. Recurring jobs need no equivalent, because their occurrences are one period apart, so the most recent missed one is always less than a period old; the scheduler coalesces the rest into a single catch-up fire.

claim_lease is how long a crashed host’s occurrence stays unavailable before another host takes it. A due job is leased rather than consumed, so the row survives until the turn is delivered and a host that dies mid-delivery costs a retry rather than the occurrence. Raise it only if a gate probe plus a turn could plausibly exceed an hour; lowering it below that risks a second host taking an occurrence the first is still running, which the session lock catches at the cost of a deferral and a re-run gate probe. A host refuses to start on a value at or under gate_timeout, since a lease that cannot outlast the host’s own probe is never right; that check does not cover the turn after the probe, which is unbounded, so leave headroom on top of it.

max_consecutive_fires interleaves sessions: without it, one session’s whole backlog runs to completion before another session’s single due job is reached. Jobs past the budget keep their occurrence, run no gate, and are taken by the next sweep most-overdue first. It bounds a batch rather than a rate: sweeps do not overlap and the next starts as soon as the last ends, so a backlog still produces one turn per job, just in interleaved groups. 0 is refused, since it would hold every job over forever; use enabled = false to turn scheduling off.

Setting enabled = false keeps the three schedule_* tool schemas out of every request and leaves existing jobs on disk without firing.

As with [skills] and [memory], there is no environment variable and no CLI flag: whether an agent may schedule its own turns is a property of the installation.

[background]

Controls tool calls the agent starts and does not wait for. See the Background tasks guide.

[background]
enabled = true
max_tasks = 10

Alone among the capability blocks, this one is off by default. [schedule], [skills], and [memory] add capability without changing when a turn ends; this changes the contract of the primary interaction into “you asked, it answered, and something else may interrupt you later”. That is right for an unattended assistant and wrong for someone using the screen as a command line. A scheduled job also takes an explicit act to create, whereas background is reachable from any tool call, so an agent will reach for it unprompted.

Setting enabled = false keeps the background property out of every tool schema and the two task_* tools out of every request, rather than advertising a parameter that would only ever be refused.

Outcome delivery shares [schedule].poll_interval, so that key sets how long a finished task waits before it is reported, whether or not scheduling itself is enabled.

Config-only, like the blocks above: no environment variable, no CLI flag.

[session]

Settings for session history retention and context window management.

session.retention

Delete sessions not updated for longer than this, at startup and then hourly for as long as meka serve, meka acp or the screen stays up. A duration string like "30d" or "12h". Uses updated_at, so an actively-resumed session is preserved even if created long ago. Deletions are reported at warn level.

The screen’s input history, the lines Up and Ctrl+R recall, is swept with it: an entry older than this window, or than turn_retention when that is the shorter, is deleted, since what a person typed must not outlive the conversation it went into.

Three kinds of session are spared whatever their timestamp says. A session another meka process has open is skipped, and the sweep reports how many: only turns bump updated_at, and resuming does not, so an interactive session left open past the window looks expired while somebody is in front of it. A pinned session is never expired, nor is any parent of one: a pin is you saying keep this. And a session with a scheduled job still ahead of it is never expired, nor is any parent of one: a gated watcher that evaluates every tick and rarely fires looks untouched for exactly as long as it is working, and deleting it would take the schedule with it.

Default: unset, meaning nothing is deleted. "0s" is refused at startup, since it would delete everything on every launch. Conversation history isn’t reproducible, so meka keeps it until told otherwise. Use meka session remove --older-than-days <DAYS> to prune manually instead.

[session]
retention = "30d"

session.turn_retention

Delete the turns of every session that ended longer ago than this, once a compaction has summarized them. A duration string like "90d" or "36h". The sweep runs at startup, at the start of each turn for that turn’s session, and hourly for as long as meka serve, meka acp or the screen stays up.

Only turns before a session’s latest compaction can go, since the summary is what stands in for them: the turns the model still works from are never deleted out from under it. When one of those is older than the window, the next turn compacts first, keeping no rounds verbatim and quoting none, and the sweep takes it afterward. Needs auto_compact = true for that reason. A turn goes whole: its messages, its record, its words in the search index and the images only it carried. Inbox items and background outcomes go once they have been delivered or withdrawn for longer than the window. Scratchpad entries and memories are the agent’s own and stay.

The model is told the window in its system prompt, and every turn’s context block names the date nothing precedes, so it knows how far back conversation_search reaches and to keep in memory what must outlive the window. See What the agent sees.

Default: unset, meaning every turn is kept for the life of its session. "0s" is refused at startup, since it would compact and delete the conversation on every turn. Deletions are reported at warn level.

[session]
turn_retention = "90d"

session.auto_compact

Automatically compact the conversation once it is past context_ceiling_percent of the context window, between turns or between two tool rounds of one turn. Compaction summarizes older messages and preserves recent ones, the open checklist, and scratchpad entries. Off changes nothing else: a whole scratchpad_read still stops at the ceiling, and a request past the window fails the turn.

Default: true

[session]
auto_compact = false

session.context_ceiling_percent

The share of the context window meka lets the conversation fill on its own. Two things happen at the line: with auto_compact on, the conversation is compacted once past it; and a whole scratchpad_read that would carry the context past it is cut there and says where to continue, whether or not compaction is on. Refused outside 1 through 100.

What is left above the line has to hold the reply and one round’s growth past it, so keep at least your output budget plus a round free: the API refuses a request whose input and output cap together exceed the window. The default leaves 150k tokens on a 1M window against a Claude reply budget of 128000; on a small window it needs lowering, or max_output_tokens does.

Default: 85

[session]
context_ceiling_percent = 70

session.compact_checkpoint

Run a checkpoint turn before each compaction, in which the agent saves anything that must outlive the window and writes the replacement summary itself. See Compacting a session.

Costs one extra model call per compaction. Turning it off falls back to a standalone summarizer that has no tools and none of the standing instructions, so it cannot save to memory and cannot apply any judgment about what this particular deployment is for.

Note that this applies to automatic compactions too, so an unattended checkpoint can write memory with nobody watching.

Default: true

[session]
compact_checkpoint = false

session.context_window

Override the model’s context window size (in tokens). Used for the context ceiling. A per-profile [profiles.<name>].context_window takes precedence over this.

When neither is set, meka assumes 1000000. It does not infer the window from the model name, query the provider’s models API, or cache anything: the window is a local budgeting number that is never sent on the wire, so a wrong value can’t fail a request, and the user is the one who knows the truth.

1M suits the current flagship models and overshoots the smaller and older ones. Overshooting is survivable rather than free: planned compaction never fires, so those sessions compact only after the provider rejects an over-long request, paying a wasted round trip each time. Set the real window on any profile whose model is smaller.

[session]
context_window = 200000

[thinking]

Presentation and budget settings for extended thinking (anthropic-messages and claude-subscription backends). Whether thinking is on, and which wire encoding it uses, is the per-profile thinking key, not a setting here.

While the model is thinking, the screen draws a live • Thinking row so a long pause reads as work rather than as a hang. On claude-subscription it carries the server’s own running estimate (• Thinking · 150 tokens), redrawn in place as the count climbs; anthropic-messages does not report one, so the row stays bare. The count is coarse: a progress signal, not an accounting figure.

When the block ends the line stays on screen as a record that the phase happened; if the model returned readable reasoning, that text replaces the line instead.

thinking.budget

Maximum number of tokens the model can use for thinking. Read only under thinking = "budgeted"; the adaptive encoding lets the model set its own budget and sends no cap. A per-profile [profiles.<name>].thinking_budget takes precedence over this.

Default: 16000

[web]

Settings for the HTTP client web_fetch uses. All keys are optional; unset fields use the defaults shown below.

Example: corporate proxy with a private CA

[web]
proxy = "http://corp-proxy.internal:3128"
ca_cert_file = "/etc/ssl/corp-root-ca.pem"
min_tls_version = "1.2"
request_timeout = "60s"

Example: local testing against self-signed certs

[web]
# Route everything through a local SOCKS proxy you control.
proxy = "socks5h://127.0.0.1:1080"
# Accept self-signed certs on dev.local, KEEP THIS OFF IN PROD.
danger_accept_invalid_certs = true

Example: fail-fast timeouts

[web]
request_timeout = "5s"
connect_timeout = "2s"
max_redirects = 0

[display]

Settings for the interactive screen: the two rows it composes, whether finished steps fold, the session id lines, what Enter does while a turn runs, the mouse, and stream, which also decides how a one-shot run asks the provider.

display.status_row

Which facts the status row under the composer shows, each in its place and, within it, in the order listed. On the left, after the permission level, which always opens the row, the profile and the model say what the next prompt goes under, and the path and the project where the session works; the context gauge and the running work stand against the right edge.

• path: the session’s working directory, shortened with ~
• project: the project the session is on, by name, while it is on one
• profile: the profile the session runs on, by name
• model: the model the profile runs, when the config names one; off by default, since a profile named for its model would show it twice
• context: the live context-window gauge, e.g. 128.4k / 1.0M (13%) (tokens in context / model window, and the share used), the same figures /status shows on its Context: line; shown from the start at 0 / <window> (0%), omitted only while the window is unknown
• tasks: 2 background tasks, while any run
• subagents: 1 sub-agent, while any run

A hint (Copied 3 rows, The question was withdrawn) takes the status row’s right side while it stands, whatever the list says. Where the row is narrow, the level stays whole and the readings give way to it, each shown whole or not at all, from the last, since a reading cut short reads as another number; the facts after the level give way from the last too: the one that no longer fits is cut (a path from its start), or dropped when too little of it would show. A word that is not one of these, or one listed twice, is refused by name.

[display]
status_row = ["profile", "context"]

Default: ["profile", "path", "project", "context", "tasks", "subagents"]

display.turn_end_summary

What the row that closes a turn states, in the order listed:

• time: when the turn ended, as a time of day today and with the date otherwise
• duration: how long it ran
• usage: the tokens it used, with the share of the input that came from the cache

The row reads as one sentence whose first word says how the turn ended:

• Finished at 19:28 after 19m 19s
• Interrupted at 19:30 after 2m 3s
• Finished at 19:28 after 19m 19s with 12.3k tokens in, 1.2k out, 96% cached

A fact with nothing to say is left out. An empty list draws no row. A word that is not one of these, or one listed twice, is refused by name. On a resumed session every recorded turn closes with the same row, read from the store, so a scrollback says when each turn ended. A one-shot run prints none; --format json carries the turn’s usage.

The usage’s in count is the total of all three Anthropic input tiers (live, cache-write, cache-read); the cached share is cache_read / in. The /status slash command surfaces the session’s cumulative numbers in the same vein.

[display]
turn_end_summary = ["time", "duration", "usage"]

Default: ["time", "duration"]

display.fold_steps

Whether the interactive screen folds a run of thinking and tool calls into one row, such as ▸ Thought twice, ran 3 commands, read a file, once the agent writes something after it or its turn ends. Changes to files, memories and skills, and agent_spawn and agent_followup calls, never fold. Ctrl+O opens every run, with every call expanded, until it is pressed again. With false, every run starts open and still folds when you click its row. See Folded steps.

Default: true

[display]
fold_steps = false

display.show_session_id_on_create

Whether the screen shows the session id when a new session is created.

Default: false

display.show_session_id_on_resume

Whether the screen shows the session id when a session is resumed with -c, -r or /resume.

Default: false

display.show_session_id_on_exit

Whether the screen shows the session id when meka exits.

Default: true

A one-shot run prints no session id whatever these say: --format json carries it as session_id, and -v logs it.

[display]
show_session_id_on_create = true
show_session_id_on_resume = true
show_session_id_on_exit = false

display.send_class

What Enter does on the interactive screen while a turn is running: steer posts the message to the session’s inbox, where the agent reads it at its next round; followup holds it and sends it as the next turn once this one ends; interrupt cuts the answer being streamed and hands the agent the message at once. Alt+S cycles the class for one run. See While a turn runs.

Default: steer

[display]
send_class = "followup"

display.mouse

Whether the interactive screen captures the mouse. With it on, the wheel scrolls the transcript and a click expands or collapses a block; the terminal’s own click-and-drag then needs its modifier key (Shift in most terminals, Option in iTerm2) to select text. With it off the mouse is the terminal’s, and the keyboard still scrolls and toggles. See Scrolling and the mouse.

Default: true

[display]
mouse = false

display.wheel_rows

How many rows the transcript, or a panel under the pointer, moves for each wheel event the terminal sends. The terminal already decides how many events one notch of the wheel sends: Ghostty sends three, a trackpad sends one per few pixels, and VS Code’s terminal sends one, so one row per event follows what the terminal meant. Raise it if your terminal sends one event per notch and scrolling feels slow. 0 is refused at startup.

Default: 1

[display]
wheel_rows = 3

display.stream

Whether the provider is asked to stream its reply or to return it whole. On the screen a streamed answer is drawn as it arrives and a whole one lands when the turn ends; a one-shot run prints its answer when the turn ends either way. The --no-stream flag turns streaming off for one run; this key is the standing preference, and it applies to sub-agents as well.

Default: true

[display]
stream = false

[serve]

Configuration for meka serve, the HTTP API server. See the HTTP API usage guide for a full walkthrough.

A ${VAR} in a [serve] value (a token, a webhook URL) is expanded from the process environment by the grammar the MCP fields use, ${VAR:-default} included. A name the environment does not supply and no default covers refuses the server at startup, since a token left reading ${VAR} would be an auth-bypass-shaped configuration; so does a reference the grammar does not accept (an unclosed ${, an empty name, a default that opens another reference), which would otherwise become the token as written.

serve.bind

Address and port the HTTP server listens on.

[serve]
bind = "0.0.0.0:8080"

Security: Binding to 0.0.0.0 exposes the server on all interfaces. In production, keep 127.0.0.1 and front with a TLS-terminating reverse proxy.

serve.cors_allowed_origins

Browser origins allowed to call the API cross-origin, for a web application served from somewhere other than meka itself. Omitted or empty, the server sends no CORS headers at all, and a browser refuses every cross-origin call.

[serve]
cors_allowed_origins = [
    "https://owner.github.io",
    "http://localhost:5173",
]

An origin is a scheme, a host and a port, and nothing else: https://owner.github.io/mekaweb/ has the origin https://owner.github.io, and a path cannot narrow the grant. Each entry is normalized at startup to what a browser sends in Origin (lowercase host, default port dropped, a trailing root slash tolerated), and a request is granted only when its origin matches an entry exactly: another scheme, port or subdomain is another origin. An entry with a path, query, fragment or credentials, a non-HTTP scheme, null, or a pattern such as https://*.example.com is refused at startup.

["*"], alone, grants any origin. That is safe here because the API authenticates with a bearer header the page sets itself and never with a cookie: a page without the token gets a 401 from any origin, and a page holding it can use it from anywhere regardless. The allowlist guards only what needs no token: the two health probes, the opt-in OpenAPI document and the body of a 401. Name your origins where you can; use * for a LAN deployment reached from several device addresses. Browser clients describes what the grant covers.

serve.max_body_bytes

Maximum request body size in bytes. Requests exceeding this limit are refused with 413 Payload Too Large. 0 is refused at startup; omit the field for the default.

serve.relay_provider_errors

Whether a 502’s payload carries the provider’s own response text, as a provider_response member alongside detail.

On by default. The upstream’s error type is the actionable part of a failed turn, and “consult the server log” is no answer to anyone driving a meka they do not operate. meka acp honors this key too: the same policy decides what a failed turn’s error.data carries.

What it can expose is usually the upstream’s response body, which can name the operator’s account with the provider and its rate-limit posture: a fact about your billing relationship rather than about the caller or the conversation, which is why this is a switch rather than a decision meka makes for you. Not always, though. The member carries the failing call’s error message, and for some failures that is meka’s own sentence about the call rather than anything the provider sent.

It reaches sessions:r, not only sessions:w. Submitting a turn takes the write scope, but the failure also rides the terminal turn.failed event, and GET /v1/sessions/{id}/stream replays that to any reader. Turn this off where read-only tokens go to people who may watch a session but are not entitled to the account behind it.

[serve]
relay_provider_errors = false

detail is unchanged either way, so a client reading only that sees the same sentence and a context overflow keeps its “shorten it before retrying” remedy. Off, the member is simply absent and the text goes to the server log alone.

Bounded to the provider’s own response. A required MCP server that is down still reports only the server names under /errors/mcp-unavailable, because that reason is meka’s own subprocess text and has carried a command line and its filesystem path. This key does not turn that on.

serve.docs

Whether to serve the OpenAPI document at /v1/openapi.json.

Off by default. It is the only route on the surface that takes no bearer token and describes the deployment rather than reports on it: what it publishes is the shape of every endpoint you expose. That is exactly what you want while building a client against a local meka serve, and exactly what you do not want reachable from anywhere else. Turn it on deliberately.

[serve]
docs = true

serve.max_concurrent_turns

Process-wide cap on in-flight turns across all sessions, counting every turn: one a client submits and one the server starts on its own for an inbox item, a scheduled job or a finished background task. When the cap is reached, a new turn submission returns 429 Too Many Requests with a Retry-After header, and an autonomous turn waits for a free slot (the next turn’s end or the next tick) rather than running past the cap. Leave it unset for no limit; 0 is refused at startup, because a cap of zero would 429 every turn rather than mean “unlimited”.

serve.stream_replay_events

How many of a session feed’s latest SSE events to retain, across its turns, so a client reconnecting to GET /v1/sessions/{id}/stream with Last-Event-ID can replay what it missed. The events retained also stay within 16 MiB of payload, the oldest leaving first, since one file edit’s event carries the file before and after.

Matches the live broadcast channel’s capacity: retaining more than the channel can buffer would let a reconnecting client replay events a connected consumer would have been dropped for missing. Raising it buys a longer reconnect window at the cost of memory for every resident session. 0 switches replay off, so a reconnect receives only what happens from then on and is told its replay is incomplete rather than being handed a silently truncated one.

serve.stream_reattach_grace

How long a held turn keeps running after its request’s client disconnects, waiting for a listener to come back, and how long a parked approval prompt waits after its last attending reader disconnects before it is canceled. Accepts duration strings.

Zero subscribers means nobody is listening, and a turn with no audience is spending provider tokens for nothing. That is the right instinct and the wrong deadline: a client whose connection just dropped and one that is never coming back are the same observation until the window expires. Set "0s" to stop a turn at the first round boundary after its request drops, which spends less on abandoned work and makes re-attach useful only for turns that already finished. A turn a request opened with detach: true, and one the server opened, is never stopped for want of a reader; see Holding a turn.

serve.inbox_retry_ceiling

How long a queued inbox item is retried for after a turn on it failed, from when it was enqueued, before it is given up on with inbox.failed. Accepts duration strings.

The ceiling bounds the whole wait: a retry never lands past it, whatever the upstream said about when it would be back, so a deployment states its own patience here, and every item shows the deadline it sets as retry_until. Set "0s" to give an item up on its first failure, for a client that owns redelivery itself. A failure no retry would change, a rejected credential or a request the upstream judged wrong, gives the item up at once regardless; one waiting can change, the upstream unavailable, a required MCP server not ready, meka’s own store or disk refusing, is retried within the ceiling. See The inbox.

serve.idle_timeout

How long a session can sit idle (no turns submitted) before the GC evicts it from memory. Accepts duration strings like "24h", "30m", "7d". "0s" turns idle GC off: nothing is ever evicted for being idle.

Eviction drops the in-memory runtime but preserves the SQLite row; a later request transparently re-attaches. See delete_on_idle to also remove the row. An open feed keeps its session loaded when its token holds sessions:w, the scope that could load it; a sessions:r reader keeps nothing loaded.

serve.gc_scan_interval

How often the background GC scanner runs. Accepts duration strings; "0s" is refused at startup, since the scanner would then never run.

serve.delete_on_idle

When true, idle-evicted sessions also have their SQLite row deleted, unless a pin or a scheduled job anywhere in the session’s tree keeps it, as [session].retention spares one. When false (default), only the in-memory state is dropped and the session can be re-attached later.

serve.shutdown_drain_timeout

Maximum time to wait for in-flight turns and tasks to finish during graceful shutdown (SIGTERM / SIGINT). After this timeout, remaining tasks are aborted and the process exits.

[[serve.tokens]]

An array of bearer tokens for API authentication. At least one token is required.

* Exactly one of token or token_file must be set.

Inline plaintext tokens log a startup warning; use ${ENV_VAR} or token_file for production.

Examples

Development token (inline):

[[serve.tokens]]
token = "sk_dev_test123"
scopes = ["sessions:r", "sessions:w"]

Production token (environment variable):

[[serve.tokens]]
token = "${MEKA_BRIDGE_TOKEN}"
description = "telegram bridge"
scopes = ["sessions:r", "sessions:w"]

Production token (file-based):

[[serve.tokens]]
token_file = "/etc/meka/bridge.token"
description = "telegram bridge"
scopes = ["sessions:r", "sessions:w"]

Admin token with every scope:

[[serve.tokens]]
token = "${MEKA_ADMIN_TOKEN}"
description = "operator"
scopes = [
    "sessions:r", "sessions:w",
    "skills:r", "skills:w",
    "memory:r", "memory:w",
    "schedule:r", "schedule:w",
    "mcp:r", "mcp:w",
    "config:r", "config:w",
]

Scopes are flat: memory:r does not imply memory:w, and neither implies the other. See the HTTP API scope table for what each permits. An unrecognized scope logs a warning at startup and grants nothing, so a typo like sessions:write is visible rather than silently inert.

[[serve.webhooks]]

Outbound endpoints meka POSTs to when something happens that no client is waiting on: a scheduled job firing, a background task finishing. Omit the block entirely and meka never makes an outbound request.

[[serve.webhooks]]
url = "https://bridge.example/meka-hook"
secret = "${MEKA_WEBHOOK_SECRET}"     # or secret_file = "/etc/meka/hook.secret"
events = ["turn.finished", "turn.failed", "task.finished", "schedule.fired"]
timeout = "10s"
max_retries = 3

events is required and every name must be recognized. An unknown event is a startup error, not a warning, unlike an unknown token scope: a scope that grants nothing leaves the token working for whatever else it holds, whereas an endpoint whose only subscription is a typo is silently never called at all.

Payloads carry identifiers and metadata, never message content. Omitting secret sends unsigned deliveries and logs a warning. See Webhooks for the payload shape and the signature-verification recipe.

Environment variables

The config file is the recommended way to configure meka. Environment variables are useful for operational overrides; for example, in CI pipelines, containers, or to isolate a per-project config and data directory.

These operational variables override config file values but are overridden by CLI flags.

Accounts and profiles are not configurable via the environment. Profile selection comes from the config file and --profile; the model and every other model-tied setting come from the selected profile, the endpoint from its account; secrets come from the store via meka account. There are no account or profile env vars. This is deliberate: an ambient OPENAI_API_KEY or MEKA_PROFILE left in the environment must never silently rebind which account a named profile bills.

meka-specific variables

MCP variables

How many servers connect at once at startup is a setting, not a variable: [mcp].stdio_concurrency and [mcp].http_concurrency.

Editor

Logging

meka uses the tracing framework. The log level can be controlled with:

If RUST_LOG is not set, the verbosity flag (-v, -vv, -vvv) controls the level:

Logs are written to stderr so they do not interfere with agent output.

CLI options

meka [OPTIONS] [COMMAND]

Commands

account

Manage accounts and their credentials. meka account add writes an [accounts.<name>] table to ~/.config/meka/config.toml and keeps its secret in the store; usage, whoami and stats are the read-only views described under Account info.

meka account add claude --backend claude-subscription
meka account list [--format <FORMAT>]
meka account login claude
meka account remove claude
meka account rename claude personal
meka account usage [NAME] [--format <FORMAT>]    # session / weekly windows
meka account whoami [NAME] [--format <FORMAT>]   # plan, tier, org, role and local auth status
meka account stats [NAME] [--format <FORMAT>]    # lifetime tokens, streaks, per-day counts

See the meka account CLI reference for the full flag list.

profile

Manage profiles: an account plus a model and every model-tied setting. meka profile add writes a [profiles.<name>] table; nothing here touches a credential.

meka profile add work --account anthropic --model claude-opus-5-5
meka profile list [--format <FORMAT>]
meka profile set work model claude-opus-5-5
meka profile set work effort --unset   # back to the default
meka profile use work
meka profile remove work
meka profile rename work daily

See the meka profile CLI reference for the full flag list.

project

Manage projects: the names a session is on, each a memory tier of its own, kept as rows of the store. See Projects.

meka project add webdev
meka project list [--format <FORMAT>]   # name, when it was added, memories, sessions
meka project remove webdev              # refused while anything is on it
meka project rename webdev web          # moves its sessions and memories with it

session

Manage stored sessions: list or search them, show one in full, export one as Markdown or JSON, import a JSON export, fork, rewind, title or pin one, or delete them.

Every <SESSION_ID> is a full id or any unique prefix of one, which is what the listings print.

meka session list [-n <LIMIT>] [--include-children] [--project <NAME>] [--format <FORMAT>]   # default limit: 20; sub-agent sessions hidden unless asked
meka session show <SESSION_ID> [--format <FORMAT>]    # full id, profile, project, directory, permission, title
meka session export <SESSION_ID> [-o <OUTPUT>] [--format <FORMAT>]   # markdown (default) or json; -o - prints to stdout
meka session import <INPUT>                           # a JSON export; - reads stdin
meka session fork <SESSION_ID>                        # prints the copy's id
meka session rewind <SESSION_ID> [-n <TURNS>]         # default 1
meka session set <SESSION_ID> title|pinned <VALUE>      # a title, or true/false
meka session search <QUERY> [-n <LIMIT>] [--include-children] [--format <FORMAT>]
meka session remove <SESSION_IDS>...
meka session remove --older-than-days <DAYS>
meka session remove --all

See Sessions for details.

history

View or clear the input history that powers Up-arrow / Ctrl+R recall (distinct from saved sessions).

meka history list [-n <LIMIT>] [--format <FORMAT>]   # default 50; -n 0 shows all
meka history clear

mcp

Manage MCP servers in config.toml and their stored credentials.

meka mcp list [--format <FORMAT>]
meka mcp get <NAME> [--format <FORMAT>]
meka mcp add <NAME> [LOCATION] [ARGS]... [flags]   # a URL (HTTP) or an executable (stdio)
meka mcp remove <NAME>
meka mcp disable <NAME>
meka mcp enable <NAME>
meka mcp reconnect <NAME>
meka mcp tools <NAME> [--format <FORMAT>]
meka mcp login <NAME> [--auth-token-stdin | --client-secret-stdin]
meka mcp logout <NAME>

See MCP for the add flags and what each command does.

tool

Inspect built-in tools. meka tool list prints every built-in with its Permission, the Source of that requirement (builtin, or override from [tools]), its Status (enabled, deferred, or disabled), and the start of its description. The levels are the ones a session on this machine would enforce: shell_execute is read where the shell sandbox is on and a backend is usable, and unrestricted otherwise, so the listing probes the sandbox the way a session start does and gives the same warning when none is usable.

meka tool show <name> prints one built-in as the model receives it: the same fields, the whole description and the parameters schema. Under json, the object is the listing’s entry plus parameters.

meka tool list [--format <FORMAT>]
meka tool show <NAME> [--format <FORMAT>]

See Filtering built-in tools.

skill

Manage the skills under ~/.config/meka/skills/.

meka skill list [--paths] [--format <FORMAT>]
meka skill get <NAME> [--format <FORMAT>]    # frontmatter and on-disk paths
meka skill show <NAME> [--format <FORMAT>]   # the rendered body
meka skill add <NAME> [flags]
meka skill remove <NAME>

See Skills for the add flags.

memory

Manage the memories the agent keeps.

meka memory list [--project <NAME>] [--format <FORMAT>]
meka memory get <NAME> [--project <NAME>] [--format <FORMAT>]    # every stored field
meka memory show <NAME> [--project <NAME>] [--format <FORMAT>]   # the body
meka memory add <NAME> --description <DESCRIPTION> [--project <NAME>] [flags]
meka memory edit <NAME> [--project <NAME>]      # the body, in $VISUAL, then $EDITOR
meka memory remove <NAME> [--project <NAME>]
meka memory verify [--rebuild]
meka memory export [--directory <DIR>] [--project <NAME>]   # default: ./meka-memory-export
meka memory import <DIR> [--force]              # the reverse; --force overwrites a memory that exists

--project names the tier a command works in: a project’s, or the global tier for an empty value. Without it a listing covers every tier, and a name that is in several projects is refused until one is named. See Memory for the add flags.

instructions

Show the standing instructions the agent is given.

meka instructions show   # the resolved text and where it came from
meka instructions path   # the paths checked, and whether each exists

See Instructions.

schedule

Inspect and cancel the wakeups the agent scheduled for itself. There is no create: a job needs a session for its turn to run in, and the agent creates one through schedule_create.

Every <ID> is a full id or any unique prefix of one, which is what list prints.

meka schedule list [--session <SESSION>] [--format <FORMAT>]   # every session's jobs, or one session's by id or prefix
meka schedule show <ID> [--format <FORMAT>]   # full prompt, gate command, session, withheld reason
meka schedule cancel <ID>

See Scheduling for details.

acp

Run meka as an ACP agent over stdio. Takes no flags of its own; -c, -r and --project are refused, and --profile selects the profile a new session starts on.

meka acp

serve

Run meka as a long-lived HTTP service. --bind <ADDR> overrides [serve].bind. Like acp, it refuses -c, -r and --project: the host creates a session per request.

meka serve
meka serve --bind 0.0.0.0:8080

Options

-p, --prompt <TEXT>

Run the agent’s first turn immediately with this text as the user message, then stay on the interactive screen for follow-up. Pair with --oneshot to exit after the first turn instead of opening the screen. -p - reads the prompt from stdin, to end of input.

meka -p "list all files larger than 1MB in the current directory"   # first turn, then the screen
meka --oneshot -p "list all files larger than 1MB"                  # first turn, then exit
git diff | meka --oneshot -p -                                      # the prompt is the diff

When omitted, meka opens the screen with no initial input. There is no bare positional prompt, so a mistyped subcommand is an error rather than a session opened with the typo as its first turn.

--skill <NAME>

Invoke a skill as the first turn. Mirrors the slash command /skill <name> [extra...]. -p, if given, is prepended to the rendered skill body as additional context. Pair with --oneshot to exit after the turn instead of opening the screen.

meka --skill download-videos -p "https://example.com/video"             # first turn, then the screen
meka --skill download-videos --oneshot -p "https://example.com/video"   # first turn, then exit

Errors out with a clean message if the skill name is unknown.

-c, --continue

Continue the most recent session. Takes no value.

meka -c                        # pick up where you left off
meka -c -p "and now add tests" # …with an opening prompt

Starting fresh when there is no session yet is not an error; meka just begins a new one. With --project <name>, the most recent session on that project, or a new one on it.

-r, --resume [SESSION]

Resume a specific session, or pick one. The value is the full id or any unique leading prefix; with nothing after it, the screen opens on a picker: the fifty newest sessions, filtered after /, Enter resuming the pick and Esc leaving you in a new session.

meka -r                                          # pick from a list
meka -r 550e8400-e29b-41d4-a716-446655440000     # full id
meka -r 550e                                     # prefix; works if unique
meka -r 550e -p "and now add tests"              # …with an opening prompt

The value can be left off because nothing on the root command is positional: the prompt is -p, so meka -r -p "fix it" reads as a pick with an opening prompt. A scripted run has no screen to pick on, so --oneshot -r needs the session named. With --project <name>, a bare -r picks among that project’s sessions, and -r <id> moves the named session onto the project.

Errors if the session does not exist, the prefix matches multiple sessions (with the matching ids listed for disambiguation), or the session is locked by another meka instance.

-c and -r are mutually exclusive. Both work with --oneshot, which runs a single turn against the session and exits:

meka --oneshot -r 550e -p "summarize what we decided"

--profile <NAME>

Select which configured profile a session runs on. Takes the name of a profile from [profiles.<name>], overriding default_profile in the config file. The choice outlives the run: on a new session it is what gets recorded, and on a resume it rewrites the row.

meka --profile work

The value is a profile name (e.g. work, personal), not an account or a backend. List configured profiles with meka profile list. There is no short form: -p is the prompt.

A new session records the profile it runs on, so meka -c later comes back on it rather than on default_profile. Passing --profile alongside -c / -r repins the session: the row is rewritten and it keeps that profile from then on. See what a resume restores.

There is no --model, --base-url, --thinking or --thinking-budget. A profile is an indivisible bundle of an account, a model and every model-tied setting, and a session records which one it runs on rather than a rewritten copy. To change a setting, edit the profile with meka profile set; to run something different, make a second profile and select it with --profile.

--project <NAME>

Open the session on a project, one meka project add created; see Projects. A new session records it, the way it records its profile, and sees the project’s memories beside the global ones.

meka --project webdev
meka -c --project webdev          # the latest session on webdev, or a new one there
meka -r --project webdev          # the picker over webdev's sessions
meka -r 550e --project webdev     # moves session 550e onto webdev

Beside -c and a bare -r, the flag filters the session meka selects; beside -r <SESSION> it moves the session you named, rewriting its row. A name no project has is refused before anything is touched. There is no value for “no project”: a session with nothing named is on none, and /project close takes a session off one.

--permission <LEVEL>

Set the initial permission level. Accepts none, read, workspace or unrestricted.

meka --permission workspace

There is no flag for approvals: a new session takes [permissions].approvals from the config file, and /approvals on moves it afterwards.

Default: read.

Recorded on the session, so a resume comes back at the level the session was last at rather than at the default. Passing --permission alongside -c / -r repins it, the way --profile does. A level that is no longer in [permissions].enabled is not granted on resume: the session drops to the configured default with a warning.

--instructions <STRING>

Standing instructions for this run, replacing the instructions.md file and both MEKA_INSTRUCTIONS* environment variables. Takes the text itself, not a path; use "$(cat file.md)" to read one.

meka --instructions "Be terse. No code fences in answers."

--additional-workspace-directory <DIR>

Add a directory to the workspace beside the working directory, with the working directory’s rights: writable at workspace, read-only at read, searched with it by the search tools. Repeatable. The working directory is always part of the workspace; this adds to it.

meka --permission workspace --additional-workspace-directory ../shared-assets --additional-workspace-directory /srv/build

Deliberately a flag rather than a config key: which directories this run works in is a per-run scope, like the working directory itself, not a preference to persist.

A path that does not resolve at startup is reported as a warning and kept, so a build directory that does not exist yet joins the workspace the moment it does. A path that is not a directory, or a system directory the sandbox masks, is refused with a warning: neither can be expressed as a boundary by every backend.

The masked set is the filesystem root itself plus /proc, /dev, /sys, /run, /tmp and /var/tmp, and /run/user and $XDG_RUNTIME_DIR as whole subtrees. A directory is refused when it is one of these and when it is an ancestor of one, but not when it is merely underneath: a directory under one of these is usually fine and refusing it would be a real loss, since /run/media/$USER/drive is an ordinary external disk. The ancestor half is why --additional-workspace-directory /var is refused, and it is also why --additional-workspace-directory ~ is refused on WSL and on minimal window managers, where $XDG_RUNTIME_DIR lives under $HOME and so binding $HOME would hand the session bus back. /tmp and /var/tmp are in the set because Bubblewrap masks them with a tmpfs and then binds the requested directory back over it, last mount winning: binding /tmp/work restores just that directory, but binding /tmp restores the entire host /tmp including every X11, D-Bus and tmux socket in it, which is a route straight back out of the sandbox. The cost is that a session started with cd /tmp has no write boundary, which is the safe direction to fail.

The flag reaches the interactive screen, one-shot runs, and ACP sessions. It does not reach sessions created through POST /v1/sessions, which are single-directory by design, and therefore does not reach a scheduled turn under meka serve either: those run in the session the job belongs to, which the HTTP API created.

--additional-readable-directory <DIR>

Add a directory this run may read beyond its workspace and never write, which the search tools cover only when named. Repeatable. In effect where reads are confined, by [permissions].confine_reads; the per-run form of [shell].additional_readable_directories, held by the session rather than the installation, so a sub-agent spawned with nothing named inherits it and one given a scope of its own does not.

meka --permission read --additional-readable-directory ~/reference

A path that does not resolve is reported as a warning and kept, as the workspace flag’s is. The flag reaches the same hosts the workspace flag does, and is likewise never recorded on the session.

--sandbox-backend <BACKEND>

Pick the sandbox backend for this run: landlock, bubblewrap or bubblewrap-landlock on Linux, appcontainer or restricted-token on Windows. A value from another platform is refused, and macOS has one backend and takes no value. Wins over MEKA_SANDBOX_BACKEND and [shell].sandbox_backend, and like either of those, pinning a value suppresses the warning the auto-pick prints when it falls back.

meka --sandbox-backend landlock

--eager-load-tool <SERVER:TOOL>

Eager-load a specific MCP tool for this session, bypassing the tool_load round-trip. The tool’s schema ships in the cacheable tools-array prefix from turn 1 instead of being deferred. Mirrors the per-server eager_load_tools config field: repeatable, raw tool names (the server-advertised form, not mcp__<server>__<tool>).

Particularly useful for scripted runs that know up front which tools they’ll need. The flag appends to whatever eager_load_tools lists in config.toml for that server; it doesn’t replace existing entries. A server name the file does not hold logs a warning and is kept, for a server of that name added while the process runs.

meka --eager-load-tool notion:search --eager-load-tool github:create_issue \
     --oneshot -p "search Notion for the deploy runbook and open a GitHub issue"

--no-stream

Disable streaming for this run. The agent waits for the complete response before displaying it. By default, responses are streamed token-by-token; display.stream is the persistent form. Applies to sub-agents as well.

meka --no-stream

--format <FORMAT>

What a --oneshot run writes to stdout: plain (the default) streams the answer as text; json prints nothing during the turn and one object when it ends. See One-shot mode for the object’s fields. The flag applies to --oneshot alone; a run without it is refused. meka account usage, whoami and stats take the same flag and values, and meka session export --format takes markdown or json.

meka --oneshot -p "what changed?" --format json | jq -r .text

Every listing and show command takes the same --format plain|json: session list|show|search, account list|usage|whoami|stats, profile list, project list, mcp list|get|tools, schedule list|show, memory list|get|show, tool list|show, history list and skill list|get|show. Under json, a show prints one object and a listing prints {"<nouns>": [...]} (sessions, accounts, profiles, projects, servers, jobs, memories, tools, history, skills), with the field names the HTTP API uses for the same object where it has one. An empty listing is the envelope around an empty array and nothing on stderr; in plain, it is a No <nouns>. note on stderr and nothing on stdout. Warnings and hints stay on stderr under either format, so meka … --format json 2>/dev/null | jq sees only the document.

meka session list --format json | jq -r '.sessions[].id'
meka mcp get notion --format json | jq .url

--oneshot

Exit after the first turn finishes. Requires either -p or --skill <NAME>; without one of those, meka has nothing to do. Useful for scripts and CI invocations.

meka --oneshot -p "summarize the last commit"
meka --oneshot --skill deploy -p "to staging"

-v, --verbose

Increase log verbosity. Can be repeated up to three times.

meka -v      # info
meka -vv     # debug
meka -vvv    # trace

-h, --help

Print help. -h is the summary; --help adds the longer prose under the flags that have it.

-V, --version

Print version.

Interactive mode

Start meka without --oneshot to open the interactive screen:

meka

The screen takes over the terminal, the way an editor does. A new session opens on meka’s mark, the M of its icon in the terminal’s cyan, two columns in, beside three lines: the version, with the commit the binary was built from (-dirty for a tree with uncommitted changes) and debug for an unoptimized build beside it when they say more than the version does; then what the agent carries for the session, the MCP servers and skills on one line, the memories it sees and the standing instructions in effect on the next, each file counted once and a flag or variable as one. It stands while nothing but a warning stands with it, and goes with the first prompt. The conversation fills the screen from the top; the composer sits at the bottom, a gray block with a bar of the permission level’s color down its left edge and a row of the gray above and below the text. The status row under the composer says, on the left, what the next prompt goes under, the permission level in its color and the profile the session runs on, then the session’s working directory (shortened with ~) and the project it is on, while it is on one; against the right edge it shows the context gauge (128.4k / 1.0M (13%): tokens in context, the model’s window, the share used) and 2 background tasks and 1 sub-agent while any run. display.status_row picks the facts and their order on each side, and can add the profile’s model. Type and press Enter. What you sent stays on the transcript in the same gray block, in white, behind the composer’s bar in the color of the permission level its turn ran under (red for a !command, gray while it waits for its turn to open, and for a prompt the log holds no turn for), and the answer streams in under it as it arrives, word by word, as rendered markdown: a list item hangs under its marker, and a table’s columns fit the window.

While the agent works, a row of its own appears above the composer, under the blank line that always keeps the conversation off it: a spinner in column 0, then what the agent is doing (Working, Thinking, Answering or Using a tool), how many seconds the turn has run, and Esc to stop. The spinner stands still as • while the turn waits on you, for an approval or a question, and the row goes when the turn ends. A !command has the same row, as Running command.

Everything on the transcript shares one left edge. Column 0 holds a glyph that says what a row is: ▎ a bar down what you sent, in the color of the permission level it ran under (red for a !command, gray while it waits for its turn), • something the agent or meka did (a tool call, a thinking block, a notice, a command’s outcome), ▸ a folded run of steps or a closed compaction and ▾ an open one, ! a warning, ■ an error, and nothing for the answer itself. No glyph is an emoji, so none is drawn as a picture. The text of every row starts in column 2. Color is spent sparingly: an answer’s emphasis is weight (bold is bold, headings are bold), the terminal’s cyan names things (inline code, a tool call, the checklist), structure (bullets, rules, the quote bar) is gray, red and yellow mean an error and a warning, and the permission level’s color marks what runs under it. A diff tints the lines it removes red and the lines it adds green. A code block sits on a gray shade of its own, and fenced code is highlighted from the same palette: comments gray, keywords blue, strings green, numbers yellow, names of functions and types cyan. A code line wider than the block folds at its edge, and a tab is drawn as four columns. The text is drawn in the terminal’s own colors, so the screen follows your terminal’s theme. Fixed are the shades behind the composer, a prompt, an open run and a code block, a diff’s tints and the marks on its lines, the white of a prompt’s words and of the profile on the status row, the gray of dimmed text on a shade, and a picture’s pixels.

A turn, its finished run of steps opened:

▎
▎ summarize the project
▎

▾ Thought once, ran a command, read a file, used a tool  1 failed

• Thinking · The user wants a summary of the project state. I should look at…

• shell_execute ls -la && cat notes.txt
  └ total 12
    drwxr-xr-x 2 k4yt3x k4yt3x 4096 Oct 11 09:55 .
    drwxr-xr-x 9 k4yt3x k4yt3x 4096 Oct 11 09:41 ..
    … +3 lines

• file_read missing.txt  failed
  └ failed to resolve path 'missing.txt'

• checklist_add Review the conflict section, Write the summary

• Checklist
  └ › Review the conflict section
    □ Write the summary

  Project state
  Here is a quick overview of where things stand.

The transcript is drawn from what meka knows, not written once and scrolled away, so what is on screen can be changed after the fact: a thinking block or a tool call is a block that expands and collapses, the whole transcript re-wraps when the window is resized, older turns load as you scroll up, and you can type while the agent works.

While a turn runs

Enter does not wait for the turn to end. What it does is the session’s send class. While a turn runs the empty composer names it: Steer the agent, Queue a followup or Interrupt the agent.

Alt+S cycles the class for this run; display.send_class sets where it starts. The prompt appears in the transcript with its class and reads waiting until the agent has read it. A slash command that would have to wait on the turn is refused while one runs; see Slash commands.

The steer and interrupt classes are the inbox the HTTP API exposes; see the inbox for what each one does inside the turn.

When the turn ends, a row closes it, in the same dim register as the other stage directions:

• Finished at 19:28 after 19m 19s

The opening words say how the turn ended (Finished, Interrupted, Failed, or Hit the output limit and Declined by the model for an answer that stopped short of being one), and display.turn_end_summary picks the facts after it: the time, the duration, the tokens used. A resumed session closes every recorded turn the same way, so the scrollback says when each one ended.

Expanding and collapsing

Reasoning shows as one dimmed • Thinking · … row: the first words of the block once it has ended, its latest line while it still streams, or the token count when the provider reports only that.

A tool call is its name and the one argument that identifies it, • file_read notes.txt. A path is shown as the status row shows the directory: relative to the working directory under it, with ~ for your home directory. An MCP tool’s mcp__server__ prefix is dimmed, and it is shown by the first of the call’s arguments that is text, else the first that has a short form (a number, a flag). A shell command is highlighted as code: its first line on the row, the next two on a │ bar under it, then a count of the rest, or the one line left where only one is. A leading cd into the working directory, which does nothing there, is dimmed. A call that failed says so on its row in red: exit 2 for a command, with the code it exited with, failed for anything else, a command stopped before it exited among them.

Under the call, behind a └, is the opening of what it produced: the lines up to the first blank one, at most three, each cut at the edge, and a count of the rest, or the one line left where only one is. A listing shows its header and first row, and a file its first lines; what a tool wrote for the model after its payload is counted rather than shown, and the directions meka writes into a result for the model are left out. What a tool said of a failure is red; a command’s output is its output, however it exited, unless it was stopped before it exited.

A call that changed a file, a memory or a skill (file_write, file_edit, memory_write, memory_edit, skill_write, skill_edit and the two deletes) draws the change as a diff in place of the words the tool wrote. The line before, the line taken out on a red tint with its old number, the line put in on a green tint with its new number, the line after, and … between hunks; a tinted line’s number and sign are in the tint’s light shade. Its row counts the change, +1 -1, and the arguments the diff already shows are left out of its expanded block. A memory’s diff is over the text meka memory export writes, so a reworded description is one changed line of frontmatter, and a delete is every line on red. Collapsed, a change gets twenty lines rather than the three of plain output, so a small edit shows whole and a rewrite shows its first lines and a count. A result keeps about 30 KB of a change’s lines, and counts the rest.

Either expands to the whole thing: the full reasoning, or every argument of the call wrapped in full and all of its output. The row drops its summary once the arguments are under it; they hang on a │ bar from the row down to the └ of the result, a shell command first, behind $, highlighted and wrapped whole. Nothing in an expanded block is cut.

A resumed session draws every call as it was drawn live: the diff, the code a command exited with and the checklist are recorded with each result.

• Click a block to toggle it. A block lights up under the mouse, which is the hint that it opens.
• Ctrl+T shows or hides every thinking block at once; Ctrl+O expands or collapses every tool call, and opens or folds every run of steps with them.
• Alt+Up and Alt+Down pick a block out from the keyboard, newest first; Enter or Space toggles the picked one, and Esc lets go of it.

Everything else on the transcript is what it was when it happened: the prompts, the checklist as it stood (the item in progress marked ›, the rest □, a deferred one » with its reason), the notices, the stage directions, and ! Interrupted where a turn was stopped. A slash command’s answer is not on the transcript at all; see Slash commands.

Folded steps

The thinking and tool calls the agent works through show as they happen. Once it writes something after them, or its turn ends, each run of them folds into one row that says what it did, in the order it first did each:

▸ Thought 3 times, ran 5 commands, read 2 files  1 failed

  Everything works from the new location. Now a top-level README so the layout is self-explanatory.

▸ Ran 2 commands, used a tool

How many of its calls failed follows in red. A run of one step stays as it is, and a change to a file, a memory or a skill, or an agent_spawn or agent_followup call, never folds: it stands between the runs around it. A change that failed changed nothing, and folds. A run whose call is still at work stays open, and a run that finishes while you are scrolled up is left as it is until you are back at the bottom, so what you are reading does not move.

Click a run’s row, or pick it with Alt+Up and press Enter, to open it under its row, and again to fold it. A folded run’s row starts with ▸, an open one’s with ▾, and an open run sits on a shade of its own from its row through its last step, so what it holds is told from what stands around it. A resumed session opens with every finished run folded. display.fold_steps = false leaves every run open until you fold it.

Images

An image goes with the next prompt. Paste or drag a path to an image file (png, jpg, gif, webp or bmp) onto the composer and the file is attached, or press Ctrl+V to attach the image on the clipboard. meka reads that from the operating system, since a terminal pastes text alone, so it needs a display on the machine meka runs on and does not work over SSH; a path does. Each attachment is a chip above the text, in the order attached, marked reading while the image is read beside the screen; Backspace on an empty composer drops the last one. Enter sends them with the words once every one is read; pressed before then, it sends nothing and the status row says an image is still being read. A photo is drawn the way up it was taken, and so is a copy meka makes of it for the model, shrunk or converted; one sent as it is keeps the orientation it records, for the provider to read. A skill or an MCP prompt typed with them takes them, and gives them back when it cannot run; any other command is refused while they are attached. The profile has to accept images ([profiles.<name>].vision), the limits are the HTTP API’s, and an image waits for the turn to end rather than riding on a steer.

The transcript draws each image sent, live and on a resume, in colored half-block characters, two pixels to a row: scaled down to the text width and at most 20 rows, its proportions kept, and transparent pixels left as the terminal’s background. It works in any terminal with 24-bit color, over SSH and inside tmux, at the resolution the cells allow, which shows an image’s layout and colors but not its small text. An image whose pixels do not decode, or with nothing in it opaque enough to draw, is the row [image 1280x720], with the size its header states, or [image].

Scrolling and the mouse

The wheel scrolls the transcript, a row for each event your terminal sends (display.wheel_rows moves it more); PgUp and PgDn scroll it half a screen, Ctrl+Home jumps to the top of what is loaded and Ctrl+End to the end. The view follows new output while it is at the bottom. Scrolling up pauses that, and ↓ back to bottom appears in the row above the composer, on the working row while the agent works, until you return: click it (it turns white under the mouse), press Esc, or send a prompt.

Once an answer has pushed your prompt off the top, the prompt’s first line sticks there as a bar. Click it and the prompt comes to the top of the view, with the prompt before it stuck in the bar’s place, so clicking on walks back through the conversation one prompt at a time.

The screen opens on the last page of the session’s log and reads the page above it whenever you scroll near the top, so a resumed session shows its last turns at once and the first scroll up reaches the ones before, however far back the session goes. What is held is bounded: scrolling far up lets the newest pages go, and scrolling back down reads them again; returning to the bottom always shows the end of the log with this run’s rows after it. Older history shows the conversation the log records, with a row for each compaction that opens to what it did; the turns a rewind dropped are left out, and one row in their place says how many went.

The screen captures the mouse so that the wheel, a click and a drag reach it. Dragging over the transcript selects the text it covers, and releasing copies it: to the terminal’s own clipboard through the OSC 52 sequence, which works over SSH and inside tmux where they allow it, and to the system clipboard where meka can reach one. The status row says how many rows went. What is copied is the text, not the screen: each row from the text edge, without the gutter’s marks, and a code block’s code as it was written, a line folded at the edge coming back as one line, its indentation its own, and the block’s shading adding nothing. The terminal’s own selection still works with its modifier held (Shift; Option in iTerm2, Fn in Terminal.app). Set display.mouse = false to leave the mouse to the terminal entirely; the keyboard still scrolls and toggles.

Inside tmux, the wheel needs tmux’s own mouse mode (set -g mouse on).

Keys

The composer takes the usual editing keys: Ctrl+A and Ctrl+E for the ends of the line, Ctrl+K and Ctrl+U to kill to either end, Ctrl+W to kill a word, Alt+F and Alt+B to move by word, and the arrow keys. It grows as you type, up to a third of the screen, and scrolls inside after that.

Input history

What you send is saved to the store, so Up, Down and Ctrl+R recall what you typed in any previous run. A brand-new meka, a resumed meka -c, and the current session all share one history. Multi-line prompts are kept whole, and only the most recent entries are kept (older ones are pruned). This input history is separate from the conversation itself.

Slash commands

Commands start with /. /help shows this table, with the /mcp subcommands beneath /mcp and the shortcuts below it. A command is not echoed on the transcript. What a command has to show (/help, /status, a listing) opens in a panel in place of the composer: Up, Down, PgUp, PgDn and the wheel scroll it, Esc or Enter closes it, and nothing of it stays on the transcript. What the screen holds the answer to works at any time, a turn running or not: the listings and pickers (/skill, /memory, /schedule, /task, /session, /help, /log), the settings (/permission, /approvals, /cd), /task cancel and /schedule cancel, and /exit. A command that needs the agent’s turn to be over (/compact, /rewind, /fork, /export, /title, /status, /usage, every /mcp verb and prompt, /skill <name>, /profile <name>, /project open <name> and /project close) is refused while a turn runs, in a panel naming it: stop the turn with Esc first, or wait for it to end. What a command does (set a level, change directory, cancel a job) is one dimmed • row on the transcript. What a command has to say back instead, a refusal, a failure or an empty list, is a panel as well, closed with Esc, and leaves no row. /log opens the last few hundred log lines at every level, newest last, whatever -v lets onto the transcript: a warning is a row as it happens, and the debug lines around it are there to read without restarting.

A bare /permission, /approvals, /profile, /project or /resume is a picker: the choices in a panel with the cursor on the current one, Up and Down (or j and k) to move it, PgUp and PgDn to move it by a page, Ctrl+Home and Ctrl+End to the ends, Enter to apply, Esc to leave it as it was. In /resume’s list, / starts typing a filter that keeps only the rows matching the text; Esc stops typing and keeps the filter, and a second Esc closes the list. With an argument each sets the value directly. A bare /skill, /memory, /task or /schedule is a picker too: the skills and memories by name and description, the tasks and jobs by id with what each is doing (a job that cannot fire is marked held), and Enter runs the picked skill or shows the picked memory, task or job in full. A bare /mcp lists the configured servers with their state, and Enter offers reconnect, login and logout for the picked one.

Some of the grammar the table compresses: a bare /mcp is /mcp list, and the picker shows each server’s live state (pending / connected / failed / disabled); /task cancel all is accepted for --all; /schedule cancel, /task cancel and the two shows take an id or any unique prefix; /cd ~ still goes home; /export writes session-<id>.md in the working directory and prints where it landed; /skill <name> prepends anything typed after the name to the skill body, and the transcript shows Running skill '<name>' with those words under it, live and on a resume, as it does Running prompt '<server>:<prompt>' for an MCP prompt; /memory lists memories most important first; /mcp login <server> puts the authorization URL as a question in the composer’s place, with one field for the callback URL pasted from the browser’s address bar when the browser cannot reach meka, and Esc on it ends the login.

Typing / opens the list of commands above the composer, each with its description, and the list narrows as you type. Up and Down move the pick, Enter runs the picked command, Tab fills it in so you can go on to an argument, and Esc closes the list until you type again. An argument’s list opens the same way: permission levels for /permission, on/off for /approvals, configured profile names for /profile, open and close then the project names for /project, installed skill names for /skill, the subcommands and configured servers for /mcp, and directory paths for /cd (Tab after a completed directory drills into its subdirectories).

/status

Shows the session’s resolved model parameters followed by its cumulative counters, in a panel:

/status
  Profile:         work
  Account:         claude (claude-subscription)
  Model:           claude-opus-5-5
  Context:         128.4k / 1.0M (13% used, 871.6k left)
  Effort:          xhigh
  Thinking:        adaptive
  Turns:           23
  Compactions:     2
  Input tokens:    234.5k  (cache hit: 92%)
  Output tokens:   12.1k
  Redactions:      2 (12 images, ~38.0 MiB freed)
  Messages:        47

The top block reports what the session actually resolved to, in the order [profiles.<name>] declares the same fields, so the two can be read side by side: the Profile with its account and backend, the Model, the Context window, the reasoning Effort sent on the wire (omitted when nothing is sent, so the provider applies its own default; claude-subscription sends high when the profile sets none), and the Thinking mode. The rest are cumulative counters for the session.

Context is the live context-window occupancy: the total tokens of the most recent exchange (all input tiers plus output, i.e. what the next request re-sends minus your new prompt), against the active model’s context window, with the percent used and tokens remaining. Use it to decide whether to /compact before continuing; after /compact it drops to the compacted size immediately. It reflects this session only; sub-agents spawned via agent_spawn have their own context and are not counted (a sub-agent’s returned result is counted only once it lands in this session as a tool result). It is shown from the start, at 0 / <window> before the first turn, since the window is your context_window setting (or the documented default) and this is where you confirm it took effect; it is omitted only when the window is unknown. The status row shows the same gauge at its right edge; display.status_row drops it or moves it among the readings there.

Input tokens (and the other cumulative counters) is the total billed across every turn of the whole session. These totals are persisted, so resuming a session with meka -c continues them rather than restarting at zero.

Compactions is how many times the conversation has been summarized, whether automatically, by /compact or at the agent’s request. It is counted from the session’s history, so it survives a resume, and each one puts the earliest detail one more summary away from the original.

cache hit is the share of input tokens served from the prompt cache rather than re-sent at full price, on every backend that reports one (Anthropic’s cache tiers, OpenAI’s cached_tokens). It should climb and stay high: meka keeps everything that changes mid-session out of the cached prefix, so a steady session re-reads the cache instead of rewriting it. The figure is arithmetic as much as it is health: every new token (a tool result, the model’s own reply) is written to the cache once and read on each later request, so the session-wide share starts at zero, passes 90% around the fifteenth request (each tool call is a request) and keeps climbing from there; a low figure on a short session is not a miss. Expect it to drop once after a /compact (which rewrites the head of the conversation) and to recover on the following turns. A profile with cache_control = false on an endpoint that caches only what is marked reads zero here by design.

Redactions reports any times an Anthropic backend had to drop the oldest tool-result image blocks because the request body would have exceeded the profile’s max_request_bytes (30 MiB by default, held under Anthropic’s own 32 MiB limit). A non-zero count indicates the cache prefix was invalidated for the redacted messages.

/usage

Fetches the account’s current rate-limit usage from the account the session’s profile bills and shows each rolling window with its percentage used and reset time, in a panel:

/usage
  5-hour (session)   [#---------]   8% used  (resets in 4h 12m, 2026-07-02 02:10 +02:00)
  Weekly             [----------]   2% used  (resets in 22h 50m, 2026-07-02 13:00 +02:00)

This is distinct from /status, which reports this session’s own token counters. /usage queries the upstream service for your whole-account subscription limits. It works only for the two subscription backends, which expose a usage endpoint (claude-subscription’s 5-hour and weekly windows; chatgpt-subscription’s primary/secondary windows plus plan and credit balance). For an API-key backend it prints a short note that usage is not available there instead. The same command is available under ACP.

/compact

The /compact command asks the LLM to summarize the entire conversation, then replaces the messages the model sees with a single summary message followed by the recent tail. This is useful for long sessions that are approaching the context window limit or becoming expensive.

After compacting, the session continues with the summary as context. The pre-compaction messages are never deleted: they stay in the underlying event log on disk (the model just no longer sees them). meka session export walks that full log, so an export always contains the entire conversation including the compacted-away turns, with a marker at each compaction point.

Every compaction, this command’s and the automatic ones, leaves a boundary on the transcript: a dim rule across the screen labeled →← Context compacted. While one runs, the working row reads Compacting the conversation. The rule starts with ▸: click it, or pick it with Alt+Up and press Enter, to open what the compaction did on a shade under it. First comes what set it going (Compacted the conversation on user request, Autocompacted the conversation after context usage crossed the ceiling, The agent compacted the conversation), then what departed from the ordinary case, when anything did: that no recent turns were kept after the summary, so the summary is all the agent has of the conversation, or that the standalone summarizer wrote it rather than the agent. Then the checkpoint turn’s thinking and calls (the memories it wrote, with their changes), each of which opens on its own as any call does, and last the summary the agent now reads in place of the conversation. A compaction before 0.88 recorded only the names of the memories its checkpoint wrote, so it opens to those and its summary. A resumed session shows the same rows, read back from the log.

/rewind

/rewind drops the most recent turn from the conversation, so the model no longer sees it or your prompt that started it. /rewind N drops the last N. The cut always lands on a turn boundary, so a tool call is never separated from its result. A compaction summary opens a turn of its own, so rewinding past everything after a compaction takes the summary with it and leaves the conversation empty; the turns it replaced stay behind the boundary on disk, and leave the screen with the summary that stood for them.

The dropped turns leave the screen too, now and whenever the session is resumed, and one row in their place says how many went. Nothing is deleted, though: like /compact, the turns stay in the event log on disk, and meka session export still shows them with a marker where the rewind happened.

Use it to take back a prompt that sent the agent down the wrong path without paying for a summary, or to recover a session the provider has started rejecting. meka repairs a rejection it causes itself (see below), but content that entered the conversation earlier is out of its reach; rewinding past it is the way back. meka session rewind <id> does the same to a session you are not currently in.

Recovering from a rejected message

Providers validate the whole conversation on every request, so one piece of content they reject would otherwise fail every later turn as well, permanently. When that happens, meka strips the offending content from what it added this turn, retries once, and hands the model the provider’s own complaint as a failed tool result so it can adapt rather than silently losing the data. If the retry is rejected too, the original content goes back untouched and the turn reports the provider’s error.

A mislabeled image already committed to the session is repaired when you resume it, without a provider round trip. For anything further back, use /rewind.

Recovering from a call that got no answer

A refusal is one thing the provider says; a request that never got a usable reply at all is another. A connection that fails or is reset while the request is going out is retried with backoff (up to twice, waiting 1s then 2s), and so is a response body that could not be read back. The turn continues as if the failed attempt had not happened, and nothing about it enters the conversation. Only when the retries run out does the turn report the error.

Worth knowing what a retry can cost. When the failure was a body that could not be read, the provider had already generated the response and billed you for it, so the retry pays a second time. meka does it anyway, because the alternative is losing the turn for content you have already been charged for once, but it is not free.

One failure is not retried, because the next attempt is known not to be worth making: a request meka could not build, which points at whatever went into it, most often a base_url that is not a URL or a stored credential carrying a character that cannot go in a header. A redirect is never followed at all: the endpoint’s answer is reported with where it pointed, and the fix is to set base_url to that endpoint. A reply, or one streamed event, larger than 64 MiB is refused for the same reason: an endpoint answering with something that size is not answering the request.

Retrying is bounded by time as well as by count, and the time bound is the one that usually decides. A failure that takes the full idle timeout to arrive costs five minutes, which spends the whole budget, so a stream that hung is reported rather than tried again: retrying is for a failure that was cheap, and a provider that went silent for five minutes has already taken more of your turn than a second silence is worth. Without the bound at all, three slow failures would be fifteen minutes of waiting on a turn that fails anyway.

The bound stops a new attempt starting rather than capping the total, so the worst case is a failure arriving just under the five minutes and permitting one more full-length attempt after it, for about ten in total.

/fork

/fork copies the current session and switches you into the copy, printing its id. Your conversation carries over untouched, so the branch happens exactly where you are; the original stops there and keeps everything up to that point.

Use it before trying a direction you might want to back out of, or before /compact if you’d rather keep the uncompacted conversation around. To go back, exit and resume the original with meka -r <old-id>.

The copy is a fully independent session with no link back to its source. (/fork only ever runs against the session you are in, which is never a sub-agent, so the sub-agent case below cannot arise here.) See Forking a session for exactly what it carries.

Shell escape

Type ! into the empty composer and it enters shell mode: the composer’s bar turns red, the status row reads Run command in shell in red in place of the level and the facts after it, and what you type runs as a shell command on Enter, bypassing the model entirely. Backspace on the empty composer leaves the mode, and a recalled !cmd comes back in it. On the transcript the command keeps its !:

▎
▎ !ls -la
▎

  total 32
  drwxr-xr-x  5 user user 4096 Mar  4 10:00 .
  ...

The command runs in the session’s working directory, so it follows /cd. Its output is captured and shown in the transcript, colors included, with a line naming the exit status when it failed. It runs beside the screen, which keeps drawing and counts the seconds on the working row; Esc or Ctrl+C kills it, with everything it started, and marks it ! Interrupted; so does leaving meka, a hangup or SIGTERM included. (On Windows the shell alone is killed.) Its output keeps its last 1 MiB and 10,000 lines, and a row says when more was let go. It reads nothing from the keyboard, and a command that needs the terminal itself (an editor, a pager) belongs in a shell beside meka.

Exiting

You can leave meka in any of these ways:

• Type /exit or /quit
• Type exit or quit
• Press Ctrl+D on an empty composer

Leaving while the agent is working stops the turn first, so nothing keeps running once the screen is gone; a !command still running is killed, and background tasks are stopped on the way out, with how many said.

The screen hands the terminal back as it found it. The session’s id is printed on the way out when display.show_session_id_on_exit says so; the conversation itself stays in the store, and meka -c reopens it.

Interrupting the agent

Press Esc or Ctrl+C while the agent is running to interrupt it. The two keys count on one ladder, and presses escalate:

1. The first press cancels the current turn: the request in flight is dropped and any shell command the turn spawned is killed. Background tasks keep running, because a keystroke aimed at the answer on screen should not lose a twenty-minute build.
2. A second press during the same turn stops every running background task, records each as canceled, and says how many it stopped.
3. A third press leaves, the way /exit does: what was canceled is given its moment to unwind, the background tasks are stopped, and the exit status is 130.

The count starts over with each new turn, so the first press of the next turn cancels that turn whatever happened during the last one, and it ends with the turn: a press during a wait that is not a turn (/usage, a stuck /mcp reconnect) starts a count of its own from the first step. When nothing is running, Esc goes back to the bottom of the transcript, and Ctrl+C clears a composer with text in it; on an empty one it counts on the ladder, so a second press stops the background tasks and a third leaves.

A question the agent asks replaces the composer until it is answered. An approval prompt is a panel titled with the call, its arguments under it and four answers to pick from: Allow (y), Allow for the session (a), Deny (n), Deny for the session, each also reachable by its number; Esc denies. A server that asks for a URL to be opened asks the same way, with Open in the browser (y), Skip (s) and Decline (n) to pick from. An MCP form takes typed answers, one field at a time; Esc declines. While any of these is open, Esc answers it rather than stopping the turn; Ctrl+C stops the turn, which withdraws the question. Questions are put one at a time: when two tool calls dispatched together both ask, the second waits until the first is answered.

One-shot mode

One-shot mode runs a single prompt and exits, similar to bash -c. It takes --oneshot and the prompt through -p:

meka --oneshot -p "your prompt here"
git diff | meka --oneshot -p -      # `-p -` reads the prompt from stdin

The agent works through the prompt, tool calls included, and when the turn ends prints its answer: the last text block the model wrote, as markdown source, terminal or pipe alike, since the output is for the next tool rather than for reading. Nothing else is printed. The thinking, the tool calls and the rest of the process are logged, so -v shows them. A run interrupted with Ctrl+C exits 130, whatever it had printed by then.

A prompt without --oneshot is not a one-shot run: it seeds the first turn and then leaves you on the screen, which is the right default when you are working interactively and the first thing you want is already in your shell history.

--oneshot requires something to do, so it needs -p or --skill.

An empty or whitespace-only prompt is refused rather than sent.

Approvals have nothing to ask from here: there is no prompt to answer, so with the switch on every tool that needs approval is refused. meka says so once at startup and names each tool as it is refused, but the run is still less useful than it looks. Give a non-interactive run the level it needs with --permission, or use meka serve if you need a human in the loop over an API.

Examples

# Simple question
meka --oneshot -p "what is my current working directory?"

# File operations (requires workspace permission)
meka --oneshot --permission workspace -p "create a file called notes.txt with today's date"

# Search
meka --oneshot -p "find all TODO comments in this project"

# Web page
meka --oneshot -p "summarize https://blog.rust-lang.org"

Combining with other flags

All configuration flags work in one-shot mode:

# Use a specific profile
meka --oneshot --profile work -p "explain this codebase"

# With workspace permission
meka --oneshot --permission workspace -p "run 'cargo test' and summarize the results"

# Ask the provider for a whole reply rather than a stream
meka --oneshot --no-stream -p "read README.md and summarize it"

# Run one turn against an existing session
meka --oneshot -r 550e8400 -p "summarize what we decided"

JSON output

--format json keeps stdout empty during the turn and prints one object when it ends, so a script reads the whole turn at once rather than parsing a stream. Errors still go to stderr and the exit code; no object is printed for a turn that failed. A turn interrupted with Ctrl+C is reported, not failed: its object is printed with stop_reason set to interrupted, and the run exits 130 as it does without --format json.

meka --oneshot -p "how many files are here?" --format json

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "profile": "work",
  "stop_reason": "end_turn",
  "text": "There are 14 files in this directory.",
  "tool_calls": [
    { "name": "file_find", "input": { "glob": "*" }, "is_error": false }
  ],
  "usage": {
    "input_tokens": 1180, "output_tokens": 42,
    "cache_creation_input_tokens": 0, "cache_read_input_tokens": 1024
  },
  "notices": [
    { "level": "warn", "text": "Approvals are on but nobody can answer here, so 'shell_execute' was refused without asking." }
  ],
  "compactions": []
}

stop_reason is end_turn, max_tokens, refusal (with refusal_text beside it when the model gave one) or interrupted. session_id is omitted, not null, for a turn interrupted before the session existed, which is the one way a run prints a report without one; every other field is always present. text is the assistant’s text with the rounds joined by a blank line, tool_calls lists every call in the order it was dispatched, and usage sums the rounds. notices is what meka itself said during the turn (a refused approval, a lost write, a declined MCP elicitation), each with a level of info or warn and its text; it is empty when meka raised none. compactions lists the compactions the turn ran, each in the shape of the HTTP API’s context.compacted event. The flag applies to --oneshot alone; a run without it is refused. meka account usage, whoami and stats take the same flag and values, and meka session export --format takes markdown or json.

Session behavior

One-shot mode creates a new session for each invocation, unless you point it at an existing one with -c (most recent) or -r <SESSION> (specific). Those run a single turn against that conversation and exit, which is the usual shape for scripting against a session built up earlier.

No session id is printed. --format json carries it as session_id, -v logs it, and -c resumes the most recent session without naming it:

meka -c

Piping

The answer goes to stdout and everything else to stderr, so meka -p … 2>/dev/null | next-tool hands the next tool only what you asked for. That holds for every command, not just this one.

A reader that stops reading is its own decision, and meka exits 0 for it:

meka -p "summarize this log" | head -20     # exits 0; head got its lines

A stdout that cannot take the answer is a different thing, and fails the run:

meka -p "summarize this log" > /full/disk   # exits non-zero, and says why on stderr

The distinction matters in a script: the first is how pipelines end, the second is data you asked for and did not get.

ACP (Agent Client Protocol)

meka acp speaks the Agent Client Protocol over stdio so editor / web / messenger clients can drive a meka turn end to end. Where Interactive mode and One-shot mode are for humans, ACP is for programs that want to host meka inside a richer UI: streamed diffs, native apply-buttons, hosted terminals, and slash-command palettes.

This page describes what meka’s ACP surface looks like to a client. Editor-specific setup belongs in each editor’s own documentation; the protocol contract is the same everywhere.

Starting an ACP server

meka acp

The process speaks JSON-RPC 2.0 with newline framing on stdio. There is no human-facing prompt; the binary is meant to be spawned by a client that owns the conversation. The client sends initialize, then session/new (or session/load / session/resume), then a series of session/prompt calls.

A few flags are worth knowing:

Three flags are refused rather than ignored: -c, -r and --project. Each names one run’s session, and this host creates one per session/new, each naming its own profile and project. A new session starts on the host’s default profile and on no project; move either with session/set_config_option, and session/load restores whichever a session already recorded. --profile is accepted, since it selects which configured profile a session gets when it names none, which is a property of the connection rather than of one session.

On startup, after the client’s initialize arrives, meka logs ACP client connected: <name> <version> so you can confirm the client identity under -v.

What meka advertises (agentCapabilities)

These are returned in InitializeResponse.agentCapabilities:

• loadSession: true: the client may call session/load with any persisted session id.
• sessionCapabilities.list: the client may call session/list to browse the persisted session catalog (cwd-filtered, cursor-paginated; sub-agent audit sessions are hidden).
• sessionCapabilities.resume: the client may adopt a persisted session id without replaying history.
• sessionCapabilities.fork: the client may branch a copy off a persisted session (see Forking). Unstable in the protocol.
• sessionCapabilities.close: the client may release the active session slot.
• sessionCapabilities.additionalDirectories: the client may send extra workspace roots on session/new, session/load, and session/resume (see Multi-root workspaces).
• promptCapabilities.embeddedContext: true: the client may inline @-mentioned file contents as embedded resource blocks (see Prompt turn).
• promptCapabilities.image: follows the process default profile’s vision flag (default true; set vision = false in [profiles.<name>] for a text-only model). Per connection rather than per session, because initialize is answered before any session exists. Whether a given session/prompt accepts an image block is decided per session from the profile that session runs on, so a session moved onto a text-only profile refuses attachments even on a connection that advertised image.

mcpCapabilities is intentionally not advertised. meka is itself an MCP client, but the servers it consumes are configured via meka’s own config.toml rather than the mcpServers field on session/new. Advertising HTTP/SSE while silently ignoring the client’s array would have been misleading; the marker will return when client-supplied MCP server connections are actually implemented.

agentInfo carries meka’s name ("meka") and the running binary version.

What meka consumes (clientCapabilities)

The client advertises these in InitializeRequest.clientCapabilities; meka stashes them and lets the built-in tools route accordingly:

• fs.readTextFile: true: file_read issues fs/read_text_file { sessionId, path, line?, limit? } so the client serves the in-buffer view of the file, when the client also takes writes. A regex read fetches the file the same way and filters it; an image read has no fs/* analog and stays local.
• fs.writeTextFile: true: file_write and file_edit’s apply step issue fs/write_text_file { sessionId, path, content }. meka still attaches diff metadata to the tool_call_update so clients with an apply-diff UI can render it, as it does for skill_write, whose file is in meka’s store; a memory write, which has no file, and a delete, which leaves no text after, carry their change as a unified diff in a diff code block instead.
• terminal: not consumed. It means “I implement terminal/*”, i.e. the agent may run commands in the client, which meka never does. See Shell commands stay inside meka.
• _meta.terminal_output: true: the client renders agent-owned terminals, so shell_execute output is streamed into a real terminal instead of a code block. A rendering choice only: meka still spawns and sandboxes the process either way. Advertised by Zed; independent of the terminal capability above.
• elicitation.form / elicitation.url: when an MCP server asks the user for input mid-tool-call, meka issues elicitation/create so the prompt renders in the editor. The two are advertised independently and checked separately: a server asking for a form when only url is advertised is declined rather than sent. Without the capability meka declines every elicitation, which is what it did unconditionally before. Elicitations raised inside a sub-agent forward to the parent session, like permission prompts.
• session.compaction: the client renders a compaction entry, so every compaction goes out as a compaction_update; without it, as a tool call card. See Prompt turn. Advertised by Zed.
• session.notices: the client presents notices outside the transcript, so an advisory meka raises goes out as a notice; without it, as a [meka] chunk. Advertised by Zed.

If the client omits a capability, the matching tool falls back to local syscalls; the user-visible behavior is the same as meka on the screen.

Shell commands stay inside meka

shell_execute never runs in the client’s terminal, whatever the client advertises and whatever the permission level. meka spawns the process itself so everything it wraps a command in keeps applying: the sandbox that read and workspace depend on (Landlock / bwrap / sandbox-exec / restricted token), the environment scrub that keeps API keys out of the child, the per-session cwd from /cd, the timeout, and the process-group kill that reaches backgrounded grandchildren. The client’s terminal/* offers none of that.

meka used to delegate in any level other than read, which made every sandboxed level a bypass: meka would refuse to run at all when no sandbox backend was available, then hand the same command to an unsandboxed editor terminal. Delegation is gone rather than narrowed, so workspace keeps its boundary here exactly as it does on the screen.

Live output

Because meka owns the process, it streams the output: while a command runs, what it has printed so far is pushed into the open tool call, so an editor shows a build or a test run progressing instead of a spinner. Updates are coalesced to at most one per 150 ms. stdout and stderr are interleaved in the live view, the way a terminal shows them, while the result the model sees keeps them separated.

How that output is drawn depends on the client:

Clients advertising _meta.terminal_output get an agent-owned terminal. meka announces one on the tool call, appends each chunk to it as it arrives, and closes it with the command’s real exit code and signal. The client renders a genuine terminal: ANSI color, selection, full scrollback, and an expandable view in the tool call. meka still spawns and sandboxes the process; the client only draws the bytes it is handed. Nothing is executed on the client side, and no terminal/* request is ever sent.

Everything else gets a console code block, replaced on each update with a trailing window of the output. The complete output arrives in the final update when the command exits.

The terminal path uses an extension rather than ACP proper: _meta.terminal_info to announce the terminal (on the opening tool_call, which is where clients read it), _meta.terminal_output to append, _meta.terminal_exit to close it with the command’s real exit code. The convention comes from codex-acp, claude-agent-acp emits the same shape, and Zed consumes it, advertising _meta.terminal_output: true to say so. Gating on that key rather than on terminal matters: a client that implements terminal/* but not these frames cannot resolve the terminal, and would render nothing at all for it.

This is deliberately temporary. ACP v2 standardizes agent-owned terminals as terminal_update / terminal_output_chunk, and meka should move to those once a client implements them; v2 is still a draft schema (v2.0.0-alpha.N, behind an off-by-default feature flag) that nothing speaks yet.

When the client won’t serve a path

Editors differ in which paths they will serve: Zed answers only for the project it has open, another client may serve any absolute path. meka models none of these rules. It asks per path and routes on the answer:

• ResourceNotFound (-32002) means the client will not serve this path, so it holds no buffer for it. meka reads or writes the file locally, and a write says so in the tool result: the change still appears in that tool call’s diff, but not in the editor’s buffer or undo history. This is what keeps ACP as capable as the terminal: the agent can read and edit its own skills, prompts, and configuration even though they live outside the project.
• Any other error means the client may own the file and hold unsaved changes for it, so the tool call fails instead of routing around the client. Reading on-disk bytes would hand the model a stale view of a file the user is editing, and writing them back would overwrite unsaved work.

The route is chosen once per tool call by the read, not per request: file_edit and file_write write back through whichever filesystem they read from, so a diff taken from the editor’s buffer isn’t applied to disk while the buffer keeps the old content. The read is also the more reliable signal: Zed reports an out-of-project path as ResourceNotFound on fs/read_text_file but as a generic error on fs/write_text_file, so a route chosen from the write’s own error would never recognize it.

A client advertising fs.readTextFile but not fs.writeTextFile leaves the write to meka, so file_read, file_edit and file_write read the file from disk as well: what the model reads is what its edit is computed from, and the edit lands where it was computed. The client still holds a buffer for the file, which the write diverges from; the tool result discloses that with its own note.

Session lifecycle

meka holds an in-memory map of sessionId → SessionEntry. Any number of sessions can coexist in one meka acp process, each with its own cwd, permission level, conversation, cancellation token, and per-session runtime mutex. Prompts on different sessions run in parallel; a second session/prompt for a session that already has one in flight is refused with InvalidParams. The session row is also locked on disk (the same lock the screen uses), so two meka processes can’t simultaneously write events for the same session id.

An unknown sessionId, a session another meka process holds, a sub-agent’s id, a turn over the profile’s max_request_bytes and a profile config.toml no longer has are all refused with InvalidParams; InternalError is reserved for faults in meka or below it.

What an InternalError’s data carries follows the same policy the HTTP API applies to a failed turn, so a deployment cannot have one surface withhold what the other publishes:

• The provider’s own response text travels only when [serve] relay_provider_errors is on, which is the default. It can name the operator’s account with the provider and its rate-limit posture; turn the key off and data carries meka’s sentence alone. Relayed text is capped at 4 KiB with the cut marked, and the full text goes to the meka log either way.

• An MCP server’s connection reason never travels. The server names do, since that is the part to act on; the reason is meka’s own subprocess text and has carried a command line and its path.

• A store or filesystem failure, and a [web]/base_url misconfiguration, never travel: they name meka’s own directories or the operator’s config. data says where the detail went.

• session/new { cwd, mcpServers }: mints a fresh persisted session, captures the cwd, takes the on-disk session lock, returns the session id and the current SessionMode state. mcpServers is ignored, with a warning naming how many entries were dropped; meka’s servers come from config.toml. On this and every other door, cwd must be an existing directory and is recorded in its canonical spelling (symlinks resolved), the rule the screen’s /cd and the HTTP API apply too; anything else is InvalidParams.

• session/load { sessionId, cwd, mcpServers }: replays the session’s log, its newest 2,000 rows without what a rewind took back, as a stream of session/update notifications (user_message_chunk, agent_message_chunk, agent_thought_chunk, tool_call, tool_call_update) before the response. The turns before a compaction are replayed too, and the compaction is said where it happened, as the live run said it: a completed compaction_update to a client that advertised session.compaction, else a completed card, then the calls its checkpoint made; never the summary as a user turn. The recent turns a compaction kept are replayed once. A background report replays as the stage direction the live run said, a parenthesized agent_message_chunk, never as the words the model read. A skill invoked by name replays as /<skill-name> and the words typed with it, never as its body; an MCP prompt invoked on the screen, which an editor has no command for, as the stage direction the screen says and then those words. A result is reported as the live run reported it, with the change it recorded and the result as rawOutput; a file edit’s change comes as a unified diff in a diff code block, since the log keeps the change and not the file. Orphan tool calls (the persisted log stopped mid-tool) are closed out with a failed status so the client’s UI doesn’t render a stuck spinner. If the client’s cwd differs from the persisted one, meka updates the persisted row to match; the client wins, but only once the session has actually opened, so a load meka refuses (a sub-agent’s id, a profile that has left config.toml, an account with no stored credential) leaves the session’s recorded directory and roots exactly as they were. mcpServers is ignored silently here and on session/resume. A sub-agent’s id is refused with InvalidParams before the session is locked; continue that conversation with agent_followup from the parent instead.

• session/list { cwd?, cursor? }: paginated index. Filtered to the requested cwd when present, compared in the canonical spelling every session records; sub-agent sessions are always hidden. nextCursor is opaque; round-trip it back to keep paging.

• session/resume { sessionId, cwd, mcpServers }: adopts the session id without replaying. Use this when the client already has the history rendered. Same cwd-update behavior as session/load, including that a refused resume writes nothing. A sub-agent’s id is refused on the same terms as session/load.

• session/fork { sessionId, cwd, additionalDirectories, mcpServers }: copies the session’s conversation into a new persisted session, adopts the copy as active, and returns its id. The source is left open and untouched. See Forking.

• session/close { sessionId }: cancels any in-flight prompt, waits for that turn to finish (the cancel does not cut short a file_read or an fs/* request already in progress), releases the on-disk session lock, and removes the entry from the map.

• session/cancel { sessionId }: interrupts the active session/prompt. The response carries stopReason: "cancelled". A cancel sent straight after a prompt still stops that prompt, even if it arrives before the turn has started: meka latches the signal and applies it as the turn begins. The latch is scoped to a prompt that is already on its way, so a cancel with nothing to stop is discarded rather than saved. Interrupting a turn, canceling twice, or canceling while idle all leave the next prompt you send to run normally.

• session/set_mode { sessionId, modeId }: flips the agent’s Permission cell. A level outside [permissions].enabled is refused with InvalidParams. On success, meka emits session/update: current_mode_update. The flip is atomic and applies to the next tool call within an in-flight turn; no need to wait for the turn to finish.

• session/set_config_option { sessionId, configId, value }: sets one of the entries in configOptions. Returns the full list with its new values. See Session config options.

session/new, session/load, session/resume and session/fork all answer with modes and configOptions, and each is followed by an available_commands_update (see Slash commands). --additional-workspace-directory on the meka acp command line adds to every session’s workspace, beside whatever the client sent as additionalDirectories; those are the session’s additional workspace directories at every level, writable at workspace and read-only at read as the working directory is, since session/set_mode moves the level while the session runs. --additional-readable-directory adds what every session reads beyond its workspace.

Idle sessions are released

A session untouched for 24 hours is dropped from the map by a sweep that runs every 5 minutes, releasing its lock and detaching its MCP registry. Only the in-memory entry goes, and the next session/prompt, session/set_mode or session/set_config_option naming it reopens it, in the directory and with the roots its row records, so a client that keeps a thread open needs no special handling; session/load reopens it with its history, as it does one from a previous run. Sticky approval answers go with the entry, so they reset here as they do on session/close.

session/close is optional in the protocol and several editors never send one, which is what this answers. Each open session holds an Agent, a tool registry the MCP manager keeps a clone of, and an open file lock, none of them reachable from anywhere else meanwhile. Neither the window nor the scan interval is configurable; both match [serve]’s defaults for the same mechanism.

Prompt turn

A session/prompt carries a prompt array of ContentBlocks. meka accepts:

• text: the baseline.
• resource_link: the model reads it as a <resource_link name="…" uri="…">description</resource_link> tag where the link sits among the words; meka does not fetch the resource server-side. A block that declares a MIME type adds mime="…" to the tag, here and on resource below.
• resource (embedded @-mention contents): a text resource is read as a <resource uri="…">…contents…</resource> tag where it sits; a binary (blob) resource becomes a self-closing <resource uri="…" encoding="base64"/> marker (the payload is not inlined).

Each resource is stored in its place among the words, so a session’s title reads the words around it, and session/load replays it as a resource_link named as the editor named it (an embedded resource by the last segment of its URI) rather than as its contents. A prompt that opens with /<skill-name> is the skill’s invocation, whole: the model reads the words and the files sent with them, then the skill’s body, and session/load replays it as the command and those words, each file as its @name.

• image: accepted only when the profile has vision on. The payload is normalized through meka’s image pipeline (size cap, format conversion) and forwarded to the model as native vision input (Claude image, OpenAI chat image_url, Codex input_image).

audio blocks (and image when vision = false) produce InvalidParams.

Images travel in the other direction too: when a tool looks at one (file_read on an image file, image_render, web_fetch on an image URL), the picture is forwarded on that tool call as an image content block rather than a placeholder, so the client renders what the model was shown.

While the turn runs, meka streams session/update notifications:

• agent_message_chunk for each piece of assistant text.
• agent_thought_chunk for thinking blocks (Claude OAuth / extended-thinking models).
• tool_call when a tool starts, with kind, status: "in_progress", an absolute locations array (relative paths resolved against the session cwd, with the start line for file_read), the raw input, and a human-readable title. The title is the tool’s name followed by the argument that identifies the call, so editors show what’s running rather than the bare tool name: file_read <path> / file_edit <path> / file_write <path>, web_fetch <url>, and the same under an MCP tool’s own name. shell_execute is the exception: its title is the command itself, whole and with its line breaks, because a client renders an execute call’s title as the command (Zed shows it in the terminal card and copies it from there, and shows no rawInput for that kind). This is also what claude-agent-acp sends.
• tool_call_update when a tool finishes, with the final status (completed / failed), a content array, and raw_output (the structured tool result). A call that never ran, its stream cut after it arrived, is closed failed before the turn’s next round, or when the turn ends there; one a session/cancel stopped is left for the client to mark, as the protocol has it mark every call unfinished at a cancel. A command left running in the background streams nothing more to its call. shell_execute output is wrapped in a fenced console code block so editors render it monospaced; file_edit and file_write populate diff content blocks so clients can render the apply-diff UI. (Large outputs offloaded to the scratchpad show the scratchpad reference rather than the full payload.) A call goes under the id the provider gave it, unless the session has already sent a call under that id (some providers reuse theirs every round, or give none) or the editor’s thread came from before (session/resume, session/fork, a session reopened after the idle sweep), in which case under one meka makes unique; every report of the call goes under the same id.
• plan whenever a checklist_add or checklist_edit call changes the checklist, so clients with a plan panel (e.g. Zed) render the open items. A deferred item is pending there, with what it waits on in its text; an emptied list is an empty plan.
• session_info_update once per session, carrying the title (the first user message’s words, cut to 200 characters) so a freshly created or loaded tab gets a label without a session/list call.
• compaction_update for every compaction, automatic ones included, when the client advertised session.compaction on initialize: in_progress under a compactionId when it begins, then completed with the summary as the model wrote it, failed with the error, or cancelled when you stopped it. _meta.compaction carries meka’s facts: trigger from the start, and once it lands the fields of the HTTP API’s context.compacted event. A client without the capability gets a tool_call of kind think instead, as claude-agent-acp sends one: titled “Compacting the conversation” while it runs, then completed under the compaction record’s own sentence with what set it apart and the summary as its content and those facts as its rawOutput, or failed with the error (“Interrupted” when you stopped it). Each call its checkpoint makes (the memories it writes, the files it reads) is told as it finishes, a finished tool_call carrying its result under an id that begins with the compaction’s, however the compaction then ends; a load shows them after the compaction.
• notice for an advisory meka itself raised during the turn (a lost write, an MCP elicitation it declined on your behalf), when the client advertised session.notices on initialize: severity is info or warning, and title carries the words the screen shows. A client without the capability gets the same words as a [meka]-prefixed agent_message_chunk, [meka warn] for a warning, so it can style the two apart. A scheduled job’s turn that failed or was interrupted is reported the same way, since it has no session/prompt response to carry its outcome.
• notice again for finished background work the model was shown, in the screen’s words: title is the stage direction (Background task 7f3a1c22 finished after 12m 4s), description the task’s label (one line per task when several report at once), and _meta.background.tasks the tasks as GET /v1/sessions/{id}/tasks lists them, outcome included, so a client that wants the result has it without the transcript carrying it. A client without session.notices gets the direction as a parenthesized agent_message_chunk, as a replay says it. The report the model read is shown to no client.
• A user_message_chunk carrying a scheduled job’s prompt, pushed by meka itself before the turn it fires runs, so the transcript shows what triggered it.
• usage_update after every provider round, carrying used (tokens currently in context: all input tiers plus output) and size (the model’s context window), so clients with a context gauge (e.g. Zed) show how full the window is while a long tool loop runs rather than once it ends; a turn that fails or is canceled reports its rounds too, and a compaction reports the estimate it leaves. One more on session/new, session/load, session/resume and session/fork, with what the row recorded, so a reopened session’s gauge is not empty until its first reply. Emitted only once the window is known.
• The session/prompt response additionally carries usage: what that turn spent, as the protocol defines it, in totalTokens / inputTokens / outputTokens / cachedReadTokens / cachedWriteTokens, a sub-agent’s and a compaction’s spend inside the turn included. This is the turn’s cost, not the gauge: usage_update answers “how full is the window”, usage answers “what did this turn cost”. A local command such as /status spends nothing and says so. thoughtTokens is omitted because meka doesn’t meter reasoning separately from output.

The response carries a final stopReason:

Permission levels

meka’s Permission levels map 1:1 to ACP SessionMode ids:

The full picker is advertised on every session-creation response (NewSessionResponse.modes, LoadSessionResponse.modes, ResumeSessionResponse.modes, ForkSessionResponse.modes) but only the levels in [permissions].enabled from your config.toml are listed; picking a disabled level would just error.

The same picker is also advertised as a configOptions entry, so a client that reads either field gets it; see below.

With the approvals config option on, a tool call above the active level triggers a session/request_permission round-trip instead of a refusal. Clients render four options:

• Allow: run this call only.
• Always allow any <tool_name>: run this call and skip the prompt for that tool for the rest of the session.
• Deny: refuse this call only.
• Always deny any <tool_name>: refuse this call and every subsequent call to that tool.

The sticky options name the tool because that is exactly their scope: the decision is keyed on the tool name and takes no account of arguments. The prompt’s title is <tool_name> <primary argument>, the tool’s name and the argument the indicator shows (for shell_execute, the command alone, as on the tool call), so for a shell command you are reading one specific command line while the sticky option covers every shell command the agent runs afterwards. If you want per-command control, use Allow and keep answering. The request’s rawInput, and a fenced json content block beside the title, carry every argument the call was made with, so a client that renders either shows what is being written and not only where. The request names the call’s card. A call the editor has not been shown opens one first: a compaction checkpoint’s call opens the card the call’s end completes with its result, and a sub-agent’s call, which the editor never sees, opens a card of the prompt’s own that closes with the answer as the screen says it (file_write allowed), leaving the agent_spawn call as it was.

Sticky decisions live in meka’s process memory with the session entry; they reset on session/close and when the idle sweep releases the session.

A prompt left unanswered for 30 minutes is denied, and the turn carries on; the HTTP API’s permission_required event has the same 30 minutes. This is a backstop against a client that is connected but will never reply (an editor whose UI thread has wedged, or a harness that speaks ACP without implementing prompts), not a deadline on you: session/cancel already resolves a prompt the moment you stop the turn, and without the backstop a client that does neither holds the session’s runtime mutex indefinitely, blocking session/close and session/set_mode behind it. Denying rather than allowing on expiry is deliberate: an unanswered prompt is not consent.

Session config options

Every session-creation response also carries configOptions, a list of options a client can render and change with session/set_config_option. meka advertises three, four where a project exists, in this order:

approvals takes the protocol’s boolean value, "type": "boolean", "value": true beside configId in the session/set_config_option params, where the two pickers take a bare value id and no type. A new session starts with [permissions].approvals from the config file; session/load and session/resume restore what the session recorded, since the switch is written to the session row like the level.

permission is deliberately advertised twice, once here and once in the legacy modes field. A client that only understands modes keeps the picker it has; one that reads configOptions gets permission and profile adjacent rather than in two unrelated menus. Setting it through either route does the same thing, and neither picker is left stale: session/set_mode pushes a current_mode_update and a config_option_update, while session/set_config_option pushes a current_mode_update and returns the whole refreshed list in its response.

A session whose recorded profile has since left config.toml cannot be loaded at all: session/load fails while building the runtime, so there is no entry for session/set_config_option to change. Restore the profile in config.toml, or move the session with meka -r <id> --profile <name> from a shell, and load it again.

Changing profile rewrites the session’s row, so it holds for every later turn and for a resume from any surface, not just for this connection. This is the same change /profile makes in the screen and PATCH /v1/sessions/{id} makes over HTTP. Switching mid-conversation is allowed and is your call: a thinking block is tagged with the backend that produced it and is not replayed to a different one, so from the next turn the model no longer sees the reasoning recorded under the old profile.

Changing project rewrites the row the same way, and the next turn’s context restates the memories the session now sees; a new session is on no project, and a name no project has is refused without moving the row.

While a turn is in flight either switch is refused with InvalidParams (cannot switch profile while a turn is in flight; cancel it first, or project), the answer a second session/prompt gets, and nothing is written. Reasoning effort is deliberately not offered: which tiers a model accepts is a fact about the provider’s system, and a fixed dropdown would be meka asserting it. It stays on the profile.

Slash commands

Two kinds of slash command are advertised through session/update: available_commands_update (after session/new / session/load / session/resume / session/fork, and refreshed at the top of every session/prompt so a skill installed mid-session shows up without a reconnect):

• Built-in local commands: /status (the permission level, then the screen’s block: profile, model, context usage, effort, thinking, compaction count, cumulative tokens), /mcp (configured MCP servers and their connection status) and /usage (the account’s rate-limit windows, subscription backends only). They render text back as an agent_message_chunk and end the turn immediately, with no model call. They take no argument, so a command followed by words, /usage looks wrong, why?, goes to the model as typed, and one sent with an image is refused with InvalidParams, since nothing would read the image.
• Skills (see Skills): each installed skill is a top-level command carrying a free-form input hint ("additional context (optional)").

When the user picks one from the palette, the client typically inserts /<name> and lets the user type extra context. meka parses the prompt as follows:

• A built-in local command (/status, /mcp, /usage): handled agent-side, output streamed back, turn ends with no model call. Checked first, so a skill can’t shadow a built-in (a skill named status, mcp or usage is dropped from the palette).
• Plain text (no leading slash): passes through to the model unchanged.
• /<skill-name> matching an installed skill: loads the skill body via the same path as the screen’s /skill command and prepends any extra context the user typed.
• Slash with a syntactically valid but unknown skill name (/nonexistent): passes through to the model unchanged, with a debug log. The filter false-positives on pasted text like /usr local lib, so a miss is read as “not a skill invocation after all” and the model can say it does not know the command. Only a skill that exists but cannot be read is an error (InternalError).
• Slash with content that isn’t a valid skill identifier (/etc/hosts, //comment): passes through to the model unchanged, so pasted paths and code comments don’t get intercepted.

Sub-agents

agent_spawn and skill-based delegation produce a sub-agent that runs through PermissionForwardingFrontend. The sub-agent’s own output isn’t streamed to the client (its final report flows back through the parent’s tool_call_update), but its permission prompts and fs/* requests forward through the parent’s connection, so the editor’s apply-diff UI sees a sub-agent’s writes the same as the root agent’s. A forwarded prompt opens a card of its own; see Permission levels.

ACP has no sub-agent primitive (no nested sessions, no nested tool calls), so a sub-agent is one tool call, and its progress is that call’s content. While it runs, each tool call it starts is appended to a rolling list (the last 20) and pushed as a tool_call_update on the parent’s agent_spawn call, so a long delegated task shows what it is currently doing instead of an opaque spinner. The whole list is resent on each update because clients replace a tool call’s content rather than appending to it. A nested sub-agent’s list is not forwarded further up: it already appears as an agent_spawn line in its parent’s list, and two writers on one tool call’s content would overwrite each other.

Multi-root workspaces

An editor whose workspace holds several folders (Zed’s Add Folder to Project) sends the first as cwd and the rest as additionalDirectories. Clients only send them when the agent advertises sessionCapabilities.additionalDirectories, so before meka advertised it every folder but the first was silently dropped and the agent would report files in them as missing.

What the extra roots do and don’t change:

• Search sweeps all of them. file_find and file_search walk every root when you don’t pass an explicit path. The 60-second walk budget is shared across the whole call, not granted per root, so a four-folder workspace doesn’t get a four-minute ceiling. Passing path searches exactly that tree, as before.
• A truncated file_search says which roots it skipped. Roots are walked in order starting from cwd, so a busy cwd can fill the 100-match cap before later roots are reached. When that happens the output names how many roots went unsearched, rather than leaving their absence to read as “nothing there”. Pass path to search one directly, or scratchpad to lift the cap. file_find is unaffected: its cap bounds only what it prints, so it still counts matches across every root.
• Overlapping roots are collapsed. A root nested inside another (or a repeat of cwd) is dropped, so its tree isn’t walked twice and its files aren’t reported twice. Symlinked duplicates aren’t detected.
• The model is told they exist. Each root is named in the per-turn environment context, alongside the working directory.
• Relative paths still resolve against cwd only. This is what the spec requires: cwd “remains the base for relative paths”. Use an absolute path to reach a file in another root.
• The shell still runs in cwd. shell_execute is unaffected.
• A stale root is skipped, not fatal. A root that no longer exists is passed over so the other roots can still answer; file_search reports “does not exist” only when no root existed. Root paths are escaped before they reach the glob engine, so a folder named 2024* or notes[1] matches literally instead of widening the search.

Every entry must be an absolute path; a relative one is refused with InvalidParams.

The list is persisted and reported back on session/list as SessionInfo.additionalDirectories, which is how a client rebuilds the workspace shape when you pick a session out of its history. session/load and session/resume carry the complete resulting list, so they replace what was stored rather than merging: reopening a session from a window that no longer has the second folder correctly narrows it, and an empty list clears the roots.

Forking

session/fork branches a copy off a persisted session: the new session starts with the source’s full conversation and continues from there, while the source stays open and unchanged. It’s the protocol’s way to explore a direction, or run something like a summary, without writing into the conversation the user is looking at.

The request is a session-creation request, not a row copy: it carries its own cwd and additionalDirectories, and meka applies those to the fork rather than inheriting the source’s. mcpServers is ignored, as on session/new. The response returns the new sessionId and the current SessionMode state, and the fork is registered as active immediately, so it can be prompted without a further session/load or session/resume.

There is no replay: unlike session/load, forking emits no session/update stream for the copied history, since a client that just forked already has the transcript rendered.

Sub-agent child transcripts are not copied, and a fork of an ordinary session records no link back to its source. session/fork answers InvalidParams for a sub-agent’s own id: the copy would be a sibling under the same parent and could not be driven, so the answer points at agent_followup from the parent instead. It answers InvalidParams for a source with a prompt in flight too, as a second session/prompt does, and for a source another meka process has open: either copy would end on a prompt nothing answered. See Forking a session for the full semantics.

This method is marked unstable in the protocol: it is not part of the spec yet and may change or be removed. Zed does not currently call it.

Known limitations

• A reopened session’s file diffs are code blocks. A session reopened with session/load shows a file edit’s change as a unified diff in a diff code block rather than the protocol’s diff, which the live run sends: a result records its change as numbered hunks, not as the two texts the protocol’s diff carries. The on-disk content is unaffected.
• Calls of one round under one id. A provider that gives two calls of one round the same id, or none, has an approval prompt or a command’s live output for either shown on the first one’s card, and two such sub-agents’ activity possibly on each other’s; each result reaches its own.
• terminal/* is never used: meka owns every process it spawns, so no command runs in the client’s terminal. Output streams into the tool call instead, as an agent-owned terminal where the client advertises _meta.terminal_output and a console block otherwise. See Shell commands stay inside meka.
• Image file_read: stays local. The fs/read_text_file request carries only text, so there’s no protocol surface to delegate it. A regex file_read fetches the whole document through the delegate and filters it locally.
• audio prompts: not supported; audio content blocks produce InvalidParams.
• No client-side model gate for images: when vision is on, meka forwards images to whatever model the profile names; a non-vision model returns a provider error rather than meka refusing up front. Set vision = false for text-only endpoints.

HTTP API

meka serve exposes meka as an HTTP API server so other programs can drive agent turns programmatically. Where Interactive mode is for humans at a terminal and ACP is for editor integrations over stdio, the HTTP API is for service-to-service use cases:

• A Telegram or Discord bridge that connects a chat bot to an agent.
• A web or mobile UI that streams assistant responses in real time.
• A script or orchestrator that embeds meka as a sub-agent backend.
• Any cross-language client that speaks HTTP+JSON.

All three entry points (meka, meka acp, meka serve) drive the same agent core: same tools, same profiles, same session persistence. The HTTP API is a transport layer on top. A shell script that wants one turn as JSON and no server can use meka --oneshot --format json instead; see One-shot mode.

Starting the server

meka serve

The server reads the [serve] section from your config.toml (see Configuration below). At minimum you need one bearer token; bind defaults to 127.0.0.1:8080:

[serve]
bind = "127.0.0.1:8080"

[[serve.tokens]]
token = "${MEKA_API_TOKEN}"
scopes = ["sessions:r", "sessions:w"]

On startup the server logs the bind address and begins accepting requests. All endpoints (except health probes and OpenAPI docs) require a valid Authorization: Bearer <token> header.

The server starts whether or not a profile is configured, unlike every other way of running meka, so an installation managed over the API can come up before its first account and profile exist and have them added through POST /v1/accounts and POST /v1/profiles. Until a session can get a profile, GET /v1/health/ready answers 503 with profile_configured: false, and a POST /v1/sessions that names no profile is a 422 carrying the configuration’s own sentence: no profile configured, or several and no default_profile. A body that names a configured profile is served either way.

Two flags are refused rather than ignored: -c and -r. Both name one run’s session, and the server creates one per POST /v1/sessions, each naming its own profile. Address an existing session by id under /v1/sessions/{id}, and pass profile on the create request. --profile is accepted, since it selects which configured profile a session gets when it names none, which is a property of the server rather than of one session.

TLS: meka serve speaks plain HTTP. For production, front it with a TLS-terminating reverse proxy (nginx, Caddy, Cloudflare Tunnel).

Under systemd, the unit lines in the shell tool’s Memory section keep a command that takes every byte from taking the server with it.

Quick example

Blocking turn (simplest)

# Create a session
curl -s -X POST http://localhost:8080/v1/sessions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"working_directory": "/home/user/project"}' | jq .id
# → "550e8400-e29b-41d4-a716-446655440000"

# Submit a turn
curl -s -X POST http://localhost:8080/v1/sessions/550e8400-e29b-41d4-a716-446655440000/turn \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "list the files in src/"}' \
  | jq -r '[.messages[] | select(.role == "assistant") | .content[] | select(.type == "text") | .text] | join("")'
# → "Here are the files in src/: ..."

Streaming turn

curl -N -X POST http://localhost:8080/v1/sessions/$SESSION_ID/turn \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "explain this codebase", "stream": true}'

The response is a text/event-stream (SSE) that emits typed events as the agent works:

retry: 3000

event: turn.started
id: 1793001600000000
data: {"turn_id":"...","session_id":"...","started_at":"2026-05-26T13:45:12Z","source":"client"}

event: assistant_text.delta
id: 1793001600000001
data: {"text":"This project is ","turn_id":"...","session_id":"..."}

event: assistant_text.delta
id: 1793001600000002
data: {"text":"a Rust workspace that..."}

event: tool_call.composing
id: 1793001600000003
data: {"id":"tu_1","name":"file_read"}

event: tool_call.executing
id: 1793001600000004
data: {"id":"tu_1","name":"file_read","input":{"path":"src/main.rs"},"display_summary":"src/main.rs"}

event: tool_call.completed
id: 1793001600000005
data: {"id":"tu_1","is_error":false,"content":[{"type":"text","text":"fn main() { ... }"}]}

event: turn.finished
id: 1793001600000012
data: {"turn_id":"...","session_id":"...","stop_reason":"end_turn","usage":{"input_tokens":12340,"output_tokens":567,...}}

Every payload carries turn_id and session_id; the later events above elide them. An id is an integer that rises by one per event across the session’s turns. Each time a server loads the session, after an eviction or a restart, the sequence starts again above every id it issued before, at the microseconds since the epoch, so a Last-Event-ID from before always reads as behind it.

Detached turn

curl -s -X POST http://localhost:8080/v1/sessions/$SESSION_ID/turn \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "refactor the parser", "detach": true}'
# → 202 Accepted, Location: /v1/sessions/.../turns/...
# → {"id":"...","source":"client","started_at":"2026-10-17T09:12:03Z","permission":"workspace","usage":{...}}

The turn runs whether or not this client stays. Its events are on the session feed, and its ending on the resource Location names; see Holding a turn.

Core concepts

Sessions

A session is a persistent conversation with its own working directory, permission level, and message history. Sessions live in the same store as screen and ACP sessions; they’re interchangeable.

POST   /v1/sessions           Create a session
GET    /v1/sessions           List sessions (paginated)
GET    /v1/sessions/search    Find sessions by the words of their conversations
GET    /v1/sessions/{id}      Get session details
PATCH  /v1/sessions/{id}      Update permission, approvals, working_directory, profile, title or pin
DELETE /v1/sessions/{id}      Close and clean up
POST   /v1/sessions/{id}/fork Branch a copy off a session

GET /v1/sessions is paginated. limit is how many to return (default 50, clamped to 1..200). Pinned sessions come first, newest pin on top, then the rest most recently updated first. When more remain, the response carries next_cursor; pass it back as cursor for the next page. include_children=true lists sub-agent sessions too, working_directory=<path> keeps only the sessions in that working directory, compared in the canonical spelling every session records, and parent=<id> lists one session’s direct children: the sub-agents it spawned, which is what a tree view asks for per expanded node, and what an audit asks to learn what a session dispatched. parent names sub-agents by definition, so include_children is moot beside it; a session with none, or an id no session has, is an empty page. profile=<name> keeps the sessions on one profile, project=<name> those on one project (project= those on none), pinned=true or pinned=false the pinned or the unpinned ones, and updated_since=<RFC 3339> the ones whose updated_at is after that instant: a turn or a change to what the session runs as, never a title or a pin. The filters compose.

When creating a session, specify the working directory and optionally a permission level, the approvals switch, a profile, a project, and capabilities:

{
  "working_directory": "/home/user/project",
  "permission": "workspace",
  "approvals": false,
  "profile": "work",
  "project": "webdev",
  "capabilities": {
    "supports_reasoning_stream": false,
    "supports_permission_prompts": true
  }
}

approvals is whether a tool call above the level is put to the client for approval rather than refused; see Approvals below. Omitted, it is the server’s [permissions].approvals. Every session response echoes both permission and approvals back.

Create, get, list, fork and PATCH all answer with the same session record:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2026-05-26T13:45:12Z",
  "updated_at": "2026-05-26T13:47:01Z",
  "working_directory": "/home/user/project",
  "permission": "workspace",
  "approvals": false,
  "profile": "work",
  "project": "webdev",
  "title": "list the files in src/",
  "last_turn": {
    "id": "7f3b...", "source": "client", "started_at": "2026-05-26T13:46:40Z",
    "permission": "workspace", "ended_at": "2026-05-26T13:47:01Z", "status": "succeeded",
    "stop_reason": "end_turn",
    "usage": {"input_tokens": 12340, "output_tokens": 567, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 8000}
  },
  "capabilities": {"supports_reasoning_stream": false, "supports_permission_prompts": true},
  "turn_in_flight": false,
  "approvals_pending": 0,
  "checklist": [
    {"id": 3, "text": "write the tests", "status": "in_progress"},
    {"id": 4, "text": "ask Sam about the venue", "status": "deferred", "reason": "waiting on Sam"}
  ]
}

checklist is the session’s open checklist: every item the agent has committed to and not yet disposed of, with its id, text, status (pending, in_progress or deferred), and on a deferred item its reason and the task it waits on when it waits on one. Present on a session this server holds; the feed’s checklist.updated carries the same list on every change.

created_at is when the row was made; updated_at moves on a turn and on any change to what the session runs as (permission, approvals, working_directory, profile, project), a PATCH included, but not on a title or a pin; title is the title a client set, else the first user message’s words, whitespace collapsed and cut to 200 characters. A pinned session also carries pinned_at.

last_turn is the session’s latest turn, whatever host ran it: the same record GET /v1/sessions/{id}/turns lists, carried here because a list of sessions is rendered from it, one row per session. id is the turn’s id, the one turn.started announced it under and every message it added names; source is who opened it (client, inbox, schedule, background, or parent for a sub-agent’s turn); started_at is when; permission is the level it ran under, the one its opening told the model, and for a turn still opening, such as the record a detached request’s 202 carries, the session’s level, which it opens under unless the level moves first. Once the turn has ended, ended_at says when and status how: succeeded, with its stop_reason (end_turn, max_tokens or refusal), failed, with an error carrying the same type and detail a Problem Detail would (never the provider’s own text), or canceled; profile names the fallback that served the turn when the session’s own profile could not (Fallback profiles), and is absent otherwise; and usage is what every round of it spent. A turn that began and shows no ended_at is either in flight, which turn_in_flight says, or one the process died under. Whether a turn is running now is a live fact of the process that no row stores. Together they answer the one question a session list asks: running, waiting on a person (approvals_pending above zero), or stopped and how. A turn refused before it began, by a 4xx or the 503 for a required MCP server, added nothing and leaves last_turn alone. The checkpoint turn POST /compact runs is announced on the feed under a turn_id of its own, for the events it emits, but is not a turn of the conversation: it has no row and no message names it.

On every response and event this API sends, a field that has no value is omitted rather than sent as null. On a session that means last_turn until a turn has begun, approvals_pending on a session this server does not hold, working_directory when the row recorded none, permission when the session is not loaded and its row records no level, and parent_id, which only a sub-agent’s session carries. The same rule gives a turn its refusal_text only on a refusal and a tool call its display_summary only when the tool has a label. It is also why meka session show --format json prints the same object for the same record: the row’s fields are one shape shared by both surfaces, and capabilities, turn_in_flight, approvals_pending and checklist are what the server adds to it.

profile names a profile in the server’s config.toml; GET /v1/profiles lists them, and a name that is not configured is a 422 whose detail reads no profile named 'x' (configured: a, b). Omitted, it is the server’s own default profile. The session keeps it for the rest of its life and every session response echoes it back as profile, so a client can confirm which account a session bills.

project names a project, which decides the memory tier the session’s writes land in and the tiers it sees; GET /v1/projects lists them, POST /v1/projects adds one, and a name no project has is a 422 whose detail reads no project named 'x' (configured: a, b). Omitted or empty, the session is on no project, and every session response echoes project back, "" for none. PATCH /v1/sessions/{id} with {"project": "movie"} moves a session onto a project and {"project": ""} takes it off one; the row is rewritten, and the next turn’s context restates the memories the session now sees. Like profile, it is a 409 when a turn is in flight.

To move a live session onto another profile, PATCH /v1/sessions/{id} with {"profile": "other"}. That rewrites the session’s row, so it holds for a resume from any surface rather than for this request. Switching mid-conversation is allowed and is your call: a thinking block is tagged with the backend that produced it and is not replayed to a different one, so from the next turn the model no longer sees the reasoning recorded under the old profile. Like working_directory, it is a 409 when a turn is already in flight; cancel first. A PATCH naming any of working_directory, profile and project holds the session while it writes, the way compact does, so a turn arriving meanwhile answers 409 rather than starting under it, and so does a second such PATCH. permission and approvals are the two fields that apply during a turn; see Permission levels over HTTP.

A PATCH naming a profile moves the session to that profile, and the profile is the whole story: the model, the account and every model-tied setting come from it, so there is nothing else on the row to reconcile. The row is also the billing record, so a profile the store cannot record fails the request; permission, approvals and working_directory still apply to the live session when their row write fails, and the failure is logged.

If you run more than one meka on the same store, send the PATCH to whichever process has the session. A body naming only a profile is the one PATCH that works on a session this server has not loaded, and it takes the session lock to do it, so a session another process is running answers 409 session-locked rather than moving a row that process would go on ignoring. Only the host holding a session may change what it runs on.

A body naming only profile is also the rescue for a session whose profile has left config.toml: it moves the row without building an agent, so it works on a session that cannot currently run. Adding permission or working_directory to the same body loses that, because those need a loaded session and loading one is exactly what fails; send the profile on its own first.

The working_directory field is validated on create, fork and patch, by the same rule the screen’s /cd and ACP apply:

• Must be an absolute path (no relative paths).
• Must exist on the server’s filesystem.
• Must be a directory (not a file, device, or socket).
• Must not contain null bytes (which cause kernel/userspace path mismatch).
• Is recorded, and echoed back, in its canonical spelling: symlinks resolved, . and .. removed. Every host records the same spelling, so a working_directory filter on the listing finds a session however its directory was spelled.

If working_directory is omitted, it defaults to the server process’s current working directory.

Sessions persist server-side until explicitly deleted or evicted by the idle timeout GC (see Session lifecycle).

Capabilities

Enabling supports_reasoning_stream costs a streaming turn its retry on a transient provider failure: the deltas have already reached you and a second attempt would repeat them, and reasoning is the first thing a turn produces. Blocking turns on the same session are unaffected, since they carry whole blocks rather than deltas.

Set supports_permission_prompts: false if you stream but have no interface to show an approval prompt on, which is the normal case for a service-to-service client streaming for liveness. Gated tools are then denied immediately with an explanatory notice, the same as blocking mode. Leaving it true means every gated call parks for 30 minutes and then denies anyway, which is hard to tell apart from a hang. Better still, create the session with permission: "workspace" so nothing is gated. The flag speaks for the streaming client: a feed reader that opened the stream with attend=true is asked regardless, since attending is that declaration made per connection.

Set answers_prompts_on_return: true on a session a person drives through a client that comes and goes, a browser tab say. A gated call in a turn no request holds, a detached turn, an inbox turn, a scheduled fire, then parks whether or not anyone is attending, survives the last attending reader leaving, and closes only on an answer, the turn’s cancellation or its 30-minute expiry; the client that comes back is handed it with the feed’s replay and answers it. The session is busy for as long as the prompt waits. A held turn keeps the grace rule, since its request leaving stops the turn anyway. Leave it false for a script or a service with no interface to show a prompt on, where the default refusal is the right answer.

Forking a session

POST /v1/sessions/{id}/fork copies a session’s conversation into a new session and returns it with 201 and the usual session body. The copy starts with the source’s full history and is immediately usable; the source is left untouched, and does not have to be in memory, so a GC-evicted session forks as well as a live one. A source with a turn in flight answers 409 turn-in-flight, as PATCH, DELETE, compact and rewind do; cancel the turn or wait for it. A source another meka process holds answers 409 session-locked. Either copy would have ended on a prompt nothing answered.

The body is optional and inherits everything by default. The only field is working_directory, matching ACP’s session/fork, which likewise carries a workspace but no permission or capability fields. An If-Match header holding the ETag of GET /v1/sessions/{id}/messages makes the copy conditional on the source being as it was read; see Detecting a rewritten history. Branching from a point is a fork under If-Match followed by a rewind of the copy, which nothing else can run a turn on in between:

{ "working_directory": "/home/user/other-project" }

Permission, approvals, capabilities and the profile are inherited and remain changeable afterwards via PATCH /v1/sessions/{id}. Sub-agent child transcripts are not copied, and a fork of an ordinary session records no link back to its source.

A sub-agent’s own id is refused with 422: the copy would keep that sub-agent’s parent and spawn terms, so it is a sibling under the same parent rather than a session this endpoint could hand back. See Forking a session for the full semantics.

Sub-agent sessions cannot be driven through this API

GET /v1/sessions?include_children=true lists the sessions an agent_spawn created. Those ids are readable through every endpoint on this page (/messages, /context, /export) and drivable through none of them: POST /v1/sessions/{id}/turn answers 422 with /errors/session-not-drivable, as do /compact, /responses/{request_id}, /fork, /schedule, and PATCH /v1/sessions/{id}. A sub-agent runs under the tools, permission ceiling and profile its spawn call set, which live in its spawn record and which only its parent can reconstruct, so the conversation is continued with the agent_followup tool from the parent rather than over HTTP.

A sub-agent is never a session this server holds: its parent runs it under the parent’s runtime. Its record still says when it is in a turn, because the parent’s run registers it for exactly as long as it runs, so turn_in_flight on a sub-agent’s record and in a listing is true while a spawn or a follow-up is running it; last_turn on its row says how its last run ended. While it runs, its id names its own event feed, which is read rather than attended; see A sub-agent’s feed. A prompt a sub-agent’s call parks rides the parent’s feed, with the sub-agent named, and the sub-agent’s feed mirrors it; see Approvals.

Two exceptions, both of which change a transcript without running anything on it. Teardown stays open: DELETE /v1/sessions/{id} discards a sub-agent and DELETE /v1/sessions/{id}/tasks/{task_id} stops one of its background tasks, and the parent’s own agent_delete does the same thing. So does POST /v1/sessions/{id}/rewind, which truncates the event log the same caller can already read in full through /export, and which meka session rewind has always allowed on a sub-agent. The line is whether the model runs: /compact is refused because compaction is a turn.

Importing an archive

POST /v1/sessions/import recreates a session tree from a meka session export archive under fresh ids, on the same terms as the CLI’s meka session import. An archive naming no profile takes the server’s default, the same one POST /v1/sessions applies to a body with no profile; a long-lived host always has one, since it refuses to start without it.

One limit is the server’s alone: an archive holding more than 1000 sessions is refused with a 422 whose detail names the count and the cap, and points at meka session import. The whole tree is written in one transaction on the process’s single connection to the store, so a larger one would hold every other in-flight request behind it. A one-shot meka session import restoring its own backup has nothing to contend with and so carries no cap; it is the way to restore a tree this large.

Everything else about the archive is honored as the CLI honors it; see Exporting a session.

Titles, pins and search

A session is labeled by its first words until someone titles it. PATCH /v1/sessions/{id} with {"title": "Research notes"} sets the title every surface shows from then on, the CLI and editor clients included, and answers with the updated record; an empty string clears it. A title is one line of at most 200 characters, whitespace runs collapsed, and a longer one is a 422. {"pinned": true} pins the session, which lists it first on every surface and spares it from the retention sweep; {"pinned": false} unpins it. Pinned sessions order among themselves by pinned_at, newest first, and pinning an already pinned session keeps its time. Neither field moves updated_at, so a rename does not reorder the list, and a body naming only these two, or only profile, works on a session this server has not loaded and on one another process is running.

GET /v1/sessions/search?q=<words> answers {"sessions": [...]}: the sessions whose conversations hold the words, best first, each the same record GET /v1/sessions lists plus an excerpt, the line of the best-matching message the words were found on, whitespace collapsed and cut short, marked (summary) when taken from a compaction summary. What is searched is what was said, user messages, replies and compaction summaries; tool calls, tool results and thinking are not. A session whose title holds every word comes first, with an excerpt only when its words matched too; the rest are ranked by their best message. Every word must appear; when nothing holds them all, the words are tried as prefixes, then sessions holding any of them, then any as a prefix. Words match by their stem and with every diacritic folded; scripts written without spaces match character by character. limit is how many at most (default 20, clamped to 1..100) and include_children=true adds sub-agent sessions. A blank q finds nothing. Requires sessions:r.

Detecting an in-flight turn

Session responses carry turn_in_flight, a boolean saying whether a turn is running right now. It exists so a client whose connection dropped can tell “my turn is still running” from “my turn died” without submitting a speculative turn and reading the 409. A dropped connection does not cancel the turn at once: a held turn runs until its next round boundary after the grace, a detached one to its end, and resubmitting would duplicate a reply the user is about to receive. Poll GET /v1/sessions/{id} and wait for it to go false rather than retrying blind.

The same holds for a held JSON turn whose client gives up: a request timeout on your side does not stop the turn until the grace is out, and a turn with a single round that is already under way ends as it would have. Read what completed from GET /v1/sessions/{id}/messages, and the turn’s ending from GET /v1/sessions/{id}/turns/{turn_id}. A client whose timeout is shorter than its longest turn sends detach: true instead; see Holding a turn.

turn_in_flight answers for this process: a session it holds, and a sub-agent it is running under a parent. A session another process is running, a screen open on it say, reads as idle, because only that session’s file lock knows and a read never probes the lock. Once a turn has ended, however it ended, last_turn on the record says how.

Turns

A turn is one round-trip: you send a user message, the agent processes it (potentially calling tools in a loop), and returns a result. Every turn that began is a row: GET /v1/sessions/{id}/turns lists them, newest first, each with its id, source, when it began and ended, how it ended and what it spent, in the shape last_turn on the session record shows for the latest one. limit is how many at most (default 50, clamped to 1..200), and when more remain the response carries next_before, the id to pass back as before for the page of turns older than it. Every message a turn added names it in turn_id, which is also the id its turn.started announced.

POST   /v1/sessions/{id}/turn              Submit a turn
POST   /v1/sessions/{id}/cancel            Cancel an in-flight turn
GET    /v1/sessions/{id}/turns             The turns that began, newest first
GET    /v1/sessions/{id}/turns/{turn_id}   One turn, with its ending once it has one

One turn at a time per session. A second POST /turn while another is running returns 409 Conflict. Across sessions, turns run fully concurrently. A client that would rather hand the message over and be told when the model read it uses the inbox instead of waiting for the session to be free.

POST /cancel takes an optional body {"turn_id": "..."}. Without one it stops whatever is running, as it always did. With one it stops only that turn, and answers 409 turn-mismatch naming the turn actually in flight when it is another, so a client that watched a turn cannot stop the scheduled fire or the inbox turn that replaced it. Every turn.started on the session feed carries the id to name.

The turn request body accepts six fields:

Holding a turn

stream and detach are independent. stream says how the response is encoded. detach says whether the request holds the turn: a held turn’s response ends with the turn, and the turn is stopped at its next round boundary once nobody has been listening for [serve] stream_reattach_grace, 30 seconds by default. A detached turn’s request is only the trigger: the turn runs for the session like an inbox turn, and only POST /cancel, a shutdown or its own failure ends it early.

A held request is for a client that is there for the turn: a killed curl should stop spending tokens whichever encoding it used. A detached request is for a client that cannot hold a connection open or does not want to, a browser tab that may close, a job runner behind a proxy with a short read timeout. The turn record a detached request is answered with is the row GET /v1/sessions/{id}/turns lists, with no ending yet; read GET /v1/sessions/{id}/turns/{turn_id} for the ending, or take it from the feed’s terminal event. The feed may announce turn.started before the 202 reaches you; correlate by turn_id.

A listener is any reader of the session feed, so a held turn with a feed subscriber attached is not stopped for its own request leaving. A detached stream is a feed reader narrowed to one turn: dropping it has no effect on the turn, and a reader that fell behind is caught up from the ring rather than ending the turn, as a feed reader is.

The inbox

POST /turn runs one turn for one request, the response scoped to it, and answers 409 while the session is busy. The inbox is the asynchronous door beside it, for a client that lives with a session rather than driving one turn at a time: a chat bridge, a UI, a parent process with something to say while the agent works.

POST   /v1/sessions/{id}/inbox              Enqueue a message
GET    /v1/sessions/{id}/inbox              Items the model has not been shown
DELETE /v1/sessions/{id}/inbox/{item_id}    Withdraw an item still waiting

The body is {"message": "...", "class": "steer" | "followup" | "interrupt", "source": "..."}. class is required and is the whole contract:

• steer reaches a turn that is already running. The loop reads the inbox at every round boundary, after a round’s tool results and before the next request, and appends what it finds to that same message, so the model sees it as soon as it next asks the provider anything. The end of a reply is a boundary too: a steer that lands while the model writes the answer that would end the turn follows that answer, and the turn goes on to answer it. This is what lets you correct or redirect the agent ten seconds into a ten-minute task, the way a person glances at a message mid-task.
• followup waits for the running turn to end.
• interrupt does not wait for the answer being written. While the provider is streaming, the stream is dropped within a second, the text that had arrived is kept as the answer so far, and the message follows it as the next thing the model reads; the same turn carries on, with no terminal in between, and the feed says so with a notice. A cut can land inside a thinking block or after a tool call was announced and never run: the notice is what closes those. While a tool runs, nothing is cut: the message is read at the round boundary after the tool’s results, exactly as a steer is. A profile that does not stream has nothing partial to keep: the reply being generated is dropped whole and the request goes again with the message. The cost is the request sent again, which the prompt cache mostly absorbs, and the part of the answer that was never written. For “stop, do this instead”; a steer is enough for “also, when you get to it”.

Every class rides the opening of the next turn when nothing is running, whoever starts that turn, and opens a turn of its own when nothing else does. A turn that has been admitted but has not yet sent its first request is not running yet in this sense: an item that lands in that moment rides its opening, whatever its class. The model reads each item under a header meka writes: [Message from <source>, arrived <time>], with while you were working added when it landed mid-turn. Without a source, or with a blank one, the header is [Message arrived <time>] and names nobody: who sent a message is the client’s to say, and meka does not guess it from the token that carried it. GET /v1/sessions/{id}/inbox omits source for such an item. The body is verbatim, so a client relaying text from strangers fences it itself.

The answer is 202 with the item and its state:

{"item_id": "...", "session_id": "...", "class": "steer", "state": "pending", "replayed": false,
 "retry_until": "2026-10-18T15:02:11Z"}

retry_until is the deadline for retries, the item’s enqueue plus [serve] inbox_retry_ceiling: an attempt that fails after it is not retried, and the item is given up on. An item not yet tried still runs when its turn comes, whatever the time, so under a short ceiling a fresh item can show a retry_until already past and be delivered all the same. A fresh item answers pending, unless a turn already running read it in the meantime. A replayed key answers with what the earlier item has become: beside its state, the not_before and last_error it shows while it waits, or the failure and last_error it was given up on with, so a producer that lost its place learns the item’s fate from the same call that enqueued it, without listing an inbox that no longer shows a withdrawn item.

An item is pending until its text is in the conversation, appended until the provider accepts a request carrying it, then delivered; withdrawn is a DELETE, a canceled turn, or meka giving up. Delivered means the model read it, not that it was written down: the feed’s inbox.delivered fires when the provider accepts the request, and names the turn that carried the item. A rewind that takes an appended item’s text out of the conversation before it was delivered offers the item again. GET /v1/sessions/{id} reports inbox_pending beside turn_in_flight while the session is loaded.

Idempotency-Key works here as on POST /turn: the same key with another message or class is refused with 409 idempotency. One difference matters to a bridge: the key is recorded on the row rather than in memory, so a retry that lands after a meka restart still finds its earlier item and answers it with replayed: true, and the key stays bound to that item for the session’s life, withdrawn or delivered. The item is durable before the 202; a session evicted for idleness is revived to run it, and a process that restarts finds it waiting.

A turn opened on inbox items that fails before anything from the model reached the conversation withdraws its prompt and offers the items again, when waiting can change the answer: the upstream could not serve the profile (an outage, a dropped stream, a quota or billing refusal), a required MCP server was not ready, or meka’s own store or disk refused (a lock another process holds, a full disk). Any other failure, a rejected credential, a request the upstream judged wrong, a profile that cannot read the session’s images, gives the item up at once, since every attempt would fail the same way. A retry waits 10 seconds, then twice that per attempt, up to five minutes between attempts, or less when the upstream said it would be back sooner (Retry-After, a quota reset); a stated time never makes it wait longer, since an account topped up early is noticed at the next attempt. Each deferral posts inbox.deferred on the feed and the webhook with the time of the next attempt and the error, and the item shows not_before and last_error, the same error as a Problem Detail (type, title, status, detail, never the upstream’s text), while it waits. Retrying ends at retry_until, the item’s enqueue plus [serve] inbox_retry_ceiling, an hour by default: the item is given up on, withdrawn, with inbox.failed on the feed and the webhook carrying the reason and the last error, so whoever is waiting is told rather than left with silence, and the item keeps that failure and last_error for a replayed key to answer; a canceled turn or a client’s DELETE withdraws an item with no error on it, since none decided it; "0s" gives an item up on its first failure. An item a tool round already carried into the conversation is not retried: it is history, and the next turn of any kind delivers it. An item on a session another process holds (a screen open on it, say) is asked about again every ten seconds until the holder lets go, or the holder’s own next turn carries it; those waits count toward the ceiling.

Only a pending item can be withdrawn. DELETE on one that is already in the conversation answers 409 inbox-appended, since only a turn can answer it now; a delivered or withdrawn one is 404. A DELETE that lands in the instant between a turn reading the item and writing it may still be read by the model. Canceling a turn the inbox opened, with POST /cancel, withdraws the items it opened on, the way a canceled client turn loses its prompt, and the feed reports each as inbox.withdrawn. The endpoint refuses a sub-agent’s session exactly as POST /turn does: a worker’s inbox is its parent’s, written with the agent_steer tool. No images in this release.