# Provider CLI Integration Research

Status: research baseline  
Date: 2026-03-07

## Purpose

This document captures the current, externally verified integration surfaces for AI provider CLIs that are relevant to SymForge.

The goal is not to prove a final architecture. The goal is to remove hand-waving and constrain the design to what the clients actually expose today.

This pass is focused on:

- OpenAI Codex
- Anthropic Claude Code
- Gemini CLI
- GitHub Copilot CLI
- Amazon Q Developer CLI

These are the practical targets because they are coding-oriented, local-first enough to matter, and already expose MCP or adjacent agent integration mechanisms.

## Design Question

SymForge should not be "just another MCP server" that the model might occasionally use.

It should become a durable local code-intelligence runtime that provider CLIs can consume through the deepest supported integration surface:

- MCP where that is the only public surface
- native hooks, agents, skills, prompts, or extensions where available

The central architectural question is:

How do we make SymForge get used continuously for lookup, search, repo understanding, and verified retrieval, instead of waiting for the model to discover it by chance?

## Research Summary

### High-confidence conclusion

Different clients offer very different control surfaces.

There is no universal native plugin standard across provider CLIs today.

Therefore:

- a plain MCP-only strategy is too weak
- a plugin-only strategy is impossible across providers
- the most plausible cross-provider architecture is a local SymForge runtime plus provider-specific adapters

### What "constant usage" can realistically mean

SymForge should become the default path for:

- repository outline
- symbol search
- text search
- verified source retrieval
- codebase exploration
- project/session context injection

It does **not** need to replace the client's native edit/write tools.

Trying to make every model edit files through SymForge is the wrong optimization target. The right target is to make models consult SymForge before they search or reason about code.

## Verified Provider Surfaces

### OpenAI Codex

Verified in this pass:

- Codex can connect to MCP servers through the CLI or IDE, with shared configuration across both.
- Codex can be configured through `~/.codex/config.toml` and project-scoped `.codex/config.toml` in trusted projects.
- OpenAI's own MCP docs explicitly recommend adding an `AGENTS.md` instruction to get more reliable MCP usage.
- OpenAI product docs confirm that Codex uses `AGENTS.md` for persistent repository guidance.
- Codex has first-class Skills support in the CLI, IDE extension, and Codex app.
- Codex discovers skills from repository, user, admin, and system locations.
- Codex supports Automations for scheduled background work in the Codex app.
- Codex exposes a Codex SDK for programmatic control of local Codex agents.
- Codex exposes an open app-server protocol for deep custom client integrations and rich clients.
- Codex can also run as its own MCP server for orchestration by other agents.

What we did **not** confirm in public docs during this pass:

- a public third-party Codex plugin marketplace or extension packaging model analogous to Gemini extensions
- a public hook system comparable to Claude hooks or Gemini hooks
- a public documented mechanism to force tool-routing decisions inside Codex in the same way hook-capable clients can

Implication:

- Codex is stronger than "MCP plus AGENTS only".
- Codex already exposes several meaningful native surfaces:
  - shared and project-scoped MCP config
  - layered `AGENTS.md`
  - skills
  - automations
  - SDK
  - app-server
- Codex is still weaker than Claude on workflow interception because we did not confirm an equivalent public hook system.
- Codex likely needs an "instruction + MCP + skills" adapter in the short term, with app-server and SDK remaining strategic deeper options.

Most useful levers:

- global MCP registration
- project-scoped `.codex/config.toml` where appropriate
- project `AGENTS.md` augmentation
- repository and user skill installation
- Codex SDK for internal orchestration use cases
- app-server for future deep custom integration
- high-signal MCP tool/prompt/resource naming

### Claude Code

Verified in this pass:

- Claude Code supports MCP server configuration at local, project, and user scopes.
- Claude Code supports hierarchical settings files at `~/.claude/settings.json`, `.claude/settings.json`, and `.claude/settings.local.json`.
- Claude Code supports plugins and plugin-provided MCP servers.
- Claude Code hooks include `UserPromptSubmit`, `SessionStart`, `PreToolUse`, `PostToolUse`, `Stop`, and related lifecycle events.
- Claude hooks can target MCP tools using `mcp__<server>__<tool>` match patterns.
- Claude Code supports subagents that can inherit or restrict tool access, including MCP tools.
- MCP prompts can appear as slash commands in Claude Code.
- Claude has explicit project initialization and memory surfaces around `CLAUDE.md` and slash commands like `/init` and `/memory`.

Implication:

- Claude Code is the strongest immediate native integration target.
- SymForge can inject context automatically, bias tool selection, expose MCP prompts as slash commands, and provide dedicated analysis subagents.
- Claude is the best first provider for near-"always on" behavior.

Most useful levers:

- user/project MCP registration
- plugin packaging where a shared install unit is valuable
- `SessionStart` context injection
- `UserPromptSubmit` context refresh
- `PreToolUse` steering before naive read/grep workflows
- SymForge-focused subagents
- MCP prompts as slash commands

### Gemini CLI

Verified in this pass:

- Gemini CLI supports MCP.
- Gemini CLI supports a first-class extension packaging system.
- Gemini extensions can bundle MCP servers, custom commands, hooks, sub-agents, and agent skills.
- Gemini CLI supports hooks at both lifecycle and tool boundaries.
- Gemini CLI supports user and workspace settings in `~/.gemini/settings.json` and `.gemini/settings.json`.
- Gemini CLI supports hierarchical `GEMINI.md` context loading.
- Gemini CLI supports extension installation through `gemini extensions install`.
- Gemini's extension format is the cleanest documented packaging surface found in this pass.

Implication:

- Gemini is the best target for a packaged native distribution.
- SymForge should ship an official Gemini extension.
- Gemini can support both "discoverable MCP" and "bundled workflow behavior" from the same install unit.

Most useful levers:

- official Gemini extension
- bundled MCP server config
- lifecycle and tool hooks
- bundled subagents
- bundled skills
- `GEMINI.md` or compatible context-file strategy

### GitHub Copilot CLI

Verified in this pass:

- Copilot CLI supports MCP server configuration.
- Copilot CLI stores MCP config under `~/.copilot` by default.
- Copilot CLI supports repository custom instructions, path-specific instructions, and `AGENTS.md`.
- Copilot CLI supports custom agents.
- Copilot CLI supports hooks.
- Copilot CLI supports skills.
- Copilot CLI exposes plugin documentation and a CLI plugin reference.
- Copilot CLI includes built-in specialized agents and can auto-infer custom agent usage.
- Copilot CLI has Copilot Memory as a separate persistent memory feature.

Implication:

- Copilot CLI is more extensible than a plain MCP-only client.
- SymForge can be integrated through MCP plus repo instructions plus custom agents plus hooks plus skills.
- This makes Copilot a serious second-wave target, even if the initial product focus remains Codex and Claude.

Most useful levers:

- global MCP registration
- repo custom instructions and `AGENTS.md`
- SymForge-specific custom agent profiles
- hook-based context injection and steering
- skill bundles
- plugin packaging once the adapter matures

### Amazon Q Developer CLI

Verified in this pass:

- Amazon Q Developer CLI supports MCP.
- Q CLI supports globally defined MCP configuration and both local process and remote HTTP MCP servers.
- AWS documentation describes custom agents for Q CLI.
- Q custom agents support hooks such as `agentSpawn` and `userPromptSubmit`.
- Q supports a prompt system that includes local prompts, global prompts, and MCP prompts.
- Admin control exists for enabling or disabling MCP functionality in organizations.

Implication:

- Amazon Q is not just an MCP target.
- Q has enough agent and hook surface to support a deeper adapter.
- It is a valid third-wave target after Claude and Gemini, and possibly after Copilot depending on user demand.

Most useful levers:

- MCP registration
- custom agent profiles
- `agentSpawn` and `userPromptSubmit` hooks
- reusable prompt bundles

## Integration Theory Matrix

### Theory A: Plain generic MCP server only

Description:

- Ship SymForge as a standard MCP server
- Tell users to add it to their provider CLI
- Hope the model learns to use it

Advantages:

- simplest implementation
- broadest protocol compatibility
- low maintenance

Disadvantages:

- too passive
- poor discoverability in clients with many tools
- weak control over routing
- no reliable "always use this first" behavior

Assessment:

- necessary
- insufficient as the product strategy

### Theory B: MCP plus repo instruction files only

Description:

- MCP registration
- generate `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and provider-specific instruction files

Advantages:

- works in many environments
- lightweight
- improves adoption over plain MCP

Disadvantages:

- still advisory in many clients
- no lifecycle automation
- no guaranteed context refresh

Assessment:

- useful baseline
- still insufficient alone

### Theory C: Local SymForge runtime plus provider adapters

Description:

- SymForge runs as a local service/runtime
- provider-specific adapters register MCP and native integrations
- adapters inject context, prompts, hooks, agents, and commands where supported

Advantages:

- strongest cross-provider story
- keeps indexing and project state out of per-session stdio startup
- allows one warm local cache and one project registry
- lets each provider use its deepest supported integration surface

Disadvantages:

- higher implementation complexity
- adapter maintenance burden
- requires disciplined compatibility management

Assessment:

- most plausible architecture
- recommended

### Theory D: Wrapper launcher around every provider CLI

Description:

- users invoke `SymForge codex`, `SymForge claude`, `SymForge gemini`, etc.
- SymForge starts the client with injected config and environment

Advantages:

- strong control at process start
- easier bootstrapping of runtime dependencies

Disadvantages:

- brittle
- fights normal user workflows
- weaker UX when users launch the provider CLI directly
- cannot cover cloud and IDE surfaces cleanly

Assessment:

- useful fallback
- should not be the primary architecture

### Theory E: Full client-specific plugin or fork strategy

Description:

- build custom plugin or modified client implementation for each provider

Advantages:

- maximal control where possible

Disadvantages:

- impossible or unsupported for several providers
- high maintenance
- distribution and trust problems

Assessment:

- not practical as the core strategy

## Most Plausible Strategic Position

The most plausible position after this research pass is:

- SymForge should be a local runtime first
- MCP remains mandatory, but only as one transport surface
- provider-native adapters should be first-class product components
- project instruction/context files remain important, but only as one control layer

In short:

**SymForge should become a local code-intelligence platform with MCP transport and provider-native adapters, not just an MCP server binary.**

## Provider Priority Recommendation

### Tier 1

- Claude Code
- Codex

Reason:

- these are the immediate target users
- Claude has the strongest current hook/agent integration surface
- Codex is strategically important even though its public native surface is thinner

### Tier 2

- Gemini CLI
- GitHub Copilot CLI

Reason:

- both have strong extension/customization surfaces
- Gemini has the cleanest extension packaging model
- Copilot has strong repo-native customization and MCP support

### Tier 3

- Amazon Q Developer CLI

Reason:

- valid integration target
- likely lower immediate demand than Claude/Codex/Gemini/Copilot
- still worth designing for now to avoid architecture paint traps

## Hard Constraints Exposed by Research

### Constraint 1: No universal plugin model

We cannot design once and assume every provider will load a "SymForge plugin" the same way.

### Constraint 2: MCP remains the universal minimum

Every serious target in this pass has MCP support or meaningful MCP-adjacent support.

### Constraint 3: Context files still matter

Instruction files remain a reliable steering mechanism across multiple clients:

- `AGENTS.md`
- `CLAUDE.md`
- `GEMINI.md`
- provider-specific instruction files where relevant

### Constraint 4: Hooks are the strongest enforcement layer when available

Claude, Gemini, Copilot, and Q expose hook surfaces that can bias or block naive tool usage.

Codex currently appears to rely more on layered instructions, MCP, skills, and custom client surfaces than on a public hook system.

### Constraint 5: Project tracking must live in SymForge, not in the client

Clients differ too much.

Project identity, workspace tracking, index state, and retrieval policy should live inside SymForge itself.

## Recommended Research Follow-ups

Still worth deeper verification later:

- whether Codex will expose a broader public plugin or hook surface in future official docs
- how far Codex app-server can realistically serve as a SymForge-aware custom client surface without overreaching the current product scope
- exact GitHub Copilot CLI plugin distribution story beyond skills/agents/hooks
- Amazon Q file layout and packaging conventions for team-shared agent bundles
- security/trust prompts and approval models for provider-installed hooks

## Sources

- OpenAI Docs MCP: <https://platform.openai.com/docs/docs-mcp>
- OpenAI Codex AGENTS.md guide: <https://developers.openai.com/codex/guides/agents-md>
- OpenAI Codex MCP guide: <https://developers.openai.com/codex/mcp>
- OpenAI Codex Skills guide: <https://developers.openai.com/codex/skills>
- OpenAI Codex Automations: <https://developers.openai.com/codex/app/automations>
- OpenAI Codex SDK: <https://developers.openai.com/codex/sdk>
- OpenAI Codex App Server: <https://developers.openai.com/codex/app-server>
- OpenAI Codex launch post: <https://openai.com/index/introducing-codex/>
- OpenAI Codex product page: <https://openai.com/codex/>
- OpenAI Codex app launch: <https://openai.com/index/introducing-the-codex-app/>
- OpenAI usage guidance mentioning `AGENTS.md`: <https://openai.com/business/guides-and-resources/how-openai-uses-codex/>
- Anthropic Claude Code MCP docs: <https://docs.anthropic.com/en/docs/claude-code/mcp>
- Anthropic Claude Code hooks: <https://docs.anthropic.com/en/docs/claude-code/hooks>
- Anthropic Claude Code subagents: <https://docs.anthropic.com/en/docs/claude-code/subagents>
- Anthropic Claude Code slash commands: <https://docs.anthropic.com/en/docs/claude-code/slash-commands>
- Anthropic Claude Code settings: <https://docs.anthropic.com/en/docs/claude-code/settings>
- Gemini CLI docs home: <https://geminicli.com/docs/>
- Gemini CLI extensions: <https://geminicli.com/docs/extensions/>
- Gemini CLI extensions reference: <https://geminicli.com/docs/extensions/reference/>
- Gemini CLI hooks: <https://geminicli.com/docs/hooks/>
- Gemini CLI `GEMINI.md`: <https://geminicli.com/docs/cli/gemini-md>
- Gemini CLI settings: <https://geminicli.com/docs/cli/settings/>
- GitHub Copilot CLI overview: <https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli>
- GitHub Copilot CLI usage: <https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli>
- GitHub Copilot CLI MCP: <https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers>
- GitHub Copilot CLI hooks: <https://docs.github.com/en/copilot/how-tos/copilot-cli/use-hooks>
- GitHub Copilot CLI skills: <https://docs.github.com/copilot/how-tos/copilot-cli/customize-copilot/create-skills>
- GitHub Copilot CLI custom agents: <https://docs.github.com/en/enterprise-cloud%40latest/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli>
- Amazon Q MCP docs: <https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp.html>
- Amazon Q custom agents: <https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-custom-agents.html>
- Amazon Q custom agent configuration: <https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-custom-agents-configuration.html>
