Merced AI

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.

MVP capabilities

• 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.

Installation

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 --version

Python 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.

Quick start

Initialize a workspace:

merced-ai init
merced-ai harness list

Create 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."

Bind it to a harness:

merced-ai bot create reviewer \
  --profile reviewer \
  --harness codex \
  --fallback claude

Review the exact projection without launching a model:

merced-ai ask reviewer "Review the current diff" --dry-run --explain
merced-ai profile effective reviewer --harness codex

Run 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 ui

The 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.

Standards support

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 matrix

"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.

Storage

Project-local data:

.agents/                    OAP profiles
.merced-ai/bots/            bot bindings
.merced-ai/sessions/        normalized conversation sessions

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.

Security posture

• 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.

Development

ruff format --check .
ruff check .
pytest
python -m build

Unit and CLI tests use isolated filesystems and mocked harness processes. They do not call models or require network access.