Introducing framework-shells for MCP and Codex orchestration

[MrSurge]

[Showcase] framework-shells: Lightweight Process Orchestration for MCP & Codex Servers

Hi everyone,

I’m sharing framework-shells, a Python-based process orchestration engine for managing long-running background processes—like hosting a Codex MCP server, running JSON-RPC stdio servers, or providing interactive PTYs for agents/tools.

In the context of MCP/Codex CLI, it handles the “heavy lifting” of process lifecycle management: start/stop/restart, PID tracking, log capture, and (optionally) persistence across restarts via dtach.

Why use it for MCP?

• Multiple Backends: Use PTY for interactive terminals, Pipes for JSON-RPC/stdio servers, or dtach for persistent sessions.
• Runtime Namespacing: Namespaced storage based on repo fingerprints and secrets—useful for multi-project environments.
• Live Monitoring: Built-in FastAPI router with a dashboard and real-time logs via WebSockets.
• Shellspec (YAML): Define your server configurations in simple YAML files for easy deployment.

Note: this is not a security sandbox by itself; it’s a lifecycle/orchestration layer. If you need stronger containment, pair it with allowlisted shellspecs and OS-level sandboxing.

Example Use Case

If you are building an MCP server that needs to host a persistent shell or a sidecar LSP server, you can orchestrate it via framework-shells to get automatic logging, PID tracking, and graceful shutdowns out of the box.

Here’s a tiny example of managing a stdio-style server (like an MCP server) as a long-lived process:

from framework_shells import get_manager

mgr = await get_manager()
rec = await mgr.spawn_shell_pipe(["codex", "mcp-server"], label="mcp:codex")

# Subscribe to output and stream it elsewhere (logs/UI/WebSocket)
q = await mgr.subscribe_output(rec.id)

# Send input (JSON-RPC) into the process
await mgr.write_to_pty(rec.id, '{"jsonrpc":"2.0","id":1,"method":"ping"}\\n')

Quick Start

You can install it directly via pip:

python -m pip install "framework-shells @ git+https://github.com/mrsurge/framework-shells@main"

GitHub - mrsurge/framework-shells: Framework Shells: process orchestration + shells...

Improvement

• Tell me where I need improvement, I’m actively developing this framework… And im sure I am missing a bunch of use cases, scenarios, pain points, etc …

[MrSurge]

I think the main thing here (that my admittedly AI generated summary didn’t convey) is that you could build an app import this module, and you get, based on the directory it’s in, an isolated run time process tree and app worker supervision… For free. And that comes with metrics, logging, and a dashboard.

So let’s say you have a web-based (or really any kind of app it has a CLI UX as well) app, and you want to include a terminal, or a language server, or an agent, this gives you a control plane and process supervision for those child processes.

And the kicker is, you can import it in multiple repos, and run multiple instances of it, and the processed trees will not interfere with each other, out of the box.

[MrSurge]