Skip to main content
Glama
Host Process & Sub-Agent Governor

Host Process & Sub-Agent Governor

by jasonroject

Host Process & Sub-Agent Governor (host-governor-plugin)

A lightweight Model Context Protocol (MCP) server providing host process supervision, multi-process management, and sub-agent concurrency control for AI agent environments including Google Antigravity and OpenAI Codex.


Key Capabilities

  • Sub-Agent Quota Enforcement: Strictly caps concurrent sub-agents to a configurable threshold (default: 3 per AI model) across Harness windows via atomic lockfiles and priority queueing.

  • Detached Background Execution: Spawns and manages asynchronous background software processes without blocking agent tool loops.

  • Process-Tree Termination: Ensures clean lifecycle management (taskkill /t on Windows, POSIX process groups on Unix) with graceful shutdown windows before force killing.

  • Bounded Ring Buffering: Retains head and tail logs while streaming high-throughput processes without unbounded memory consumption.

  • Automated Secret Redaction: Masks Bearer tokens, API credentials, and sensitive environment keys from stdout/stderr captures.

  • Cross-Harness Interoperability: Compatible with Antigravity (hooks.json PreToolUse hook) and standard MCP stdio clients.


Related MCP server: MCP Terminal

Quickstart

Prerequisites

  • Node.js (v18 or later)

  • npm

Installation & Build

# Install dependencies
npm install

# Compile TypeScript
npm run build

# Run Vitest test suite
npm test

Running the MCP Server

node dist/index.js

All JSON-RPC messages are communicated strictly over stdio. Diagnostics and internal logs are routed to stderr.


MCP Tools Reference

Tool

Purpose

host_exec_start

Launch a host process in the background

host_exec_status

Query state and metadata of running or completed processes

host_exec_logs

Retrieve bounded, secret-redacted process output

host_exec_input

Send input to a running interactive process via stdin

host_exec_stop

Terminate a process and its child process tree

governor_acquire_slot

Request a sub-agent concurrency lease

governor_release_slot

Release an active lease and unblock queue

governor_status

View global concurrency quotas and active processes

governor_diagnose

Inspect host platform, memory usage, and saturation status


Documentation

Detailed technical documentation is available in the docs/ directory:


License

MIT License. See LICENSE for details.

Available Tools

9 tools
governor_acquire_slotB

Acquire a sub-agent concurrency slot. Strictly enforces a limit of no more than 3 active sub-agents per AI model (cross-instance safe).

Inputs: modelId (required), subAgentName (required), priority, timeoutMs, +2 more.

governor_diagnoseA

Run deep diagnostics on the host execution environment, active sub-agent locks, and resource utilization.

Inputs: no named parameters.

governor_release_slotA

Release a previously acquired sub-agent slot, unblocking pending queued sub-agents for that model.

Inputs: leaseId (required).

governor_statusA

Inspect the current governor state: active sub-agents per model, queue depths, and running host background processes.

Inputs: modelId.

host_exec_inputB

Send stdin text to an active interactive background process.

Inputs: input (required), processId (required).

host_exec_logsB

Read captured stdout, stderr, and system logs from a background host process (with secret redaction).

Inputs: processId (required), tail, sinceTimestamp.

host_exec_startB

Spawn a software process running locally on the host machine in the background.

Inputs: command (required), cwd, tag, args, +5 more.

host_exec_statusA

Get status, exit code, state history, and runtime info of a background process, or list all running processes.

Inputs: processId.

host_exec_stopA

Stop or kill a running background host process and its entire child process tree.

Inputs: processId (required), force.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 9 tools

    Disambiguation4/5

    The tools are split into two clear domains, governor and host process management, with mostly distinct actions. The only mild overlap is between governor_status and governor_diagnose, but the descriptions distinguish routine state inspection from deeper diagnostics.

    Naming Consistency5/5

    All tool names use lowercase snake_case with consistent governor_ and host_exec_ prefixes. Verb choices are predictable: status, start, logs, input, stop, acquire, release, diagnose.

    Tool Count5/5

    Nine tools is well-scoped for managing host background processes and sub-agent concurrency. Each tool has a clear lifecycle role and no obvious redundant operations.

    Completeness4/5

    The host process lifecycle is well covered: start, inspect, read logs, send input, and stop. Governor concurrency is covered through status, acquire, release, and diagnose, though there is no explicit queue-management or stale-lock cleanup operation.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers