persistproc

1# persistproc
2 
3A shared process layer for multi-agent development workflows
4 
5[![PyPI version](https://badge.fury.io/py/persistproc.svg)](https://badge.fury.io/py/persistproc)
6[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
7[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
8 
9---
10 
11> Full docs: [steveasleep.com/persistproc](https://steveasleep.com/persistproc).
12 
13## What is `persistproc`?
14 
15Persistproc is an MCP server and command line tool which lets agents and humans see and control long-running processes like web servers. The goal is to reduce the amount of copying and pasting you need to do while coding with AI, make it easier for you to use multiple agents, and be tool-agnostic.
16 
17There is no config file. Processes are managed entirely at runtime. This is not a replacement for supervisord.
18 
19### Example use case: basic web development
20 
21Suppose you're working on a todo list app, and it has a dev server you normally start with `npm run dev`. This server watches your code for changes, typechecks it, lints it, and hot-reloads the page. When there's an error, it prints the error to your terminal.
22 
23If you're working with an LLM agent such as Cursor or Claude Code, if you see an error, you might copy/paste it from your terminal to the agent and ask how to fix it. Then the agent might make some changes, and maybe you hit another error, so you copy/paste again, and the agent makes another change…etc.
24 
25If the agent could see the changes directly, you wouldn't need to do anything! With persistproc, that's possible. Instead of saying `npm run dev`, say `persistproc npm run dev`, and the agent can instantly read its output or even restart it. Otherwise, you can still see its output in your original terminal, and kill it with Ctrl+C, like your normally do.
26 
27```mermaid
28graph TB
29    User[User] -->|"persistproc npm run dev"| PP[persistproc server]
30    PP <-->|"manages / logs"| NPM["npm run dev<br/>(web server)"]
31    PP -.->|"streams output"| User
32    
33    Agent[Cursor] -.->|"output()<br/>restart()"| PP
34    
35    style PP fill:#e1f5fe,stroke:#01579b,stroke-width:2px
36    style NPM fill:#fff3e0,stroke:#e65100,stroke-width:2px
37    style User fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
38    style Agent fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
39```
40 
41> [!NOTE]
42> **Why not just use Cursor and let the agent open a terminal?**
43>
44> 1. Not everyone likes using the terminal in Cursor/VSCode. Engineers have many different workflows.
45> 2. _Only_ Cursor's agents can see the process, not Claude Code, Gemini CLI, etc.
46 
47### Example use case: complex web development
48 
49Suppose you need to run four processes to get your web app working locally. Maybe an API, frontend server, SCSS builder, and Postgres. Each service emits its own logs.
50 
51If you run into an error while testing locally, you can go read all four log files to find out what happened.
52 
53But if you started those processes with persistproc, then the agent can read everything at once and possibly give you a quicker diagnosis.
54 
55```mermaid
56graph TB
57    User[User] -->|"starts processes"| PP[persistproc server]
58    
59    subgraph processes["Managed Processes"]
60        API[API Server]
61        FE[Frontend Server]
62        SCSS[SCSS Builder]
63        DB[Postgres]
64    end
65    
66    PP <-->|"manages / logs"| processes
67    
68    Agent1[Claude Code] -.->|"read logs<br/>diagnose issues"| PP
69    Agent2[Cursor] -.->|"read logs<br/>diagnose issues"| PP
70    
71    style PP fill:#e1f5fe,stroke:#01579b,stroke-width:2px
72    style API fill:#fff3e0,stroke:#e65100,stroke-width:2px
73    style FE fill:#fff3e0,stroke:#e65100,stroke-width:2px
74    style SCSS fill:#fff3e0,stroke:#e65100,stroke-width:2px
75    style DB fill:#fff3e0,stroke:#e65100,stroke-width:2px
76    style User fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
77    style Agent1 fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
78    style Agent2 fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
79    style processes fill:#f5f5f5,stroke:#999,stroke-width:1px,stroke-dasharray: 5 5
80```
81 
82> [!NOTE]
83> **What if my processes are started by another system?**
84>
85> Then your best bet is to write log files to a predictable location and tell the agent where they are,
86> rather than trying to use persistproc. Or, you can follow [this issue on GitHub](https://github.com/irskep/persistproc/issues/25).
87>
88> Currently, persistproc is most useful when you want your agent to be able to _manage_ processes, not
89> just see their output.
90 
91## Available Tools
92 
93`persistproc` exposes a standard [Model Context Protocol (MCP)](https://modelcontext.com/) server on `http://127.0.0.1:8947`. You can use any MCP-compatible client to interact with it programmatically.
94 
95The server exposes the following tools:
96 
97| Tool | Description |
98| --- | --- |
99| ctrl | Unified process control: start, stop, or restart processes. |
100| list | List all managed processes and their status. Can optionally filter by pid, command, or working directory and provides log paths. |
101| output | Retrieve captured output from a process. |
102 
103This list is intentionally short because LLMs perform worse with too many tools, to the point where some IDEs (such as Cursor) have a cap on how many tools you can have.
104 
105## Getting started
106 
107### 1. Install `persistproc`
108 
109```bash
110pip install persistproc
111```
112 
113### 2. Start the server and configure your agent
114 
115Run this in a dedicated terminal and leave it running.
116 
117```bash
118persistproc serve
119```
120 
121The first thing `persistproc serve` outputs is configuration instructions for various agents, so follow those instructions if you haven't already.
122 
123### 3. Start a Process
124 
125In another terminal, `cd` to your project's directory and run your command via `persistproc`.
126 
127```bash
128# Example: starting a Node.js development server
129cd /path/to/your/project
130persistproc npm run dev
131```
132 
133The command is sent to the server, and its output is streamed to your terminal. You can safely close this terminal, and the process will continue to run.
134 
135 
136> [!TIP]
137> Or just ask your agent to "run your dev server using persistproc," and it will probably find the right command by looking at your `package.json` file and run it using `persistproc`.
138 
139With this, your agent can now use the available tools to manage your development environment.
140 
141## Example Agent Interaction
142 
143Once your agent is connected, you can ask it to manage your processes. Assuming you have started a web server with `persistproc npm run dev` (PID 12345), you can now interact with it.
144 
145*   **You**: "List the running processes."
146    *   **Agent**: Calls `list()` and shows you the running `npm run dev` process.
147 
148*   **You**: "The web server seems stuck. Can you restart it?"
149    *   **Agent**: Identifies the correct process and calls `ctrl(action="restart", pid=12345)`.
150 
151*   **You**: "Show me any errors from the web server."
152    *   **Agent**: Calls `output(pid=12345, stream="stderr")` to retrieve the latest error logs.
153 
154## Development
155 
156Run persistproc in a fully configured virtualenv with `./pp`. Run other commands such as `pytest` in a virtualenv with `uv run`.
157 
158## License
159 
160This project is licensed under the MIT License.