AMKernel

AMKernel — Automation MCP Kernel

Persistent Python execution for agentic automation.

面向 Agent 自动化的持久 Python Execution MCP。

AMKernel is a persistent Python execution MCP for agentic automation. Mobile automation through Appium is its first experimental vertical.

AMKernel 是一个面向 Agent 自动化的持久 Python Execution MCP。基于 Appium 的移动自动化是它的第一个实验方向。

Agents use ordinary Python automation libraries while retaining live objects, imports, and state across tool calls.

Why the name

• Automation — Appium, Playwright, Windows, macOS, and other automation environments. / Appium、Playwright、Windows、macOS 等自动化场景。
• MCP — the standard interface that attaches AMKernel to different Coding Agents. / 挂载到不同 Coding Agent 的标准接口。
• Kernel — a persistent Python namespace with object reuse, incremental execution, and interrupt recovery. / 持久 Python namespace、对象复用、增量执行和中断恢复。

Coding Agent
  → MCP
  → persistent Python kernel
  → automation library
  → external system

The first experimental vertical is mobile automation through Appium:

Coding Agent
  → AMKernel
  → Appium Python Client
  → Appium Server
  → XCUITest / UiAutomator2
  → mobile device

Future experiments may apply the same kernel to Playwright, Selenium, pywinauto, PyAutoGUI, macOS Accessibility, and other Python automation ecosystems. Those platforms do not belong in the core until experiments establish shared requirements.

Project principles

• Python execution is the primary Agent interface.
• State persists across MCP calls.
• The Agent uses official automation libraries directly.
• The kernel reports truthful execution and survival state.
• Text, structured values, images, and large artifacts are first-class outputs.
• Platform knowledge starts in project skills and experiments, not core abstractions.
• AMKernel is local stdio code execution first, not a remote multi-tenant sandbox.
• The core grows from measured experimental needs, not hypothetical platform unification.

Install for a project

AMKernel uses one user-level uv-managed Runtime and project-scoped Agent activation. From the project directory, run:

uvx --from amkernel amkernel install

Client detection prefers project markers and otherwise considers installed Agent CLIs. One candidate is selected automatically; multiple candidates open a single-choice prompt; no candidates offer all supported OMP, Pi, Codex, and GitHub Copilot clients. Non-interactive installation requires the complete automation contract; for example:

uvx --from amkernel amkernel install --client codex --scope project --yes --json

The installation plan labels its two scopes. User Runtime is the shared uv tool installation. Project Skill, Project Official Skills, Project Official source, and Project MCP belong to the current project. Each activated project still starts an independent Server, Runner, and kernel even though projects share the user-level executable.

The installer adds .agents/skills/amkernel plus every pinned official Skill selected by the manifest, extracts the complete pinned Appium Skills source under .agents/vendor/appium-skills, and writes only the selected Agent's native project MCP entry. Copilot applies one project MCP file at a time with whole-file precedence: the installer uses an existing .mcp.json, otherwise an existing .github/mcp.json, otherwise it creates .mcp.json. It preserves every other entry in the selected file, never creates a duplicate file or migrates between them, and leaves an inactive file untouched when both exist. Copilot also requires explicit folder trust before loading project MCP servers, so status reports that notice instead of claiming activation.

Use amkernel status, amkernel doctor, amkernel update, and amkernel uninstall for the managed lifecycle. amkernel uninstall --global is explicit because it affects every activated project.

Current phase

Stage 2 agent-quality output is implemented through the packaged stdio server and the single python_exec tool. One persistent Runtime now provides bounded live progress, recoverable stream artifacts, strict JSON and raster displays, explicit artifacts, requested-package diagnostics, descriptor-rooted workspace helpers, hard output-limit intervention, and truthful lifecycle/cleanup results.

Artifact resource URIs are ephemeral. Read and verify every manifest part before another large-output call or server shutdown. AMKernel detects Store tampering when a resource is read, but unrestricted same-user Python can access host-visible files; AMKernel is not a sandbox.

Supported environments

• CPython 3.11, 3.12, and 3.13.
• Current GitHub-hosted Ubuntu and macOS environments, where the native lifecycle and installed-wheel official-client matrices are required release evidence.

CPython 3.14, Windows, and other operating systems remain unsupported. The support claim is intentionally narrower than generic Linux or macOS package classifiers.

Canonical documents:

• docs/architecture.md — generic AMKernel core architecture.
• docs/development.md — agent roles, change ownership, development workflow, and quality gates.
• docs/stage-1-implementation-plan.md — accepted Stage 1 contracts, dependency order, ownership, behavior scenarios, and risk traceability.
• docs/stage-2-implementation-plan.md — accepted Stage 2 output, artifact, lifecycle, evidence, and support contracts.
• docs/project-management.md — GitHub-backed workflow, Kanban semantics, task contracts, ADR, and risk governance.
• GitHub Project — canonical milestone, status, stage, type, priority, and queue.
• GitHub Issues — canonical work-item, dependency, blocker, risk, and verification records.
• docs/decisions/ — accepted architecture and implementation decisions.
• docs/experiments/mobile-appium.md — first Appium/mobile experiment and success criteria.

Implementation follows the interfaces, invariants, and delivery order accepted in these documents.