Skip to the content.

Architecture

Runtime topology

CLike is split into three main runtime components.

VS Code extension
  β”œβ”€ chat UI
  β”œβ”€ slash commands
  β”œβ”€ code actions
  β”œβ”€ attachment handling
  β”œβ”€ local agent execution
  └─ Git integration
        β”‚
        β–Ό
Orchestrator (FastAPI, default port 8080)
  β”œβ”€ Harper workflow control
  β”œβ”€ RAG APIs
  β”œβ”€ eval/gate endpoints
  β”œβ”€ legacy chat/generate APIs
  β”œβ”€ agent code-action API
  β”œβ”€ routing APIs
  └─ optional read-only MCP server
        β”‚            β”‚
        β”‚            └─▢ eval-sandbox (runs eval/gate checks, no credentials)
        β”‚                 └─ eval-tools (installs catalog tools into a read-only volume)
        β–Ό
Gateway (FastAPI, default port 8000)
  β”œβ”€ model catalog
  β”œβ”€ model validation
  β”œβ”€ provider-routed chat completions
  β”œβ”€ embeddings
  β”œβ”€ Harper phase execution
  └─ telemetry APIs / UI
        β”‚
        β–Ό
Providers / infra
  β”œβ”€ OpenAI
  β”œβ”€ Anthropic
  β”œβ”€ OpenAI-compatible endpoints (Ollama, ...)
  └─ Qdrant (RAG store, used by the orchestrator)

Component responsibilities

VS Code extension

The extension is the primary user entrypoint.

Responsibilities:

Key implementation files:

Orchestrator

The orchestrator is the control plane.

Responsibilities:

Key implementation files:

Gateway

The gateway is the model and provider execution layer.

Responsibilities:

Key implementation files:

Harper architecture

Harper is implemented as a repository-aware iterative pipeline, not as a single monolithic generation step.

Canonical flow

A delivered project evolves by releases: /idea --extend (EXTEND phase, cascade mode) merges the release inputs into IDEA, SPEC and TECH_CONSTRAINTS and appends a PLAN delta of ADDED / MODIFIED / REMOVED REQs, which then go through KIT β†’ EVAL β†’ GATE β†’ FINALIZE. /extend only appends REQs.

Operational split

Candidate-first design

A core architectural rule in current sources is that generated implementation artifacts are first written under candidate roots, not promoted directly.

Primary candidate root:

Common subtrees:

This separation is foundational for:

Local vs cloud execution paths

The current architecture supports two execution paths for compatible Harper work:

Cloud path

Local agent path

MCP position in architecture

The orchestrator mounts a FastMCP server at /mcp when enabled.

Current MCP characteristics:

The VS Code extension runs a second, operational MCP server (off by default, loopback, token): it runs Harper phases, eval_run and gate_check through the same governed chat flow, without overrides, promotion choices or Git.

RAG position in architecture

RAG spans extension, orchestrator, gateway, and Qdrant-backed storage.

Extension

Orchestrator

Gateway

Telemetry position in architecture

Telemetry is currently gateway-centric for Harper execution visibility.

Main telemetry surfaces:

The orchestrator also keeps run-oriented artifacts under runs/<runId>/....

Current architectural constraints

The current sources imply the following constraints: