cam-laya-mcp

Small local decisions for coding agents, powered by Laya-MLX. Your coding LLM still reads the repository, reasons, writes code, and explains changes. Laya-MLX chooses among short options for selected workflow transitions. It uses MLX on Apple Silicon, with no Laya cloud account, API key, or PyTorch runtime.

Project status: stopped — guard-only is the product; accelerator work ended

Decision (2026-09-29): efficacy work on this project is stopped. Four independent assistance ideas failed the same way, so iterating further would spend billed runs re-proving a negative. The safety guard below is finished and maintained; no new agent-assistance features are planned.

Why, with evidence:

• Model advice never earned its keep: deterministic rules matched 12/12 screened decisions vs 4/12 for raw Laya-MLX; every observed warm model call returned defer_to_agent after paying 0.1–0.4 s inference (37 s cold load). Model decisions stay opt-in.

• No whole-task speed gain in any paired screen: +4.5 s (M5, 30 runs), +0.75 s with CI crossing zero (M8 corrected 27-run screen), +0.2 s with CI crossing zero (24-pair guard screen, docs/milestone9-paired-summary.json).

• No token saving; one profile significantly increased use: PreToolUse+PostToolUse added 17,469 paired median tokens (95% CI +16,476 to +33,651).

• Retrieval without delivery is useless: the Milestone 6 tool was never called (0 calls across guided pilots) despite relevant rankings.

• Hints change actions, not outcomes: post-test git diff rose (7/9–9/9 vs 0/9) with zero fixes to an injected defect; Milestone 9 path hints hit 2/4 live targets and the candidate was removed per its stop rule.

• Billed cost was never attributable per Codex run, so no cost claim was ever supportable.

What remains true: the guard-only default passed its local gates (299/299 corpus, hook p95 ~40 ms, live safe-pass/destructive-deny on Codex and OpenCode) and needs no model, daemon, or account. See release readiness. OpenCode live guard execution is verified; Claude Code was never installed, so no claim covers it.

The corrected isolated Codex screen tested three coding tasks across baseline, full-hook, and PreToolUse+PostToolUse profiles (27 runs). Checks passed 9/9, 8/9, and 9/9, respectively. Neither hook profile showed a reliable speed gain; PreToolUse+PostToolUse used 17,469 more paired median tokens (95% CI +16,476 to +33,651). A six-pair PreToolUse-only screen was inconclusive for time and tokens. Codex billed spend was not measured. See the evaluation report and release readiness.

This remains an experiment for model advice, not a proven speed or cost optimization. A small 12-state screen favored deterministic rules (12/12) over raw Laya choices (4/12), so clear test/review transitions use those rules without model inference. The post-test hint increased git diff actions in the corrected screen (7/9 and 9/9 vs. 0/9 baseline), but a controlled Unicode-digit defect remained unfixed in all five hook trials. No post-test edits were recorded. Keep model decisions opt-in; do not claim productivity or cost gains. The guard-only default passed the Milestone 8 local gates, including isolated live Codex and OpenCode safe-pass and destructive-deny trials. Claude Code is not installed.

Related MCP server: lxDIG MCP

Quickstart

Default setup installs safety hooks on macOS or Linux with Python 3.11+. Once the package is installed, setup needs no Apple Silicon, MLX checkpoint, or uv:

cam-laya-mcp setup
cam-laya-mcp doctor

Optional model setup needs Apple Silicon, macOS 14+, Python 3.11+, and uv. On macOS with Homebrew, install uv with brew install uv if needed.

git clone https://github.com/vdqvinh2004/cam-laya-mcp.git
cd cam-laya-mcp
uv tool install -e .
cam-laya-mcp setup
cam-laya-mcp doctor

Plain setup installs owned PreToolUse safety hooks or the OpenCode pre-tool plugin. It adds no advisory MCP entry or session event for a new profile. setup --guard-only explicitly selects this mode. setup --with-model asks before installing missing Laya-MLX; setup --with-model --yes approves noninteractively. After approval, setup creates an isolated Python 3.12 runtime, downloads the checkpoint, runs a smoke decision, and adds owned MCP entries. Existing model-enabled profiles keep their preference and healthy owned access when setup is rerun. Model decisions remain disabled for new users. enable verifies the model first; disable leaves safety hooks active. Post-test guidance is off by default; set post_test_guidance = true in ~/.config/laya-agent/config.toml and rerun setup to register PostToolUse hooks.

Already have the source checkout? Start at cd cam-laya-mcp. Legacy cam-laya-mcp setup --yes still means explicit noninteractive model setup for existing automation.

The earlier laya-agent command remains an alias. Setup migrates MCP entries it owns to cam-laya-mcp; local config/state paths keep their existing names so upgrades preserve data.

The default checkpoint is aac6fef/laya-mlx, the published English MLX checkpoint in the current Laya-MLX README. Hugging Face stores it under ~/.cache/huggingface/hub/models--aac6fef--laya-mlx by default. The upstream repository does not state a fixed disk or memory requirement for every device; run cam-laya-mcp doctor and cam-laya-mcp benchmark on your machine. First download needs internet; inference after download is local.

To inspect checkpoint files and resident memory on your Mac, run du -shL ~/.cache/huggingface/hub/models--aac6fef--laya-mlx and ps -o rss= -p "$(cat ~/.local/state/laya-agent/agent.pid)" after a decision. du -L follows cache links; RSS is reported in KiB and includes the process beyond model weights.

Automatic use

Guard-only hooks run locally without a daemon. With explicit model setup and enable, unresolved decisions may start the on-demand Unix socket process; preload = true can load the model at session start. Clear test/review transitions use small deterministic rules; MLX handles choices without a known rule. With post_test_guidance = true, failed tests get a debug hint and passing tests can get a self-review hint; these hints do not load MLX by themselves. Codex and Claude Code register PostToolUse only when this setting is enabled and setup is rerun. OpenCode can block risky actions before a tool call and append enabled post-test guidance to the tool result; its plugin API does not provide a reliable channel for a nonblocking precommit hint.

Codex may show a hook trust notice after setup. Run /hooks, inspect the installed laya-agent definitions, and trust them. Until then, Codex skips those hooks. MCP registration alone never guarantees automatic tool calls.

For dangerous commands, Claude Code's hook requests a native approval. Codex currently documents ask as unsupported for PreToolUse hooks, so its hook denies the command; the user can run an approved command manually. OpenCode's plugin stops the command with an error and likewise requires a manual action. These client limits are not hidden by the MCP integration.

Hard risk checks inspect shell commands across pipes, command separators, environment wrappers, command substitutions, and sh -c scripts. They cover recursive forced removal, force pushes, Git commands that discard local work, find -delete, input piped into a shell, infrastructure deletion, privileged changes, and secret paths. Simple quoted examples such as echo 'rm -rf /tmp/data' no longer trigger command rules. This is a conservative static check, not a shell sandbox: commands assembled dynamically or hidden in scripts still require the coding agent's own review.

OpenCode may use OPENCODE_CONFIG_DIR or another live config source, including embedded integrations. Setup configures that directory, the default user directory, and paths reported by opencode debug config when they differ. opencode debug paths shows its general directories; opencode debug config shows the source the running service loads.

Example

User says “Fix the checkout bug.” The coding LLM inspects the repository and writes the patch. Before a risky command, the hard policy can block it. If the user enables post-test guidance, a failed npm test can produce a short debug hint. With model advice enabled, Laya can suggest targeted_test before commit. The LLM still does the debugging, testing, and review.

MCP server name: cam-laya-mcp. Tools: laya_status, laya_decide, laya_route_task, laya_risk_check, laya_next_action, laya_test_decision, and laya_review_decision. All responses are small JSON objects. A generic stdio MCP entry runs cam-laya-mcp mcp. Keep the stdio server open for repeated calls; it forwards decisions to a warm local daemon. Call decision tools when task state changes, using short facts. A decision is guidance, not permission.

The server advertises task-stage call guidance in MCP initialization instructions and individual tool descriptions. Agents choose whether to call tools; registration alone cannot force a call. Hooks invoke the same local daemon directly, so automatic hook activity does not appear as MCP tool calls. cam-laya-mcp stats reports mcp_decisions and hook_decisions separately. Restart an agent session after updating the installed server to load new MCP instructions.

For another MCP client, use its documented stdio server configuration with command /absolute/path/to/cam-laya-mcp and argument mcp. Generic MCP setup exposes tools but cannot guarantee automatic invocation; use the client's own lifecycle mechanism when it has one.

Commands

cam-laya-mcp status       # compact availability and warm-model state
cam-laya-mcp setup                # default safety setup, no model setup
cam-laya-mcp setup --guard-only   # explicit safety-only setup
cam-laya-mcp setup --with-model   # explicit MLX setup and MCP registration
cam-laya-mcp doctor       # environment, cache, MCP, and client checks
cam-laya-mcp test         # actual local smoke inference
cam-laya-mcp benchmark    # measured load, inference, cache timing
cam-laya-mcp stats        # local counts and explicitly estimated savings
cam-laya-mcp configure    # prints config path
cam-laya-mcp disable
cam-laya-mcp enable
cam-laya-mcp uninstall

uninstall removes only integration entries created by this tool. Optional --remove-runtime, --remove-model-cache, and --remove-config remove those items separately. The model cache may be shared with other tools, so it stays by default. Existing client settings are merged and backed up to .laya-agent.bak files. OpenCode .jsonc comments remain in the active file, grouped above its rewritten JSON object.

User config: ~/.config/laya-agent/config.toml. Set post_test_guidance = true and rerun setup to register successful-test review and failed-test debugging hints. State and a local Unix socket: ~/.local/state/laya-agent/. No prompt, command, source file, or credential value is written to the stats file. The model receives whitelisted short state facts, a short task or selected command when needed, and fixed choice labels. It receives no full conversation or repository source. Ordinary model failure returns defer_to_agent; failed risk checks require human review when mandatory_safety = true, and deterministic hard rules always apply. Confidence is a routing hint, never permission.

stats reports decisions by policy and source, escalations, cache hits, model failures, and latency. The local event log keeps one 1 MB backup; it contains decision metadata, never raw prompts, commands, or source. Savings remain zero unless a caller explicitly supplies would_call_llm: true for a decision that would otherwise need its own LLM call. The caller may also supply estimated_llm_tokens; these are counted under estimated_tokens_saved, never as exact usage. A count of Laya decisions is not a count of LLM calls avoided. benchmark samples the local machine; upstream published numbers are not reused as local results.

Repeated short tasks without secret markers and strictly shaped git push actions can reuse an in-memory decision by digest. Arbitrary commands stay uncached. Hook-supplied repository state includes a digest of changed-file names and file metadata, so a file change invalidates those decisions without reading source content. This is a best-effort cache guard, not a credential detector; do not put secrets in MCP requests.

Laya-MLX 0.2 warns that the published checkpoint has an uncalibrated choice:11+ temperature bucket. Task routing uses 12 labels, so laya_route_task returns reason_code: confidence_uncalibrated and does not use that confidence for threshold-based escalation. Other policies use at most ten labels.

Troubleshooting

• doctor says model unsupported: guard-only safety still works on supported macOS and Linux with Python 3.11+. MLX needs Apple Silicon and macOS 14+.

• Model missing: run setup --with-model on a network connection. The checkpoint is downloaded by Laya-MLX on first load.

• Codex hooks skipped: inspect /hooks and trust the exact installed definitions.

• MCP unavailable after explicit model setup: run cam-laya-mcp doctor, then rerun setup --with-model; existing unrelated MCP entries are preserved.

• Model failure: run cam-laya-mcp test for a smoke check, then benchmark only after it passes.

Development

uv sync --extra test
uv run pytest -q

Source-backed client capability choices and limits are in ADR 0001. The v0.1.0 release audit records validation and open gates. Spec Kit milestones keep each milestone's plan and tasks in its own numbered folder.