# runmedev/runme architecture

> Architecture diagram of the GitHub repository runmedev/runme, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/runmedev/runme
- Repository: https://github.com/runmedev/runme

## Overview

Runme turns Markdown code cells into runnable, stateful workflows. A user discovers or inspects cells with the CLI, then runs a named task; project and document handling provide task context, and a runner executes commands while retaining session environment. The repository also exposes parser, project, notebook, and runner services, plus an agent server with streaming and optional authentication. Harbor provides a separate command-execution interface. The main workflow is documented in the README; some links are supported only by source-index references, so unsampled behavior is not inferred.

Main entry points: [`runner/service.go`](https://github.com/runmedev/runme/blob/main/runner/service.go) (Runner service), [`cmd/server.go`](https://github.com/runmedev/runme/blob/main/cmd/server.go) (Local service command), [`cmd`](https://github.com/runmedev/runme/tree/main/cmd) (Runme CLI), [`runner/client/client.go`](https://github.com/runmedev/runme/blob/main/runner/client/client.go) (Runner clients)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflow"]
  node_cli["Runme CLI"]
end

subgraph group_docs["Documents and projects"]
  node_project["Project and tasks<br/>[project.go]"]
  node_parser["Markdown parser<br/>[parser.go]"]
  node_editor["Notebook editor<br/>[editor.go]"]
end

subgraph group_execution["Execution runtime"]
  node_runnerclient["Runner clients<br/>[client.go]"]
  node_remoteclient["Remote runner<br/>[client_remote.go]"]
  node_runner["Runner service<br/>[service.go]"]
  node_session["Execution sessions<br/>[session.go]"]
  node_commands["Command runtime<br/>[factory.go]"]
end

subgraph group_services["Services and agent"]
  node_servercmd["Local service command<br/>[server.go]"]
  node_grpcserver["gRPC server<br/>[server.go]"]
  node_parserapi["Parser service<br/>[service.go]"]
  node_notebookapi["Notebook service<br/>[service.go]"]
  node_agentapp["Agent application<br/>[app.go]"]
  node_agentserver["Agent server<br/>[server.go]"]
  node_stream["WebSocket streams<br/>[handler.go]"]
  node_agentapi["Agent RPC contracts<br/>[service.proto]"]
  node_parsercontracts["Parser RPC contracts<br/>[parser_pb.js]"]
  node_agentnotebook["Agent notebook contracts<br/>[notebooks_pb.js]"]
end

subgraph group_harbor["Harbor execution"]
  node_harbor["Harbor server<br/>[server.go]"]
  node_harboragent["Harbor integration<br/>[runme_agents.py]"]
end

node_user(("Runbook user"))

node_user -->|"runs or lists"| node_cli
node_cli -->|"selects tasks"| node_project
node_cli -.->|"runs task"| node_runnerclient
node_runnerclient -->|"uses project"| node_project
node_runnerclient -->|"uses document"| node_parser
node_remoteclient -->|"RPC requests"| node_runner
node_runner -->|"manages sessions"| node_session
node_runner -->|"builds commands"| node_commands
node_servercmd -->|"registers service"| node_parserapi
node_servercmd -->|"registers service"| node_notebookapi
node_servercmd -->|"registers runner"| node_runner
node_grpcserver -.->|"hosts services"| node_parserapi
node_parserapi -->|"deserializes notebook"| node_editor
node_agentapp -.->|"configures server"| node_agentserver
node_agentserver -->|"registers streams"| node_stream
node_agentserver -.->|"serves API"| node_agentapi
node_harbor -->|"builds commands"| node_commands
node_harboragent -.->|"integrates with"| node_harbor

click node_cli "https://github.com/runmedev/runme/tree/main/cmd"
click node_project "https://github.com/runmedev/runme/blob/main/project/project.go"
click node_parser "https://github.com/runmedev/runme/blob/main/document/parser.go"
click node_editor "https://github.com/runmedev/runme/blob/main/document/editor/editor.go"
click node_runnerclient "https://github.com/runmedev/runme/blob/main/runner/client/client.go"
click node_remoteclient "https://github.com/runmedev/runme/blob/main/runner/client/client_remote.go"
click node_runner "https://github.com/runmedev/runme/blob/main/runner/service.go"
click node_session "https://github.com/runmedev/runme/blob/main/runner/session.go"
click node_commands "https://github.com/runmedev/runme/blob/main/command/factory.go"
click node_servercmd "https://github.com/runmedev/runme/blob/main/cmd/server.go"
click node_grpcserver "https://github.com/runmedev/runme/blob/main/internal/server/server.go"
click node_parserapi "https://github.com/runmedev/runme/blob/main/document/editor/editorservice/service.go"
click node_notebookapi "https://github.com/runmedev/runme/blob/main/notebook/service.go"
click node_agentapp "https://github.com/runmedev/runme/blob/main/pkg/agent/application/app.go"
click node_agentserver "https://github.com/runmedev/runme/blob/main/pkg/agent/server/server.go"
click node_stream "https://github.com/runmedev/runme/blob/main/pkg/agent/runme/stream/handler.go"
click node_agentapi "https://github.com/runmedev/runme/blob/main/api/proto/agent/v1/service.proto"
click node_parsercontracts "https://github.com/runmedev/runme/blob/main/api/gen/proto/ts/runme/parser/v1/parser_pb.js"
click node_agentnotebook "https://github.com/runmedev/runme/blob/main/api/gen/proto/es/agent/tools/v1/notebooks_pb.js"
click node_harbor "https://github.com/runmedev/runme/blob/main/internal/harbor/server.go"
click node_harboragent "https://github.com/runmedev/runme/blob/main/integrations/harbor/src/runme_harbor/runme_agents.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_user toneBlue
class node_project,node_parser,node_editor toneAmber
class node_runnerclient,node_remoteclient,node_runner,node_session,node_commands toneMint
class node_servercmd,node_grpcserver,node_parserapi,node_notebookapi,node_agentapp,node_agentserver,node_stream,node_agentapi,node_parsercontracts,node_agentnotebook toneRose
class node_harbor,node_harboragent toneIndigo
```

## Components

### CLI workflow

- [Runme CLI](https://github.com/runmedev/runme/tree/main/cmd): `cmd`

### Documents and projects

- [Project and tasks](https://github.com/runmedev/runme/blob/main/project/project.go): `project/project.go`
- [Markdown parser](https://github.com/runmedev/runme/blob/main/document/parser.go): `document/parser.go`
- [Notebook editor](https://github.com/runmedev/runme/blob/main/document/editor/editor.go): `document/editor/editor.go`

### Execution runtime

- [Runner clients](https://github.com/runmedev/runme/blob/main/runner/client/client.go): `runner/client/client.go`
- [Remote runner](https://github.com/runmedev/runme/blob/main/runner/client/client_remote.go): `runner/client/client_remote.go`
- [Runner service](https://github.com/runmedev/runme/blob/main/runner/service.go): `runner/service.go`
- [Execution sessions](https://github.com/runmedev/runme/blob/main/runner/session.go): `runner/session.go`
- [Command runtime](https://github.com/runmedev/runme/blob/main/command/factory.go): `command/factory.go`

### Services and agent

- [Local service command](https://github.com/runmedev/runme/blob/main/cmd/server.go): `cmd/server.go`
- [gRPC server](https://github.com/runmedev/runme/blob/main/internal/server/server.go): `internal/server/server.go`
- [Parser service](https://github.com/runmedev/runme/blob/main/document/editor/editorservice/service.go): `document/editor/editorservice/service.go`
- [Notebook service](https://github.com/runmedev/runme/blob/main/notebook/service.go): `notebook/service.go`
- [Agent application](https://github.com/runmedev/runme/blob/main/pkg/agent/application/app.go): `pkg/agent/application/app.go`
- [Agent server](https://github.com/runmedev/runme/blob/main/pkg/agent/server/server.go): `pkg/agent/server/server.go`
- [WebSocket streams](https://github.com/runmedev/runme/blob/main/pkg/agent/runme/stream/handler.go): `pkg/agent/runme/stream/handler.go`
- [Agent RPC contracts](https://github.com/runmedev/runme/blob/main/api/proto/agent/v1/service.proto): `api/proto/agent/v1/service.proto`
- [Parser RPC contracts](https://github.com/runmedev/runme/blob/main/api/gen/proto/ts/runme/parser/v1/parser_pb.js): `api/gen/proto/ts/runme/parser/v1/parser_pb.js`
- [Agent notebook contracts](https://github.com/runmedev/runme/blob/main/api/gen/proto/es/agent/tools/v1/notebooks_pb.js): `api/gen/proto/es/agent/tools/v1/notebooks_pb.js`

### Harbor execution

- [Harbor server](https://github.com/runmedev/runme/blob/main/internal/harbor/server.go): `internal/harbor/server.go`
- [Harbor integration](https://github.com/runmedev/runme/blob/main/integrations/harbor/src/runme_harbor/runme_agents.py): `integrations/harbor/src/runme_harbor/runme_agents.py`

### Other components

- **Runbook user**

## Connections

- Runbook user → Runme CLI: runs or lists (evidence: `README.md`)
- Runme CLI → Project and tasks: selects tasks (evidence: `README.md`)
- Runme CLI → Runner clients: runs task
- Runner clients → Project and tasks: uses project (evidence: `runner/client/client.go`)
- Runner clients → Markdown parser: uses document (evidence: `runner/client/client.go`)
- Remote runner → Runner service: RPC requests (evidence: `runner/client/client_remote.go`)
- Runner service → Execution sessions: manages sessions (evidence: `runner/service.go`)
- Runner service → Command runtime: builds commands (evidence: `runner/service.go`)
- Local service command → Parser service: registers service (evidence: `cmd/server.go`)
- Local service command → Notebook service: registers service (evidence: `cmd/server.go`)
- Local service command → Runner service: registers runner (evidence: `cmd/server.go`)
- gRPC server → Parser service: hosts services
- Parser service → Notebook editor: deserializes notebook (evidence: `document/editor/editorservice/service.go`)
- Agent application → Agent server: configures server
- Agent server → WebSocket streams: registers streams (evidence: `pkg/agent/server/server.go`)
- Agent server → Agent RPC contracts: serves API
- Harbor server → Command runtime: builds commands (evidence: `internal/harbor/server.go`)
- Harbor integration → Harbor server: integrates with
