Skip to content

Latest commit

 

History

History
192 lines (157 loc) · 9.35 KB

coding-cli-integration.md

File metadata and controls

192 lines (157 loc) · 9.35 KB

Coding CLI integration

Choose code navigation (devmap) and optionally task tooling (devcouncil). These are separate MCP servers. Integration writes configuration and project assets; successful file validation does not prove that a running editor has reloaded or trusted them. Documentation index

Standalone DevMap

Both native installers accept cursor, claude, codex, antigravity, opencode and warp. The one source is the Rust Host enum; devcouncil integrate hands every host name to devmap integrate, which refuses unknown names with the list, and the Go host itself answers the legacy gemini / aider targets with where they went. This is the repository's adapter set, not a claim about every host's current capabilities.

From the target repository:

devmap integrate cursor --dry-run
devmap integrate cursor
devmap integrate cursor --check

There is no --apply on devmap integrate: an invocation without --dry-run or --check applies changes. Read the JSON receipt with --json when scripting.

Host DevMap configuration surfaces
Cursor Global MCP registration, owned project entries, managed guides/rule, .cursor/skills and .cursor/hooks.json
Claude Global MCP registration and the project .mcp.json entry (both withheld while the Dev Map plugin is enabled), managed guides and .claude/skills; separate devmap claude plugin generates a plugin bundle
Codex User ~/.codex/config.toml MCP registration, .agents/skills, project plugin/hook assets; host trust may need renewal
Antigravity .agents/mcp_config.json and .agents/skills. Task agents are not part of this row: a bare devmap integrate antigravity does not write them
OpenCode opencode.json, its project skills layout and a DevMap post-tool plugin
Warp .devcouncil/integrations/warp-mcp.json; no project skill destination is installed by this adapter
flowchart TD
    subgraph CLI["Integration Commands"]
        DM_Int["devmap integrate <host>"]
        DC_Int["devcouncil integrate <host>"]
    end

    subgraph Adapters["Supported Host Adapters"]
        Cursor["Cursor"]
        Claude["Claude Code"]
        Codex["Codex"]
        AGY["Antigravity"]
        OpenCode["OpenCode"]
        Warp["Warp"]
    end

    subgraph ConfigSurfaces["Target Configuration Surfaces"]
        UserConfig["Global User Settings<br/>(Global MCP configs, ~/.codex)"]
        ProjectConfig["Project Config<br/>(.cursor/mcp.json, .mcp.json, .agents/mcp_config.json, opencode.json)"]
        Skills["Skills Libraries<br/>(.cursor/skills, .claude/skills, .agents/skills)"]
        Guides["Managed Guides<br/>(AGENTS.md, CLAUDE.md)"]
    end

    DM_Int --> Cursor & Claude & Codex & AGY & OpenCode & Warp
    DC_Int -->|"Merges task tools & delegates"| DM_Int

    Cursor --> UserConfig & ProjectConfig & Skills & Guides
    Claude --> UserConfig & ProjectConfig & Skills & Guides
    Codex --> UserConfig & Skills & Guides
    AGY --> ProjectConfig & Skills & Guides
    OpenCode --> ProjectConfig & Skills & Guides
    Warp --> ProjectConfig & Guides
Loading

All adapters also use the managed guide-writing path. Inspect the receipt for exact files and changes: global settings may be touched. Existing unrelated server entries are preserved. Do not assume a project-only dry run previews only project-local effects.

Every DevMap MCP call should include absolute repo_path; verify repository.root in the answer. One global registration can serve multiple repositories. Hard-coded database paths and duplicate server registrations can otherwise route a query to the wrong index. devmap paths --json reports binary/configuration diagnostics.

Optional Go-host task tools

Install the full native suite first, then preview/apply the Go host:

devcouncil integrate cursor --dry-run
devcouncil integrate cursor --apply
devcouncil integrate cursor --check

devcouncil integrate <host> runs devmap integrate <host> --servers-stdin and passes it the devcouncil server: this binary by absolute path, mcp, and DEVCOUNCIL_PROJECT_ROOT. DevMap writes that entry into the host's project document in the host's own shape, beside its own devmap entry, and reports every file it examined; the Go receipt is that report. It needs a devmap (--devmap-bin, DEVMAP_BIN, or one on PATH outside the repository) and refuses without one. --check asks DevMap too, so it covers DevMap's assets. DevMap writes its own path as the devmap command unless --devmap-command PATH (absolute) names another, passed on as devmap integrate --binary; DevMap refuses to register a copy under target/devcouncil-testbin.

For Antigravity only, that call is preceded by devmap agents install --agents-stdin. Go embeds four agents and one always-on rule and DevMap writes .agents/agents/<name>/agent.md, .agents/rules/devcouncil.md, and the receipt .devcouncil-agents.json. Other hosts do not spawn that command. If the agent install succeeds and the MCP install then fails, the error comes back with the receipt of the agents that were written. A bare devmap integrate antigravity stays MCP plus DevMap skills. See the ownership decision.

Host Where the devcouncil server is registered
Cursor .cursor/mcp.json; Go also writes .cursor/rules/devcouncil.mdc
Claude .mcp.json
Codex Project .codex/config.toml ([mcp_servers.devcouncil], read for trusted projects); every other byte of the file is kept
Antigravity .agents/mcp_config.json, plus the four agents under .agents/agents/ and .agents/rules/devcouncil.md
OpenCode opencode.json
Warp .devcouncil/integrations/warp-mcp.json

Check exit codes, receipts and the way back

integrate <host> defaults to --check; pass one of --apply, --check or --dry-run (two different ones exit 2). --check exits 0 when everything is current, 1 when a file differs or is missing (the receipt names which), and 3 when DevMap reported an error and the tree was not checked — a document it will not rewrite, such as JSON with comments in ~/.cursor/mcp.json, is reported with its path, never as drift.

An --apply is planned in full before it writes, so a refusing document stops it with nothing written. An owned file the user edited since (the Cursor rule) is saved as <file>.devcouncil-backup-<id> before it is replaced, and the receipt lists the backup. The user-level ~/.codex/config.toml is edited by appending or replacing only the [mcp_servers.devmap] block: every comment and other line stays.

A successful apply records what it wrote in .devcouncil-integrate-<host>.json at the repository root. The way back is:

devcouncil integrate cursor --remove            # check: exit 1 while still registered
devcouncil integrate cursor --remove --apply    # take it back

It removes devmap and devcouncil from exactly the documents that receipt names (user-level ones included), deletes DevCouncil's Cursor rule (saving any edits), leaves every other server, key and comment, and then deletes the receipt. Without a receipt it refuses. Guides (AGENTS.md, CLAUDE.md), skills, agents and hook files are not removed: the guides are shared by every host, .devcouncil-skills.json lists the skills, and .devcouncil-agents.json lists the Antigravity agents and rule. Standalone, the same undo is devmap integrate <host> --remove --only-path DOC [--servers-stdin].

The Go host serves checkout, renew/release lease, next task, diff, gaps, verification and write-policy checks. It does not serve arbitrary file-edit or shell tools. Tasks require initialized state and a consuming agent that honors policy/results. See MCP task loop.

Hooks, skills and enforcement

DevMap navigation hooks maintain code context. DevCouncil's old lifecycle write/stop gates are retired. Installing either server does not intercept all ordinary editor writes, and --write-gate is no longer supported.

Use devcouncil skills list and devcouncil skills scaffold --dry-run to inspect the Go host's engineering skills. Embedded instructions can retain migration limits; they are guidance, not a permissions mechanism. Both skill sets go through one installer: devcouncil skills scaffold hands its library to devmap skills install --library-stdin, which owns .devcouncil-skills.json.

Reload the host after updating a binary or configuration. For Codex hook assets, the generated receipt calls out the host trust step; changing a hook can require renewed trust. File checks and physical host execution are separate verification steps.

Remove retired DevCouncil hooks

dev hook status --project-root /path/to/project
dev hook disable --project-root /path/to/project --client claude --dry-run
dev hook disable --project-root /path/to/project --client claude

Status can be nonzero because registrations remain or inspection failed; read its receipt to distinguish them. Cleanup preserves unrelated tools and records recoverable backups. Old event invocations are silent no-ops, not verification. See CLI cleanup details.

Source owners: rust/devmap-cli/src/integrate.rs, backend/go_orchestrator/devcouncil/integrate/integrate.go.