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.
• 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 and multi-turn local chat.
• 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 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, opens with an ephemeral access token, and reads the same profile, bot, session, projection, and harness inventory records as the CLI.

The layout is responsive down to a compact mobile collaboration view. See the mobile UI screenshot.

Use -C PATH on project-aware commands to select another workspace. Use --json on read and one-shot commands for automation.

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. All current projection reports remain provisional until the runtime handshake and effective-policy reporting milestone is complete.

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.