Runkeep

Runkeep

Runkeep keeps development servers, compilers, watchers, and other long-running processes shared between humans and AI agents.

One per-user daemon owns the processes. The runkeep CLI and runkeep-mcp server are clients of that daemon, so closing a terminal or finishing an agent task does not destroy the underlying service. Project services are identified by their canonical workspace path and name; global services use a separate user-level scope.

Install

Node.js 20 or newer is required. Install the signed-off v0.2.0 release globally with one command:

npm install --global https://github.com/3xjn/runkeep/releases/download/v0.2.0/runkeep-0.2.0.tgz

The same command works in PowerShell, Command Prompt, macOS terminals, and Linux shells. Confirm the installation:

runkeep --version

To uninstall:

npm uninstall --global runkeep

Install from source

git clone https://github.com/3xjn/runkeep.git
cd runkeep
npm install
npm run build
npm link

Quick start

From a project directory, we can create a neutral configuration and add services:

runkeep init
runkeep add rojo rojo serve
runkeep add typescript npm run watch
runkeep ensure
runkeep status

runkeep init deliberately creates only this ecosystem-neutral file:

{
  "services": {}
}

Examples such as the Roblox configuration live outside the product default.

Configuration

Runkeep discovers .runkeep.json from the current directory upward:

{
  "services": {
    "web": {
      "command": "npm run dev",
      "cwd": ".",
      "description": "Local web development server",
      "env": {
        "PORT": "3000"
      }
    },
    "worker": {
      "command": ["node", "worker.mjs"]
    }
  }
}

A string command runs through the platform shell. An array runs the executable directly. Relative cwd values resolve from the directory containing .runkeep.json.

Global services

For processes that should be available regardless of the current project, such as kubectl proxy, we can use the global scope:

runkeep --global init
runkeep --global add kubectl-proxy kubectl proxy
runkeep --global ensure kubectl-proxy
runkeep --global status
runkeep --global logs kubectl-proxy

Global services live in one user-level config.json: %APPDATA%\Runkeep\config.json on Windows, or $XDG_CONFIG_HOME/runkeep/config.json (normally ~/.config/runkeep/config.json) on macOS and Linux. Their default working directory is the user's home directory. --global and --workspace are intentionally mutually exclusive.

Human CLI

runkeep status
runkeep ensure [names...]
runkeep start <name>
runkeep stop <name>
runkeep restart <name>
runkeep logs <name> --tail 100
runkeep logs <name> --follow
runkeep attach <name>
runkeep send <name> <text...>
runkeep down

attach follows output and forwards entered lines to the service. Pressing Ctrl+C only detaches; it does not stop the managed process. Service commands accept either --workspace <path> or --global, plus --json.

Configuration can also be maintained without hand-editing:

runkeep add api npm run dev
runkeep add api npm run dev --cwd packages/api --description "API server"
runkeep remove api

MCP server

Any MCP host that supports local stdio servers can launch:

runkeep-mcp

For example, a host using JSON configuration can use:

{
  "mcpServers": {
    "runkeep": {
      "command": "runkeep-mcp",
      "cwd": "C:\\path\\to\\project"
    }
  }
}

Runkeep exposes:

• runkeep_status
• runkeep_ensure
• runkeep_start
• runkeep_stop
• runkeep_restart
• runkeep_logs
• runkeep_send
• runkeep_down

Every tool accepts an optional workspace and a scope of workspace (the default) or global. This lets one MCP server work with multiple projects and user-level services while keeping their identities separate.

Install project guidance for agents

MCP registration makes the tools available; AGENTS.md tells agents when and how to use them. Runkeep can safely manage its own instruction block:

runkeep agents install
runkeep agents status
runkeep agents install --dry-run
runkeep agents remove

Runkeep appends or updates only the text between these markers:

<!-- RUNKEEP_START -->
Runkeep-owned guidance lives here.
<!-- RUNKEEP_END -->

These are ordinary HTML comments, not special AGENTS.md syntax. They do not change instruction priority or scope; they only let Runkeep update its own content without touching user-authored instructions. Malformed or duplicate Runkeep markers are rejected instead of guessed at.

Agent-host MCP registration remains a separate, explicit action. For Codex:

codex mcp add runkeep -- runkeep-mcp

Runkeep does not edit host-specific MCP configuration automatically.

Check integration readiness

runkeep doctor
runkeep integrations status
runkeep doctor --json

The report checks the project .runkeep.json, Runkeep's AGENTS.md block, and whether runkeep and runkeep-mcp are on PATH. It does not claim to verify host-specific MCP registration.

Daemon behavior

The daemon starts automatically on the first command or MCP call that needs it.

runkeep daemon status
runkeep daemon start
runkeep daemon stop

Stopping the daemon stops every process it owns. On Windows, Runkeep terminates the full process tree through taskkill; on POSIX systems it uses process groups. Daemon communication stays local through a Windows named pipe or a user-only Unix socket.

Current MVP boundaries

• Process and log state lives in the daemon and is not reconstructed after a daemon or machine crash.
• A hard daemon crash can leave an unmanaged child process behind; Runkeep will not claim that process as managed after restarting.
• Readiness checks, automatic restart policies, persistent log files, and remote hosts are not implemented yet.
• Config files are trusted code: string commands execute through the platform shell.

These boundaries keep the first version small while preserving the CLI/MCP/daemon architecture needed to add those capabilities later.