# 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:

```powershell
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:

```powershell
runkeep --version
```

To uninstall:

```powershell
npm uninstall --global runkeep
```

### Install from source

```powershell
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:

```powershell
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:

```json
{
  "services": {}
}
```

Examples such as the [Roblox configuration](examples/roblox/.runkeep.json) live outside the product default.

## Configuration

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

```json
{
  "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:

```powershell
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

```text
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:

```powershell
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:

```text
runkeep-mcp
```

For example, a host using JSON configuration can use:

```json
{
  "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:

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

Runkeep appends or updates only the text between these markers:

```md
<!-- 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:

```powershell
codex mcp add runkeep -- runkeep-mcp
```

Runkeep does not edit host-specific MCP configuration automatically.

### Check integration readiness

```powershell
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.

```powershell
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.