agent-surface

Write your coding-agent setup once, render it into every agent host.

Commands, rules, subagents, external skill packs, ignore files, and first-party MCP services live once in this repo's source tree. agent-surface compiles them into the native formats of twenty-one host targets — Claude Code, Codex, Cursor, Droid, Kilo, Zed, OpenCode, OpenHands, and more — so you maintain one source instead of twenty-one bespoke configs.

It is a source compiler, not an app: there is no src/. Typed source primitives in → host-native surfaces out, validated by check and tracked by per-target manifests.

Quick start

npm ci
npm run check                      # validate source, registry, generated output
npm test                           # integration tests
npm run build -- --target all      # render every target into dist/

Preview an install before touching disk, then apply it:

node scripts/agent-surface.mjs install --target claude-code --scope user --dry-run
node scripts/agent-surface.mjs install --target claude-code --scope user --allow-scope-root
npm run install:mcps               # build + link the Synapse/Grimoire binaries the wired MCP configs point at

The install step wires each host's MCP config to point at ~/.local/bin/synapse-bridge and ~/.local/bin/grimoire-server; npm run install:mcps builds and links those binaries (and deploys the Synapse sidecar service). Run it once — the two steps together are what makes MCP actually connect.

What it does

• Compiles source primitives — commands/, rules/, subagents/, external packs, ignores/ → per-target outputs via explicit producers.
• Speaks each host natively — each target gets the surfaces it understands: commands, workflows, skills, instructions, plugins, rules, subagents, MCP config, or ignore files.
• Wires first-party MCP — Synapse (shared memory) and Grimoire (just-in-time skill retrieval) auto-merge, secretlessly and non-destructively, into all 18 MCP-capable hosts (JSON, TOML, and YAML config families).
• Installs deterministically — dry-run previews, project-scope gating, manifest tracking, generated-file strict-sync, and non-destructive config merges that preserve unknown sibling entries.

Supported targets

Twenty-one targets, ranked 1–5 by how much of the source model maps to native surfaces. Six score 5/5 (Codex, Cursor, Droid, Kilo, Antigravity CLI, OpenCode); instruction-only hosts (Copilot, VS Code, Trae) score 2/5.

Full matrix — per-target surfaces, file counts, and MCP wiring: docs/reference/targets.md.

Out of scope: Gemini CLI (EoL — use Antigravity CLI), Roo Code (EoL), Xcode.

Project layout

commands/    User-invoked reusable procedures
rules/       Always-on or scoped behavior policy
subagents/   Normalized subagent definitions
mcps/        First-party MCP services (synapse, grimoire)
ignores/     Project ignore templates
registry/    Target, capability, optional-service, and source-kind policy
schemas/     JSON schemas for registry and workflow artifacts
scripts/     CLI compiler and helpers
adapters/    Per-target install docs (one README each)
external/    Optional git-submodule skill/service packs

Local IDE overlays (.cursor/, .claude/, .kilo/, …) stay gitignored on maintainer machines; build/install render committed source into them.

Commands

node scripts/agent-surface.mjs inventory          # source counts
node scripts/agent-surface.mjs check              # full validation (commands, rules, generated, registry)
node scripts/agent-surface.mjs doctor             # repo health summary
node scripts/agent-surface.mjs commands --json    # registry inspection (add --phase <phase> to filter)
node scripts/agent-surface.mjs build --target <t> --dry-run
node scripts/agent-surface.mjs install --target <t> --scope user --dry-run

install accepts repeated/comma-separated --target (or --runtime) IDs and --category outputs (commands, rules, subagents, skills, recipes, mcps, external, instructions, prompts, plugins, ignores). --service <id> narrows --category mcps to one service.

Install behavior

• Sync-oriented: existing managed files are overwritten; manifests let stale outputs be pruned on the next install.
• Project-only artifacts (ignores/) are skipped on user-scope installs — pass --dest <project> to write them.
• A live write to the real scope root needs --allow-scope-root (or an explicit --dest) after a dry-run.
• First-party secretless MCPs (Synapse, Grimoire) are generated by default for MCP-capable targets and merged into existing host config; external/secret-bearing MCPs stay opt-in via --category mcps --service <id>.
• External skill packs (the in-scope optional packs) are included in a full install and pruned by strict-sync when they leave scope; --category external narrows an install to external packs only. The 754-skill anthropic-cybersecurity-skills pack is deliberately not emitted (it is a source-pack with no skill_roots) and is served just-in-time by Grimoire instead.
• Install manifests in .agent-surface/<target>-manifest.json track generated files and owned config entries. Full installs overwrite current generated assets, remove previously owned stale assets, and preserve unknown sibling config entries.

First-party MCP services

Built from mcps/, installed once, then auto-wired (non-destructive merge) into all 18 MCP-capable hosts across JSON/TOML/YAML config families — see docs/reference/targets.md:

• Synapse — shared multi-agent memory + file-lock coordination.
• Grimoire — read-only, just-in-time retrieval over large Agent-Skill packs (serves the 754-skill anthropic-cybersecurity-skills pack so the model searches for a skill instead of loading a 750-entry catalog).

npm run install:mcps builds both binaries and links them into ~/.local/bin (Synapse also deploys its sidecar service); the agent-surface install step merges each server into every host's MCP config. Both steps are required — one wires the config, the other provides the binary it points at. (npm run install:synapse / install:grimoire install just one.) Details: mcps/synapse/README.md, mcps/grimoire/README.md.

Workflow kernel (optional)

A multi-role pipeline whose state lives under .agent-surface/workflows/<run_id>/: workflow-orchestrator routes BOSS → worker → reviewer → judger → rescue → close; workflow-doctor validates run state; verify-readiness certifies production-ready claims with real evidence.

More

• Per-target install detail: adapters/<target>/README.md.
• Source-kind and capability policy: registry/source-kinds.json, registry/target-capabilities.json.

License

MIT