Merced AI is a local-first broker for AI agent harnesses already installed on your machine. It discovers those harnesses, normalizes their noninteractive interfaces, and uses Open Agent Profile (OAP) documents to create portable bots you can chat and collaborate with.
Merced AI is deliberately not another agent loop. The selected harness still owns model access, tools, authentication, sandboxing, approvals, and final policy enforcement.
- Safe executable and version discovery for 14 harnesses, including Codex, Claude Code, Gemini CLI, OpenCode, Goose, Loro, MagAgent, DSH, Pi, Prime Agent, OpenClaw, and Kimi Code CLI.
- Reference OAP validation, digest calculation, profile discovery, and minimal profile authoring.
- Read-only AGS 1.0 validation and deterministic planning with digests, dependency order, reachability, worst-case execution bounds, cost/tier summaries, and explicit unsupported features.
- Project-local and user-global bot bindings with preferred and fallback harnesses.
- Honest native, projected, degraded, and unsupported profile projection reports.
- One-shot bot runs, multi-turn local chat, and attributed multi-bot group conversations.
- Durable, atomic project-local conversation sessions with resume support.
- Machine-readable JSON output for inventory, profiles, bots, dry runs, and results.
- Bounded subprocess execution without a shell, with timeout and Ctrl+C cancellation.
python -m pip install merced-ai
# optional UI
python -m pip install 'merced-ai[webui]'For development:
python -m pip install -e '.[dev]'
merced-ai --versionPython 3.11 or newer is required. At least one supported harness must be installed and authenticated for a real run. Inventory and dry-run workflows do not require model access.
See the installation guide for pipx/uv, platform-specific discovery, and explicit executable overrides.
Initialize a workspace:
merced-ai init
merced-ai harness listCreate a minimal OAP profile:
merced-ai profile create reviewer \
--description "Reviews code for concrete defects before merge." \
--instructions "Review code. Report verified defects and do not edit files."Or generate and review a canonical profile through an installed harness:
merced-ai profile generate "A cautious release reviewer that cites test evidence"
merced-ai profile generate "A portable documentation specialist" --scope universalThe Profiles page exposes the same prompt-driven path. Generation runs a temporary author profile
with tools and consequential permissions denied, compiles the result into OAP 1.0, and validates
it before creation. ~/.agentprofiles is the universal user root; Merced AI's native user root and
project .agents directory take precedence. Native MagAgent and Loro sessions can also use the
bundled oap-profile-authoring workflow to propose profiles for subagents without silently
activating new authority.
Bind it to a harness:
merced-ai bot create reviewer \
--profile reviewer \
--harness codex \
--fallback claudeReview the exact projection without launching a model:
merced-ai ask reviewer "Review the current diff" --dry-run --explain
merced-ai profile effective reviewer --harness codexRun or chat:
merced-ai ask reviewer "Review the current diff"
merced-ai chat reviewer
merced-ai group chat reviewer builder tester
merced-ai group ask reviewer builder tester --prompt "Give independent assessments" --json
merced-ai session list
merced-ai session resume <session-id>Launch the optional local UI:
python -m pip install 'merced-ai[webui]'
merced-ai uiThe UI binds to loopback and exchanges an ephemeral fragment token for an HTTP-only local session.
It uses the same profile, bot, routing, projection, session, and harness services as the CLI. You
can create profiles and bots, create single or group conversations, target @mentioned bots or ask
everyone concurrently, choose routes, approve or cancel runs, inspect authority and harness health,
and search/resume/export attributed transcripts. Group setup has searchable ordered selection,
progressive per-bot status, exact failed-bot retry, @mention completion, stable identities,
conversation naming, and derived participant sets. Workspace data renders before executable
probing; cached harness health then refreshes progressively in the background. The composer can
attach bounded project files and browser uploads, recent durable run records show context/events/
duration/partial failures, completion notifications are opt-in, and each active route exposes a
copyable native-harness handoff command. See the
UI guide and
group-chat guide for the security, dispatch, and streaming boundaries.
The layout is responsive down to a compact mobile collaboration view. See the mobile group-chat screenshot.
Use -C PATH on project-aware commands to select another workspace. Use --json on read and
one-shot commands for automation.
Merced AI 0.4.0 uses open-agent-profile>=1.0.1,<2 and
agentic-graph-spec>=1.0.1,<2. It claims OAP 1.0 Level 1 as a broker and AGS 1.0 Level 0 as a
read-only parser/planner. Merced AI does not execute AGS graphs, apply OAP state deltas, or replace
the selected harness's final policy enforcement. See the OAP conformance result,
AGS conformance result, and Agentic Graph guide
for the pinned revisions and exact boundary.
| Harness | Discovery | Execution | OAP projection |
|---|---|---|---|
| MagAgent | yes | native one-shot | native for project-discovered profiles |
| Loro | yes | native one-shot | native for project-discovered profiles |
| Claude Code | yes | structured print mode | system-prompt projection |
| Codex | yes | noninteractive exec | delimited prompt compatibility mode |
| Gemini CLI | yes | structured headless mode | delimited prompt compatibility mode |
| OpenCode | yes | structured run mode | delimited prompt compatibility mode |
| Goose | yes | structured run mode | system-prompt projection |
| Anton | yes | stdin REPL bridge | delimited prompt compatibility mode |
| DeepSeek Harness (DSH) | yes | headless profile | delimited prompt compatibility mode |
| Antigravity CLI (AGY) | yes | structured print mode | delimited prompt compatibility mode |
| Pi Coding Agent | yes | structured print mode | system-prompt projection |
| Prime Agent | yes | structured print mode | system-prompt projection |
| OpenClaw | yes | embedded local agent | delimited prompt compatibility mode |
| Kimi Code CLI | yes | read-only print mode | delimited prompt compatibility mode |
"Native" means the harness receives the OAP profile name through its own CLI. It does not mean Merced AI can supersede harness policy. Projection labels describe Merced AI's broker behavior, not certification of a selected harness's effective runtime. Native handoff remains bounded by that harness's own policy and diagnostics.
GLM is treated as a model-family route, not a separate harness. Use it through a supported host such as Claude Code, OpenCode, Goose, Pi, or Prime Agent. Kimi models can likewise be selected in multi-provider harnesses, while the dedicated Kimi Code CLI has its own adapter. See COMPATIBILITY.md for qualification status and caveats.
DSH can use a non-DeepSeek provider through its bundled llm-pi-ai settings. Kimi can use a
custom config selected with MERCED_AI_KIMI_CONFIG_FILE; standard provider environment variables
remain outside Merced AI. See the compatibility guide for a key-free DSH example and current live
qualification results.
Project-local data:
.agents/ OAP profiles
.merced-ai/bots/ bot bindings
.merced-ai/sessions/ normalized conversation sessions
~/.agentprofiles/ portable user profiles shared by compatible harnesses
User-global data defaults to ~/.config/merced-ai on Linux and follows the platform configuration
directory on Windows. Set MERCED_AI_HOME to override it for automation or tests.
OAP profiles remain the authoritative source for identity and learned state. Session JSON files do not replace profile state.
- Harness discovery never installs packages or scans the full filesystem.
- Child commands are passed as argument arrays with
shell=False. - Plaintext credentials are rejected by the OAP reference validator.
- Harness policies remain authoritative.
- Degraded profile injection is clearly reported and delimited.
- Runs time out, captured output is bounded, and cancellation terminates the child process.
- Automatic fallback happens only when a harness is unavailable, never after a paid or mutating run has begun.
See PRD.md for the full product requirements, security model, architecture, and roadmap. The documentation index links configuration, detection, troubleshooting, architecture, validation, and release guides.
ruff format --check .
ruff check .
pytest
python -m buildUnit and CLI tests use isolated filesystems and mocked harness processes. They do not call models or require network access.