The ai-cli-mcp server lets you run, manage, and monitor AI CLI tools (Claude, Codex, Gemini, Forge, OpenCode) as background processes, enabling parallel AI agent orchestration and automation.
Running AI Agents
Background execution (run): Launch agents asynchronously, getting a PID immediately for non-blocking workflows
Parallel agent coordination: Run multiple agents simultaneously on different tasks (e.g., refactor backend, write tests, update docs — all at once)
Multi-model support: Claude (sonnet, opus, haiku), Codex (gpt-5.4, etc.), Gemini (gemini-2.5-pro, etc.), Forge, and OpenCode (including oc-<provider/model> wrappers)
Session resumption: Pass a session_id to resume previous sessions for context reuse
Reasoning effort control: Tune reasoning intensity for Claude (low–max) and Codex (low–ultra)
Process Lifecycle Management
list_processes – view all running/completed agents with PID, type, and status
get_result – retrieve output and status for any agent by PID
wait – block until one or more agents finish (configurable timeout)
peek – observe live events (messages, tool calls) from running agents
kill_process – terminate a running agent by PID
cleanup_processes – remove completed/failed processes from the tracking list
Diagnostics
doctor – verify AI CLI binaries are available and resolvable
models – list all supported model names, aliases, and backends
Agent Task Capabilities (via underlying CLI tools)
File operations: create, read, edit, move, copy, delete, analyze/OCR images
Code generation, refactoring, analysis, and bug fixing
Git workflows: stage, commit, push, tag
Terminal command execution and URL opening
Web search and content summarization
Multi-step workflows and GitHub integration
Custom CLI binary paths can be overridden via environment variables for specialized setups.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ai-cli-mcp Run sonnet to refactor the backend code"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
📦 Package Migration Notice: This package was formerly
@mkxultra/claude-code-mcpand has been renamed toai-cli-mcpto reflect its expanded support for multiple AI CLI tools.
An MCP (Model Context Protocol) server that allows running AI CLI tools (Claude, Codex, Gemini, Forge, and OpenCode) in background processes with automatic permission handling.
Did you notice that Cursor sometimes struggles with complex, multi-step edits or operations? This server, with its powerful unified run tool, enables multiple AI agents to handle your coding tasks more effectively.
Related MCP server: all-agents-mcp
This MCP server provides tools that can be used by LLMs to interact with AI CLI tools. When integrated with MCP clients, it allows LLMs to:
Run Claude CLI with all permissions bypassed (using --dangerously-skip-permissions)
Execute Codex CLI with approvals and sandbox bypassed (using --dangerously-bypass-approvals-and-sandbox)
Execute Gemini CLI with automatic approval mode (using -y)
Execute Forge CLI in non-interactive mode (using forge -C <workFolder> -p <prompt>)
Execute OpenCode in non-interactive JSON mode (using opencode run --format json --dir <workFolder> <prompt>)
Support multiple AI models: Claude (sonnet, sonnet[1m], opus, opusplan, fable, haiku), Codex (gpt-5.4, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5, gpt-5.4-mini, gpt-5.3-codex, gpt-5.3-codex-spark, gpt-5.2), Gemini (gemini-2.5-pro, gemini-2.5-flash, gemini-3.1-pro-preview, gemini-3-pro-preview, gemini-3-flash-preview), Forge (forge), and OpenCode (opencode plus explicit oc-<provider/model> wrappers such as oc-openai/gpt-5.4)
Manage background processes with PID tracking
Parse and return structured outputs from both tools
You can instruct your main agent to run multiple tasks in parallel like this:
Launch agents for the following 3 tasks using acm mcp run:
Refactor
src/backendcode usingsonnetCreate unit tests for
src/frontendusinggpt-5.3-codexUpdate docs in
docs/usinggemini-2.5-proWhile they run, please update the TODO list. Once done, use the
waittool to wait for all completions and report the results together.
You can reuse heavy context (like large codebases) using session IDs to save costs while running multiple tasks.
First, use
acm mcp runwithopusto read all files insrc/and understand the project structure.Use the
waittool to wait for completion and retrieve thesession_idfrom the result.Using that
session_id, run the following two tasks in parallel withacm mcp run:
Create refactoring proposals for
src/utilsusingsonnetAdd architecture documentation to
README.mdusinggpt-5.3-codexFinally,
waitagain to combine both results.
True Async Multitasking: Agent execution happens in the background, returning control immediately. The calling AI can proceed with the next task or invoke another agent without waiting for completion.
CLI in CLI (Agent in Agent): Directly invoke powerful CLI tools like Claude Code or Codex from any MCP-supported IDE or CLI. This enables broader, more complex system operations and automation beyond host environment limitations.
Freedom from Model/Provider Constraints: Freely select and combine the "strongest" or "most cost-effective" models from Claude, Codex (GPT), Gemini, and Forge without being tied to a specific ecosystem.
The only prerequisite is that the AI CLI tools you want to use are locally installed and correctly configured.
Claude Code: claude doctor passes, and execution with --dangerously-skip-permissions is approved (you must run it manually once to login and accept terms).
Codex CLI (Optional): Installed and initial setup (login etc.) completed.
Gemini CLI (Optional): Installed and initial setup (login etc.) completed.
Forge CLI (Optional): Installed and initial setup completed.
OpenCode (Optional): Installed and configured. This integration uses opencode run --format json, and explicit provider/model selection follows the oc-<provider/model> wrapper syntax exposed by ai-cli models.
There are now two primary ways to use this package:
ai-cli-mcp: MCP server entrypoint
ai-cli: human-facing CLI for background AI runs
npxThe recommended way to use the MCP server is via npx.
"ai-cli-mcp": {
"command": "npx",
"args": [
"-y",
"ai-cli-mcp@latest"
]
},claude mcp add ai-cli '{"name":"ai-cli","command":"npx","args":["-y","ai-cli-mcp@latest"]}'If you want to use the production CLI directly from your shell, install the package globally:
npm install -g ai-cli-mcpThis exposes both commands:
ai-cli
ai-cli-mcp
Examples:
ai-cli doctor
ai-cli models
ai-cli run --cwd "$PWD" --model sonnet --prompt "summarize this repository"
ai-cli run --cwd "$PWD" --model opencode --prompt "summarize this repository with OpenCode defaults"
ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --session-id ses_123 --prompt "continue this session with an explicit OpenCode model"
ai-cli ps
ai-cli result 12345
ai-cli result 12345 --verbose
ai-cli peek 12345 --time 10
ai-cli wait 12345 --timeout 300
ai-cli wait 12345 --verbose
ai-cli kill 12345
ai-cli cleanup
ai-cli-mcpnpxBecause the published package name is still ai-cli-mcp, the shortest npx form for the CLI is:
npx -y --package ai-cli-mcp@latest ai-cli run --cwd "$PWD" --model sonnet --prompt "hello"
npx -y --package ai-cli-mcp@latest ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --prompt "hello from OpenCode"Before the MCP server can use Claude, you must first run the Claude CLI manually once with the --dangerously-skip-permissions flag, login and accept the terms.
npm install -g @anthropic-ai/claude-code
claude --dangerously-skip-permissionsFollow the prompts to accept. Once this is done, the MCP server will be able to use the flag non-interactively.
For Codex, ensure you're logged in and have accepted any necessary terms:
codex loginFor Gemini, ensure you're logged in and have configured your credentials:
gemini auth loginmacOS might ask for folder permissions the first time any of these tools run. If the first run fails, subsequent runs should work.
ai-cli currently supports:
run
ps
result
peek
wait
kill
cleanup
doctor
models
mcp
Example flow:
ai-cli doctor
ai-cli models
ai-cli run --cwd "$PWD" --model gpt-5.4 --prompt "use the default Codex model"
ai-cli run --cwd "$PWD" --model codex-ultra --prompt "fix failing tests"
ai-cli run --cwd "$PWD" --model opencode --session-id ses_existing --prompt "continue this OpenCode session"
ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --prompt "run with an explicit OpenCode backend model"
ai-cli ps
ai-cli peek 12345 --time 10
ai-cli peek 12345 12346 --time 10
ai-cli wait 12345
ai-cli wait 12345 --verbose
ai-cli result 12345
ai-cli result 12345 --verbose
ai-cli cleanuprun accepts --cwd as the primary working-directory flag and also accepts the older aliases --workFolder / --work-folder for compatibility.
OpenCode model selection accepts either:
opencode for the CLI's configured default model
oc-<provider/model> for an explicit OpenCode provider/model, for example oc-openai/gpt-5.4
ai-cli models exposes OpenCode machine-readably via opencode: ["opencode"] plus dynamicModelBackends.opencode, which points users to opencode models for backend-native discovery.
Codex model selection uses gpt-5.4 as the default advertised model.
doctor checks only binary availability and path resolution. Its JSON output includes a checks block that marks login state and terms acceptance as unchecked.
Background CLI runs are stored under:
~/.local/state/ai-cli/cwds/<normalized-cwd>/<pid>/Each PID directory contains:
meta.json
stdout.log
stderr.log
exit-status.json for detached runs
Use ai-cli cleanup to remove completed and failed runs. Running processes are preserved.
Detached ai-cli runs persist natural exit status for all supported backends through exit-status.json. Non-zero exits are surfaced as failed with the recorded exitCode; zero exits are surfaced as completed with exitCode: 0. ai-cli kill records SIGTERM termination as a failed exit, and a tracked process that disappears without exit metadata is treated as failed rather than assumed successful.
After setting up the server, add the configuration to your MCP client's settings file (e.g., mcp.json for Cursor, mcp_config.json for Windsurf).
If the file doesn't exist, create it and add the ai-cli-mcp configuration.
This server exposes the following tools:
runExecutes a prompt using Claude CLI, Codex CLI, Gemini CLI, Forge CLI, or OpenCode. The appropriate CLI is automatically selected based on the model name.
Arguments:
prompt (string, optional): The prompt to send to the AI agent. Either prompt or prompt_file is required.
prompt_file (string, optional): Path to a file containing the prompt. Either prompt or prompt_file is required. Can be absolute path or relative to workFolder.
workFolder (string, required): The working directory for the CLI execution. Must be an absolute path.
Models:
Ultra Aliases: claude-ultra (opus, defaults to max effort and does not select Fable), codex-ultra (gpt-5.6-sol, defaults to ultra reasoning), gemini-ultra
Claude: sonnet, sonnet[1m], opus, opusplan, fable, haiku
fable explicitly selects Claude Code's latest Fable model. Fable may require separately billed usage credits and is never selected implicitly by claude-ultra.
Codex: gpt-5.4, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5, gpt-5.4-mini, gpt-5.3-codex, gpt-5.3-codex-spark, gpt-5.2
Gemini: gemini-2.5-pro, gemini-2.5-flash, gemini-3.1-pro-preview, gemini-3-pro-preview, gemini-3-flash-preview
Forge: forge
OpenCode: opencode for the configured default backend model, plus explicit wrappers like oc-openai/gpt-5.4
reasoning_effort (string, optional): Reasoning control for Claude and Codex. Claude uses --effort (allowed: "low", "medium", "high", "xhigh", "max"). Codex uses model_reasoning_effort (base levels: "low", "medium", "high", "xhigh"; GPT-5.6 Sol/Terra also support "max" and "ultra", while Luna supports "max"). Gemini, Forge, and OpenCode do not support reasoning_effort.
session_id (string, optional): Optional session ID to resume a previous session. Supported for Claude, Codex, Gemini, Forge, and OpenCode. OpenCode resumes in place via --session and may also be combined with an explicit oc-<provider/model> selection.
waitWaits for multiple AI agent processes to complete and returns their combined results. Blocks until all specified PIDs finish or a timeout occurs.
By default, each returned result item uses the compact shape shared with get_result(verbose: false): operational fields such as pid, agent, status, exitCode, model, parsed output such as agentOutput, and top-level session_id when available. Set verbose: true to include full metadata like startTime, workFolder, prompt, and detailed parsed output such as agentOutput.tools.
Arguments:
pids (array of numbers, required): List of process IDs to wait for (returned by the run tool).
timeout (number, optional): Maximum wait time in seconds. Defaults to 180 (3 minutes).
verbose (boolean, optional): If true, each result item uses the full result shape. Defaults to false.
peekStarts a one-shot short observation window for running child agents and returns structured events observed during that specific call. By default this includes only natural-language message events; pass include_tool_calls or --include-tool-calls to also include normalized tool-call events. It is not a history API, not gapless streaming, and not shell stdout/stderr tailing. Separate peek calls may miss events emitted between calls; --follow is intentionally not part of v1.
CLI v1:
ai-cli peek 123 --time 10
ai-cli peek 123 456 --time 10
ai-cli peek 123 --time 10 --include-tool-callsArguments:
pids (array of numbers, required): 1..32 process IDs returned by run. Duplicate PIDs are deduplicated server-side, preserving first occurrence order. Unknown or unmanaged PIDs are returned per process as not_found, not as a whole-call failure.
peek_time_sec (number, optional): Positive integer observation length in seconds. Defaults to 10 and is capped at 60. 0, negative values, and fractional values are invalid.
include_tool_calls (boolean, optional): When true, each process events array includes normalized tool_call events in addition to message events. Defaults to false.
Observation and filtering:
peek_started_at and events[].ts are ai-cli-mcp server-side UTC RFC3339 timestamps. peek_started_at is when the observation window starts after validation and listener registration; events[].ts is when ai-cli-mcp observed and accepted the event.
The window ends when peek_time_sec elapses or all target processes reach a terminal state, whichever comes first.
Events emitted before the window starts are not returned. Concurrent peek calls for the same PID are allowed; each has an independent window and may return overlapping events.
Message events are recognized from Codex agent_message text, Claude assistant text content, OpenCode type: "text" events where part.type is "text", Gemini stream-json message events where role is "assistant", and best-effort Forge plain-text lines beginning with Summary: or Completed successfully:.
When tool calls are included, tool_call events are normalized for Codex command/MCP calls, Claude tool use/results, Gemini tool use/results, OpenCode completed tool use events, and low-precision Forge Execute/Finished markers. Tool summaries are bounded one-line strings derived from tool names and input metadata only. Forge command output itself is not tailed or exposed. Raw stdout/stderr, raw JSONL, tool result output, command output, result.response, stats, token usage, and verbose metadata are excluded.
Unknown event shapes are denied by default. Managed agents without supported extraction return their real process status with events: [], truncated: false, and error: null.
Each PID keeps the first 50 events observed in the window. If later events are dropped, truncated is true.
status is one of running, completed, failed, or not_found, and reflects state when the observation window closes.
agent is claude, codex, gemini, forge, opencode, a future tracked string value, or null when the process is not found or the agent cannot be determined.
Example response:
{
"peek_started_at": "2026-04-11T12:34:56.789Z",
"observed_duration_sec": 10.01,
"processes": [
{
"pid": 123,
"agent": "codex",
"status": "running",
"events": [
{ "kind": "message", "ts": "2026-04-11T12:34:59.120Z", "text": "I'm checking the implementation." },
{ "kind": "tool_call", "ts": "2026-04-11T12:35:00.000Z", "phase": "started", "id": "item_0", "tool": "command_execution", "summary": "/bin/sh -c 'echo hi'" }
],
"truncated": false,
"error": null
},
{
"pid": 999,
"agent": null,
"status": "not_found",
"events": [],
"truncated": false,
"error": "process not found"
}
]
}list_processesLists all running and completed AI agent processes with their status, PID, and basic info.
doctorChecks supported AI CLI binary availability and path resolution from MCP clients. Like ai-cli doctor, it returns a checks block and does not verify login state or terms acceptance.
modelsLists supported model names, aliases, and dynamic backend discovery hints from MCP clients. This returns the same structured payload as ai-cli models.
get_resultGets the current output and status of an AI agent process by PID.
By default, this returns the compact result shape: operational fields such as pid, agent, status, exitCode, model, parsed output such as agentOutput, and top-level session_id when available. It omits metadata fields like startTime, workFolder, and prompt. Set verbose: true to return the full result shape including those metadata fields and detailed parsed output such as agentOutput.tools. If parsed output is unavailable or incomplete, the raw stdout/stderr fallback is preserved.
Arguments:
pid (number, required): The process ID returned by the run tool.
verbose (boolean, optional): If true, returns the full result shape. Defaults to false.
kill_processTerminates a running AI agent process by PID.
Arguments:
pid (number, required): The process ID to terminate.
"Command not found" (claude-code-mcp): If installed globally, ensure the npm global bin directory is in your system's PATH. If using npx, ensure npx itself is working.
"Command not found" (ai-cli): If installed globally, ensure your npm global bin directory is in PATH. If using npx, use npx -y --package ai-cli-mcp@latest ai-cli ....
"Command not found" (claude or ~/.claude/local/claude): Ensure the Claude CLI is installed correctly. Run claude/doctor or check its documentation.
Permissions Issues: Make sure you've run the "Important First-Time Setup" step.
JSON Errors from Server: If MCP_CLAUDE_DEBUG is true, error messages or logs might interfere with MCP's JSON parsing. Set to false for normal operation.
ESM/Import Errors: Ensure you are using Node.js v20 or later.
For development setup, testing, and contribution guidelines, see the Development Guide.
# Deterministic unit, parser, contract, and mocked e2e tests
npm test
# Published npm package contents smoke test
npm run test:package
# Deterministic PR/release gate used by GitHub Actions.
# This does not enable real external CLI runs by itself.
npm run test:release
# Release-time live E2E against real installed AI CLIs
ACM_LIVE_E2E=1 ACM_LIVE_E2E_AGENTS=claude,codex npm run test:live
# Release-time live E2E for both ai-cli and MCP server surfaces
ACM_LIVE_E2E=1 ACM_LIVE_E2E_SURFACE=all ACM_LIVE_E2E_AGENTS=claude,codex npm run test:liveLive E2E is opt-in because it depends on installed and authenticated external CLIs, network access, provider availability, and cost budget. ACM_LIVE_E2E_SURFACE defaults to cli; use mcp or all to include the MCP server surface.
Normally not required, but useful for customizing CLI paths or debugging.
CLAUDE_CLI_NAME: Override the Claude CLI binary name or provide an absolute path (default: claude)
CODEX_CLI_NAME: Override the Codex CLI binary name or provide an absolute path (default: codex)
GEMINI_CLI_NAME: Override the Gemini CLI binary name or provide an absolute path (default: gemini)
FORGE_CLI_NAME: Override the Forge CLI binary name or provide an absolute path (default: forge)
OPENCODE_CLI_NAME: Override the OpenCode CLI binary name or provide an absolute path (default: opencode)
MCP_CLAUDE_DEBUG: Enable debug logging (set to true for verbose output)
CLI Name Specification:
Command name only: CLAUDE_CLI_NAME=claude-custom
Absolute path: CLAUDE_CLI_NAME=/path/to/custom/claude
Relative paths are not supported.
"ai-cli-mcp": {
"command": "npx",
"args": [
"-y",
"ai-cli-mcp@latest"
],
"env": {
"CLAUDE_CLI_NAME": "claude-custom",
"CODEX_CLI_NAME": "codex-custom",
"OPENCODE_CLI_NAME": "opencode-custom"
}
},MIT
Remove all completed and failed processes from the process list to free up memory.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It clearly states the action (removing completed/failed processes) and the benefit (free memory). It does not mention edge cases like empty list or return value, but for a simple zero-parameter tool, it is sufficiently transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence front-loads the purpose and outcome. No wasted words, highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema, no annotations), the description is adequate. It covers what it does and why. Could mention that it does not affect running processes, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so baseline is 4. The description adds no parameter info because none exist. Schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool removes all completed and failed processes to free memory. It uses specific verbs and resource, and distinguishes from siblings like kill_process (which targets running processes) and list_processes (which lists them).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for memory cleanup but does not explicitly tell when to use this tool versus alternatives (e.g., kill_process for running processes). No guidance on prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check supported AI CLI binary availability and path resolution. Does not verify login state or terms acceptance.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It transparently states its scope (binary availability and path resolution) and limitations (does not verify login state or terms acceptance). This is sufficient for a simple diagnostic tool with no side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. First sentence states the main action, second sentence clarifies limits. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params, no output schema), the description is fairly complete. It covers purpose and limitations. However, it does not describe the return value or format, which could be useful for the agent to interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100% (empty). The description adds no parameter information, but none is needed. Baseline 4 is appropriate as the description does not need to compensate for missing param details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: checking AI CLI binary availability and path resolution. It also explicitly states what it does not do (verify login state or terms acceptance), which distinguishes it from sibling tools like 'run' or 'models'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage before running commands to verify CLI availability. It provides context by clarifying what it does not check, helping the agent know when to use this tool versus others. However, it does not explicitly mention when not to use it or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current output and status of an AI agent process by PID. Defaults to a compact result shape; set verbose to true for full metadata and detailed parsed output.
| Name | Required | Description | Default |
|---|---|---|---|
| pid | Yes | The process ID returned by run tool. | |
| verbose | No | Optional: If true, returns the full result shape including metadata fields and detailed parsed output such as tool usage history. Defaults to false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description accurately states it retrieves data, implying a read-only operation. However, it lacks explicit details on side effects, resource usage, or error conditions, which would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using two sentences to convey all necessary information without any redundant or irrelevant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core functionality and result shapes adequately. While it could hint at the output structure, the tool's simplicity and the presence of sibling tools make this sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the description adds value by explaining the behavior of the verbose parameter, going beyond the schema's static definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves output and status of an AI agent process by PID, specifying the action and resource. It effectively distinguishes itself from sibling tools like kill_process or run.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on the verbose parameter (compact vs. full output) but does not explicitly differentiate when to use this tool versus alternatives like peek or wait.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Terminate a running AI agent process by PID.
| Name | Required | Description | Default |
|---|---|---|---|
| pid | Yes | The process ID to terminate. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose side effects, required permissions, or what happens to process resources upon termination. For a destructive action, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. However, the brevity sacrifices valuable context for the tool's use.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward kill command with one parameter, the description is adequate but does not cover behavioral aspects or differentiate from siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with 'pid' described. The description adds no additional meaning beyond what the schema provides, which is acceptable given the simple parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Terminate a running AI agent process by PID' with a specific verb and resource. However, it does not differentiate from sibling tool 'cleanup_processes', which may also terminate processes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'cleanup_processes'. The description lacks context for appropriate usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all running and completed AI agent processes. Returns a simple list with PID, agent type, and status for each process.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that the tool returns a simple list with PID, agent type, and status for each process, but does not disclose behavioral traits such as performance characteristics, rate limits, or whether it blocks. Since no annotations are provided, the description carries the full burden, but it only minimally covers behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the core action, and no unnecessary words. Straightforward and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with no parameters and no output schema, the description adequately covers the return format and scope. However, it could mention that no detailed process information is provided (e.g., no resource usage) or that it is read-only, but overall it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so schema coverage is 100% by definition. The description naturally adds no parameter information, but the baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all running and completed AI agent processes, specifying the resource (processes) and action (list). It distinguishes from sibling tools like cleanup_processes, kill_process, etc., by focusing on listing rather than modifying or inspecting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., when to use 'peek' or 'get_result'). There is no mention of prerequisites, exclusions, or context for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List supported model names, model aliases, and dynamic backend discovery hints.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as read-only nature, idempotency, or required permissions. As a list operation, it is likely safe, but this is not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant information. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does not specify return format or structure. For a simple list, it may be sufficient, but additional details on ordering, pagination, or static vs dynamic content would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is trivially 100%. The description adds meaning by specifying what the list contains (names, aliases, discovery hints), which is helpful beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists supported model names, aliases, and dynamic backend discovery hints. It is specific and distinct from sibling tools like list_processes or get_result.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or when not to use. The purpose is implied but no alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One-shot short observation window for running child agents. Returns only natural-language message events, and optionally normalized tool_call events, observed during this call; not a history API, not gapless streaming, and not stdout/stderr tailing. In v1, message extraction is supported for Codex, Claude, OpenCode, Gemini, and best-effort Forge Summary/Completed successfully lines. Forge tool calls are low-precision Execute/Finished markers and never include command output. Tool calls exclude raw tool output.
| Name | Required | Description | Default |
|---|---|---|---|
| pids | Yes | Process IDs returned by run. Duplicates are deduplicated server-side, preserving first occurrence order. Unknown PIDs are returned per process as not_found. | |
| peek_time_sec | No | Optional positive integer observation window in seconds. Defaults to 10; maximum is 60. | |
| include_tool_calls | No | Optional: include normalized tool_call events without raw tool output. Defaults to false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that the tool is a one-shot observation, returns only message events, tool calls are normalized without raw output, Forge support is limited, and message extraction supports specific agents. It does not mention side effects, rate limits, or authentication, but the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of three sentences that front-load the essential purpose and limitations. Every sentence adds value without repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters and no output schema or annotations, the description covers the purpose, return content (message events, optional tool calls), limitations (Forge precision), and supported agents. It is sufficient for an agent to decide when to use this tool, though it omits return structure details that an output schema would provide.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already defines parameters (pids, peek_time_sec, include_tool_calls) with clear descriptions. The tool description adds overall context but does not enhance parameter semantics beyond what the schema provides. A score of 3 is appropriate as the schema carries the primary burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a 'one-shot short observation window for running child agents' that returns 'natural-language message events' and optionally 'normalized tool_call events', distinguishing it from a history API, gapless streaming, and stdout/stderr tailing. The verb 'peek' accurately reflects a quick, limited observation, and the tool's scope is specific and well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when not to use this tool (not for history, streaming, or stdout/stderr) and notes limitations like Forge tool calls being low-precision and excluding raw output. However, it does not directly reference sibling tools or provide explicit guidance on which alternative to use for specific needs, such as 'get_result' for full output.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
AI Agent Runner: Starts a Claude, Codex, Gemini, Forge, or OpenCode CLI process in the background and returns a PID immediately. Use list_processes and get_result to monitor progress.
• File ops: Create, read, (fuzzy) edit, move, copy, delete, list files, analyze/ocr images, file content analysis • Code: Generate / analyse / refactor / fix • Git: Stage ▸ commit ▸ push ▸ tag (any workflow) • Terminal: Run any CLI cmd or open URLs • Web search + summarise content on-the-fly • Multi-step workflows & GitHub integration
IMPORTANT: This tool now returns immediately with a PID. Use other tools to check status and get results.
Supported models: "claude-ultra", "codex-ultra", "gemini-ultra", "sonnet", "sonnet[1m]", "opus", "opusplan", "fable", "haiku", "gpt-5.4", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5", "gpt-5.4-mini", "gpt-5.3-codex", "gpt-5.3-codex-spark", "gpt-5.2", "gemini-2.5-pro", "gemini-2.5-flash", "gemini-3.1-pro-preview", "gemini-3-pro-preview", "gemini-3-flash-preview", "forge", "opencode", "oc-<provider/model>"
Prompt input: You must provide EITHER prompt (string) OR prompt_file (file path), but not both.
Prompt tips
Be concise, explicit & step-by-step for complex tasks.
Check process status with list_processes
Get results with get_result using the returned PID
Kill long-running processes with kill_process if needed
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | The model to use. Aliases: "claude-ultra" (Opus with auto max effort; does not select Fable), "codex-ultra" (auto ultra reasoning), "gemini-ultra". Standard: "sonnet", "sonnet[1m]", "opus", "opusplan", "fable", "haiku", "gpt-5.4", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5", "gpt-5.4-mini", "gpt-5.3-codex", "gpt-5.3-codex-spark", "gpt-5.2", "gemini-2.5-pro", "gemini-2.5-flash", "gemini-3.1-pro-preview", "gemini-3-pro-preview", "gemini-3-flash-preview", "forge", "opencode". Fable is an explicit selection and may require usage credits. OpenCode also accepts explicit dynamic models using "oc-<provider/model>". "forge" is a provider key, not a Forge model family selector. | |
| prompt | No | The detailed natural language prompt for the agent to execute. Either this or prompt_file is required. | |
| session_id | No | Optional session ID to resume a previous session. Supported for Claude, Codex, Gemini, Forge, and OpenCode. OpenCode resumes in-place via --session and may also be combined with explicit oc-<provider/model> selection. | |
| workFolder | Yes | The working directory for the agent execution. Must be an absolute path. | |
| prompt_file | No | Path to a file containing the prompt. Either this or prompt is required. Must be an absolute path or relative to workFolder. | |
| reasoning_effort | No | Reasoning control for Claude and Codex. Claude uses --effort with "low", "medium", "high", "xhigh", "max". Codex uses model_reasoning_effort with "low", "medium", "high", "xhigh"; GPT-5.6 Sol and Terra also support "max" and "ultra", while Luna supports "max". Gemini, Forge, and OpenCode do not support reasoning_effort in this integration. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses key behaviors: returns immediately with PID, runs in background, performs file/code/git/terminal operations, supports various models, and has mutual exclusivity of prompt and prompt_file. It also explains model aliases and specifics about Fable credits and 'forge' as a provider key.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with headings and bullet points, front-loading the core purpose. It is slightly verbose but every sentence adds value. Some redundancy in monitoring instructions could be trimmed, but overall it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with many models and capabilities, the description is comprehensive. It covers the process lifecycle (start, check, get results, kill), parameter constraints, model list, and additional integrations. No output schema, but it mentions PID. Minor gaps (e.g., what happens on error) are acceptable given the scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing a baseline of 3. The description adds significant meaning: explains mutual exclusivity of prompt/prompt_file, gives model selection details and reasoning_effort variants, and includes prompt tips. This goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'AI Agent Runner: Starts a Claude, Codex, Gemini, Forge, or OpenCode CLI process in the background and returns a PID immediately.' It uses a specific verb (starts/runs) and resource (AI agent process), and distinguishes from siblings by noting immediate return with PID and directing to list_processes, get_result, kill_process for monitoring.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: when to use (starting a process), when not (monitoring uses other tools), and alternatives (list_processes, get_result, kill_process). It also instructs on parameter constraints ('must provide EITHER prompt OR prompt_file'), and includes prompt tips for effective usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wait for multiple AI agent processes to complete and return their results. Defaults to compact result items; set verbose to true for full metadata and detailed parsed output.
| Name | Required | Description | Default |
|---|---|---|---|
| pids | Yes | List of process IDs to wait for (returned by the run tool). | |
| timeout | No | Optional: Maximum time to wait in seconds. Defaults to 180 (3 minutes). | |
| verbose | No | Optional: If true, each result item uses the full result shape including metadata fields and detailed parsed output. Defaults to false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries full responsibility. It discloses compact vs verbose defaults but omits behavior on timeout (error or partial results), failure handling, and side effects. Significant gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the core function and then explain key option. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks details on return value shape (compact vs verbose), error handling for invalid pids or timeouts, and blocking behavior. With no output schema, completeness is insufficient for a 3-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value for the 'verbose' parameter (explains effect) but nothing new for 'pids' or 'timeout' beyond schema definitions. Marginal improvement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'wait' and the resource 'multiple AI agent processes'. It distinguishes from sibling tools like run, kill_process, and get_result by focusing on waiting for completion and returning results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied for after launching processes with run, but no explicit when-to-use or when-not-to-use guidance is given. Alternatives like get_result for individual results are not mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v2.22.0run2 fields changedInput schema / properties / model / descriptionPrevious value: -"The model to use. Aliases: \"claude-ultra\" (auto max effort), \"codex-ultra\" (auto xhigh reasoning), \"gemini-ultra\". Standard: \"sonnet\", \"sonnet[1m]\", \"opus\", \"opusplan\", \"haiku\", \"gpt-5.4\", \"gpt-5.5\", \"gpt-5.4-mini\", \"gpt-5.3-codex\", \"gpt-5.3-codex-spark\", \"gpt-5.2\", \"gemini-2.5-pro\", \"gemini-2.5-flash\", \"gemini-3.1-pro-preview\", \"gemini-3-pro-preview\", \"gemini-3-flash-preview\", \"forge\", \"opencode\". OpenCode also accepts explicit dynamic models using \"oc-<provider/model>\". \"forge\" is a provider key, not a Forge model family selector."New value: +"The model to use. Aliases: \"claude-ultra\" (Opus with auto max effort; does not select Fable), \"codex-ultra\" (auto ultra reasoning), \"gemini-ultra\". Standard: \"sonnet\", \"sonnet[1m]\", \"opus\", \"opusplan\", \"fable\", \"haiku\", \"gpt-5.4\", \"gpt-5.6-sol\", \"gpt-5.6-terra\", \"gpt-5.6-luna\", \"gpt-5.5\", \"gpt-5.4-mini\", \"gpt-5.3-codex\", \"gpt-5.3-codex-spark\", \"gpt-5.2\", \"gemini-2.5-pro\", \"gemini-2.5-flash\", \"gemini-3.1-pro-preview\", \"gemini-3-pro-preview\", \"gemini-3-flash-preview\", \"forge\", \"opencode\". Fable is an explicit selection and may require usage credits. OpenCode also accepts explicit dynamic models using \"oc-<provider/model>\". \"forge\" is a provider key, not a Forge model family selector."Input schema / properties / reasoning_effort / descriptionPrevious value: -"Reasoning control for Claude and Codex. Claude uses --effort with \"low\", \"medium\", \"high\", \"xhigh\", \"max\". Codex uses model_reasoning_effort with \"low\", \"medium\", \"high\", \"xhigh\". Gemini, Forge, and OpenCode do not support reasoning_effort in this integration."New value: +"Reasoning control for Claude and Codex. Claude uses --effort with \"low\", \"medium\", \"high\", \"xhigh\", \"max\". Codex uses model_reasoning_effort with \"low\", \"medium\", \"high\", \"xhigh\"; GPT-5.6 Sol and Terra also support \"max\" and \"ultra\", while Luna supports \"max\". Gemini, Forge, and OpenCode do not support reasoning_effort in this integration."v2.21.0cleanup_processesdoctorget_resultkill_processlist_processesmodelspeekrunwaitMost tools have distinct purposes (run, list, kill, wait, etc.), but wait and get_result both deal with results, and peek is similar to get_result but for short observation. Descriptions help differentiate them.
Naming is inconsistent: bare verbs (wait, peek, run), verb_noun (kill_process, cleanup_processes, get_result, list_processes), and nouns (doctor, models). 'Doctor' and 'peek' are informal and break the pattern.
9 tools is well-scoped for managing AI CLI processes, covering lifecycle, diagnostics, and model listing without being bloated.
Core lifecycle (start, list, get result, wait, kill, cleanup) is covered, plus diagnostic tools. Missing a tool to send input to a running process, but the set is largely functional for the domain.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Shared control plane for AI coding agents — tasks, memory, decisions, file locks. 12 tools.
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
Cross-agent artifact workspace with provenance across Claude Code, Codex, Cursor, LangGraph.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/mkXultra/ai-cli-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
