Integrations and API contracts

Choose the interface that matches the caller. These contracts have different responsibilities.

Caller	Interface	Scope
Claude Code, Codex, Antigravity (agy)	Hooks, `ecc run`, or native MCP with canonical coordination skill	Local agent identity, presence, message delivery, advisory file reservations, and supported wake behavior. Driving agy binds the permission project (defaults to working directory); Codex supports sandbox and approval flags.
Goose (tested on 1.52.0)	`ecc mcp` via session-scoped `--with-extension 'echo:ecc mcp'` or interactive configuration (`goose configure`)	Tools exposed through Goose's stdio extension architecture. The `--with-extension` flag avoids modifying persistent YAML configuration, whereas interactive configuration writes persistent settings. (Coordination skills provide prompt guidance rather than a transport interface).
Aider and CLI-only tools	Subprocess execution via `ecc run`	CLI-driven workspace editing and commit generation under net presence; no native MCP or skill adapter.
Scripts and custom runtimes	`ecc` commands and JSON output (`--json`)	Filesystem-only messaging commands; use subprocess argument arrays, not shell interpolation.
Broker/protocol implementers	CloudEvents 1.0 envelopes	Versioned records, identity, routing, and delivery semantics across the NATS JetStream mesh.

Agent setup planning and native adapters

Pre-release working trees provide the ecc setup command to plan, verify, and apply client integrations. Always plan first before altering any configuration:

# Review proposed registration and review targets
./bin/ecc setup

# Structured machine-readable plan
./bin/ecc setup --format json

Planning discovers agent executables on PATH and produces native registration commands or manual review instructions. It operates strictly read-only: it does not read private configuration, grant permissions, install skills, or edit any files.

The plan reports registration-not-inspected by design: detecting an executable on PATH is discovery, not proof that the client has registered echo, loaded the MCP server, or established network connectivity. In JSON output, command arrays represent argv lists, not shell strings.

Isolated server verification

To verify that the local binary serves MCP correctly before configuring clients:

./bin/ecc setup --check

This probes the server in disposable state and isolated echo configuration, enumerating 16 tools and 4 resources and verifying echo_whoami. It tests the local server binary in isolation, not whether external clients discover or call it.

Explicit apply and remove workflows

Modifying client configuration requires an explicit --agents selection alongside --apply or --remove:

# Configure selected MCP clients
./bin/ecc setup --apply --agents claude,codex,agy

# Remove only unchanged configurations owned by echo setup
./bin/ecc setup --remove --agents claude,codex,agy

Explicit selection mandatory: Running --apply or --remove without explicit --agents is rejected upfront.
Close client sessions first: Close running agent sessions before modifying their settings. Setup serializes its own file writes and detects concurrent changes, but external clients do not share its lock; a concurrent client save can race the file replacement.
Unmanaged entries preserved: Setup never silently adopts existing unmanaged echo entries, even if their fields match. If an unmanaged entry is found, setup refuses to overwrite it and exits with a manual-review notice.
Supported MCP adapters:
- Claude and Antigravity (agy): Setup manages the mcpServers.echo JSON object in native configuration (~/.claude.json for Claude; ~/.gemini/config/mcp_config.json for Antigravity). Files under ~/.gemini/antigravity-cli/mcp/ are discovery caches, not registration files; never edit them directly. Restart clients after registration to reload tools.
- OpenAI Codex: Setup manages MCP registration using the native Codex CLI against a private staged copy of its TOML configuration (~/.codex/config.toml), validating changes and verifying native removal hashes before publishing. Custom CODEX_HOME locations are rejected before changes.
- Goose: The persistent MCP apply adapter remains unfinished; documented persistent setup is interactive goose configure or editing Goose YAML settings. Use session-scoped extensions instead (detailed below).
- Aider: Aider integrates via the CLI subprocess path (ecc run); it has no native MCP adapter. Do not create synthetic MCP registrations for it.

Codex permissions and child execution

Shell permissions and MCP registration are strictly decoupled. Codex rule management is handled explicitly:

# Review Codex executable-prefix rules
./bin/ecc setup --permissions --agents codex

# Apply owned rule file
./bin/ecc setup --permissions --agents codex --apply

Writing ~/.codex/rules/echo-ecc.rules grants executable-prefix permission for ecc. Important: This all-ecc permission grant includes all ecc subcommands, including ecc run and any arbitrary child commands executed through it (not only child agents). This is an explicit operator security choice, never applied implicitly by MCP registration. An optional --repo /path/to/repo flag adds bounded discovery of binaries in the repository's bin/ directory.

Canonical coordination skill

Coordination skills teach agent models how to query the roster, place advisory file reservations before editing, lease tasks, and notify peers:

# Review skill installation targets
./bin/ecc setup --skills --agents codex,goose,claude,agy

# Install the canonical skill to standard locations
./bin/ecc setup --skills --agents codex,goose,claude,agy --apply

The skill payload (SKILL.md) is embedded in the binary and deployed to standard global paths:

Codex and Goose: Share ~/.agents/skills/echo-coordination/SKILL.md. Removing the skill for either client removes the shared file for both.
Claude Code: ~/.claude/skills/echo-coordination/SKILL.md
Antigravity (agy): ~/.gemini/config/skills/echo-coordination/SKILL.md
Aider: No native skill mechanism.

Custom skill-root caveats: Relocated Goose GOOSE_PATH_ROOT and custom Claude CLAUDE_CONFIG_DIR skill roots are currently rejected for manual review. Codex's shared skill path (~/.agents/skills/echo-coordination/SKILL.md) is independent of CODEX_HOME. Symlink ancestors are rejected for manual review and never silently adopted.

Goose session-scoped extension workflow

Goose (tested on 1.52.0) supports session-scoped stdio extensions via --with-extension. This connects Goose to echo without rewriting or modifying your persistent YAML configuration. Because Goose resolves the inner extension executable (ecc) via PATH, you must add the repository's bin/ directory to your PATH first:

# Add built binaries to PATH so Goose can launch ecc mcp
export PATH="$PWD/bin:$PATH"

# Interactive Goose session with echo MCP
./bin/ecc run --tool goose --session worker-goose goose session --with-extension 'echo:ecc mcp'

# Headless Goose task execution
./bin/ecc run --tool goose --session worker-goose goose run --with-extension 'echo:ecc mcp' --text 'Review task backlog'

Repeat --with-extension 'echo:ecc mcp' for each invocation. Note that the native diagnostic goose mcp-probe does not create disposable echo state automatically: it executes against the caller's active environment and creates Goose session metadata. In our qualification test, this diagnostic was run within an explicitly isolated disposable test directory (with private HOME and echo state) where it discovered all 16 tools and 4 resources without a model call.

Integration lifecycle and qualification boundaries

Clear boundaries separate the integration stages:

Installation: Compiling or placing binaries on the host system. There is no released public installer.
Registration: Adding configuration entries, rule files, or skill markdown files.
Discovery: The client starting, reading configuration, launching ecc mcp, and listing tools.
Model invocation: The LLM choosing to invoke tools and following protocol instructions. Tests in disposable environments prove workflow mechanics, not universal model quality or zero errors.
Production connectivity: The local daemon connecting to the JetStream broker and exchanging messages across hosts.

Discovery does not prove model invocation, and isolated tool execution does not prove network mesh connectivity.

Aider and Goose runtime observations

Aider edits and Goose tool workflows have been exercised against Ollama in isolated workspaces. That does not prove every runtime has the same idle-wake behavior. Use the wrapper or MCP according to what the installed runtime supports.

Antigravity (agy) vs. Google Gemini CLI

echo.cc distinguishes Google DeepMind Antigravity CLI (agy) from the standalone Google Gemini developer CLI. Antigravity (agy) is an autonomous agent engine driven via bidirectional stream-json with native project permission grants (--project) and built-in tool loops. echo.cc has no driven adapter for the standalone Gemini CLI.

Model APIs are optional

Optional AI query commands can use configured model providers. They make network requests separately from filesystem-only coordination. A provider key, model access, quota and connectivity are required; using a coding-agent CLI subscription does not automatically grant API credentials.

Protocol documentation

Read the event contract, JSON Schema and CLI reference. CLI results, task state and dashboard snapshots are not interchangeable with wire envelopes. The published agent card is discovery metadata, not an implemented A2A task API.

SDKs and hosted APIs

There is no supported public hosted HTTP API or official language SDK yet. CLI subprocess and MCP integration come first. A hosted OpenAPI contract and generated clients should follow implemented, authenticated tenant routes and real consumer requirements.