zymi-core is an auditable MCP backend for AI agents. Its core idea is to compile the operation flows that agents converge on through trial and error into declarative YAML pipelines, so that these flows can run stably and reproducibly even when the agent is not present. It is positioned as a governed, reproducible low-level execution layer, not an autonomous agent, IDE plugin, or chat interface.
Purpose When users ask a coding agent to add a VPN user, deploy a service, or clean up a server, the agent often needs repeated trial and error to complete the task; a week later, when performing a similar task, the agent may re-derive slightly different steps, or be unable to execute due to rate limiting or being offline, and no one remembers the specific steps. zymi targets this scenario by solidifying the flows agents converge on into YAML pipelines: most steps are deterministic tool calls, with LLMs introduced only where judgment is truly needed. After that, pipelines can run independently of the agent, or be invoked by the agent as a single MCP tool, dangerous steps require human approval, and every run has a tamper-evident event record.
Main capabilities Pipelines: composed of steps with depends_on edges forming a DAG, where independent steps can execute in parallel. Step types include: deterministic tool steps (direct dispatch, parameter templating, no LLM jumps), agent steps (LLM ReAct loops with a tool allowlist), and ask steps (the run pauses and asks the caller a question, answered by a human in the terminal or by the connected agent under MCP, then resumes). Steps can carry when conditions to implement branching; skipped branches cascade to descendants and are recorded as StepSkipped events. Tools: supports four categories of tools, cataloged uniformly. Declarative shell/HTTP tools are written in tools/<name>.yml with no code required; Python @tool is written in tools/<name>.py, supports sync or async, signatures are automatically mapped to JSON Schema and automatically discovered, and runs in the project's own .venv; MCP servers, where one mcp_servers: entry provides N tools, namespaced as mcp__<server>__<tool>; built-in tools include read_file, write_file, write_memory, execute_shell_command, spawn_sub_agent. All four categories of tools emit the same ToolCallRequested / ToolCallCompleted event. MCP server: expose pipelines as MCP tools over stdio via zymi mcp serve, for use by Claude Code, Claude Desktop, Cursor, or any framework with an MCP adapter. Exposure is selectively enabled per pipeline. Approvals are presented in the caller's UI, and gated steps send elicitation/create through the active tools/call, appearing in Claude Code as an approve/reject form; clients that do not support elicitation fail closed. ask: steps borrow the caller's reasoning capability, and task-augmented calls enter the input_required state carrying { prompt, resume_token }, which the agent answers via zymi/reasoning/resume, and the answers are recorded to guarantee byte-identical replay. --expose-observability adds read-only zymi.runs.list / .get / .events / .step_io, letting the agent debug its own runs. Approvals: setting requires_approval: true on a tool publishes an ApprovalRequested event and routes the human decision back through a channel. Channels include terminal, http, telegram, mcp_elicitation. Resolution order is pipeline override → project default → fail closed. A crash mid-approval can be repaired after restart. Replay, recovery, and observation: every state change is an immutable hash-chained event, replayable, resumable by forking from any step, browsable in the TUI, or readable by the agent as its own run trace to explain failures. Long-running services: zymi serve responds to events from declarative connectors (http_inbound, http_poll, cron, file_read, stdin) and answers through outputs (http_post, file_append, stdout). It uses SQLite by default, and multi-process shared state can be configured with a one-line postgres://…. Context window management: the agent's context is rebuilt from the event log on each iteration rather than accumulated in a buffer; older observations are masked in place, and only if the budget is still tight is a single summarization call usedto compress the oldest batch. Python embedding: after installing zymi-core in the project venv (uv add zymi-core), the same wheel exposes Runtime, Event, EventBus, EventStore, ToolRegistry, and the @tool decorator.
Usage Install uv (if not installed): on macOS/Linux run curl -LsSf https://astral.sh/uv/install.sh | sh, on Windows run irm https://astral.sh/uv/install.ps1 | iex. ~/.zymi is an ordinary zymi project, and when not inside another project all commands fall back to it. You can add your own pipelines (for example, a site check), allow commands in ~/.zymi/project.yml (policy.allow: ["curl *"], commands not listed will first request approval), then run zymi run site_check. Runs, arguments, and output are recorded in ~/.zymi/.zymi/events.db, viewable with zymi observe. Point any MCP host at that library, and every pipeline with an expose.mcp: block becomes a tool. Model endpoints can be declared once per machine in ~/.zymi/providers.yml and referenced by name (llm: neuraldeep or llm: { use: neuraldeep, model: other }), with keys stored in ~/.zymi/.env. Providers that cannot be resolved only disable agent steps; pure tool pipelines still work. Commands use --dir, otherwise if the current directory is a project it uses the current directory, otherwise it uses ~/.zymi.
Applicable scenarios Suitable for scenarios that need to solidify operational workflows repeatedly derived by agents into reproducible, auditable pipelines, such as operations, deployment, user management, site checks, etc.; also suitable for teams that want to provide governed processes to coding agents in the form of MCP tools, and environments that need approval gating and event-sourcing records.
Limitations The official documentation clearly states: approval waits inside asynchronous tasks depend on host adoption and will time out (synchronous calls are fully interactive); cancellation is best-effort; arguments are passed as strings across boundaries; mcp serve currently only supports Unix. zymi is intentionally not an autonomous agent, IDE plugin, or chat UI.
