# https://github.com/hecateq/hecateq-openagent Project Manual

Generated at: 2026-06-21 01:33:13 UTC

## Table of Contents

- [Overview and Plugin Architecture](#page-1)
- [Hecateq Orchestration Pipeline](#page-2)
- [Memory System and Context Injection](#page-3)
- [CLI Commands and Doctor Diagnostics](#page-4)

<a id='page-1'></a>

## Overview and Plugin Architecture

### Related Pages

Related topics: [Hecateq Orchestration Pipeline](#page-2), [Memory System and Context Injection](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [package.json](https://github.com/hecateq/hecateq-openagent/blob/main/package.json)
- [packages/lsp-tools-mcp/README.md](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/README.md)
- [packages/lsp-tools-mcp/package.json](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/package.json)
- [packages/lsp-tools-mcp/src/lsp/language-mappings.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/src/lsp/language-mappings.ts)
- [packages/lsp-tools-mcp/src/lsp/types.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/src/lsp/types.ts)
- [packages/rules-engine/src/constants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/rules-engine/src/constants.ts)
- [packages/model-core/src/index.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/index.ts)
- [packages/model-core/src/model-requirements.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-requirements.ts)
- [packages/model-core/src/model-resolution-types.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-resolution-types.ts)
- [packages/model-core/src/model-capabilities/get-model-capabilities.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-capabilities/get-model-capabilities.ts)
- [packages/model-core/src/known-variants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/known-variants.ts)
- [packages/web/package.json](https://github.com/hecateq/hecateq-openagent/blob/main/packages/web/package.json)
</details>

# Overview and Plugin Architecture

Hecateq OpenAgent (`v0.1.0-hecateq.1`, beta) is a production-grade fork of `oh-my-openagent` designed to plug into the Hecateq agentic workflow engine that runs inside OpenCode. The repository is organized as a TypeScript monorepo: a top-level plugin/CLI binary plus a collection of internal packages that each own a single concern (LSP tooling, rules, model resolution, state, web UI). The release notes advertise task-graph orchestration, self-healing memory management, and validation safeguards as headline features, all of which are layered on top of the same plugin surface the upstream project exposes.

## Monorepo Layout and Public Surface

The root `package.json` declares the public entry points for downstream consumers, published under the `beta` npm tag (`Source: [package.json:1-50]()`):

| Export | Path | Purpose |
|---|---|---|
| `.` | `./dist/index.d.ts`, `./dist/index.js` | Plugin entry (type + runtime) |
| `./server` | `./dist/index.js` | Server-mode runtime re-export |
| `./schema.json` | `./dist/oh-my-opencode.schema.json` | Upstream-compatible config schema |
| `./hecateq-schema.json` | `./dist/hecateq-openagent.schema.json` | Hecateq-flavored config schema |

The root build pipeline stitches together the `ast-grep-mcp` package, the main Bun entry (`src/index.ts`), a Node `require` shim, and the JSON schema generator, then runs `tsc --emitDeclarationOnly` to produce `.d.ts` files (`Source: [package.json:51-90]()`). A separate `build:lsp-tools-mcp` script delegates into the `packages/lsp-tools-mcp` workspace so the LSP runtime is rebuilt in lockstep with the plugin (`Source: [package.json:91-130]()`).

Internal packages share a common shape (`packages/*`):

- **`packages/lsp-tools-mcp`** — standalone LSP-over-MCP server (see below).
- **`packages/model-core`** — canonical model identifiers, fallback chains, capability resolution.
- **`packages/rules-engine`** — discovery and priority resolution for project/user rule files.
- **`packages/ast-grep-mcp`**, **`packages/comment-checker-core`**, **`packages/hashline-core`**, **`packages/boulder-state`**, **`packages/agents-md-core`**, **`packages/utils`** — supporting libraries, each gated behind its own `tsconfig.json` and typechecked individually by the root `typecheck` script (`Source: [package.json:131-180]()`).
- **`packages/web`** — Next.js 15 / React 19 dashboard deployed to Cloudflare via `opennextjs-cloudflare` (`Source: [packages/web/package.json:1-60]()`).

## LSP Tools MCP Subsystem

`packages/lsp-tools-mcp` is the upstream source of truth for two downstream plugins (`codex-lsp` and `oh-my-openagent`), both of which consume it as a git submodule rather than forking the runtime (`Source: [packages/lsp-tools-mcp/README.md:1-30]()`). The package ships as a stdio MCP server with the binary name `lsp-tools-mcp` pointing at `./dist/cli.js` (`Source: [packages/lsp-tools-mcp/package.json:1-40]()`).

The runtime exposes tools such as `lsp_diagnostics`, `lsp_goto_definition`, `lsp_find_references`, `lsp_symbols`, `lsp_prepare_rename`, `lsp_rename`, and `lsp_status` (`Source: [packages/lsp-tools-mcp/README.md:31-60]()`). Internally, file extensions are normalized to LSP language IDs through a hand-maintained table covering common ecosystems (TypeScript, Python, Rust, Go, Ruby, Zig, etc.) (`Source: [packages/lsp-tools-mcp/src/lsp/language-mappings.ts:1-60]()`). Strongly-typed LSP wire types — `Diagnostic`, `TextEdit`, `WorkspaceEdit`, `PrepareRenameResult`, and the `SeverityFilter` union — live alongside the runtime so refactors stay type-safe end-to-end (`Source: [packages/lsp-tools-mcp/src/lsp/types.ts:1-60]()`).

```mermaid
flowchart LR
  Agent[OpenCode Agent] -- "stdio MCP" --> Server[lsp-tools-mcp]
  Server -- "LSP wire protocol" --> Backend[Language Servers]
  Backend -- "diagnostics / symbols / edits" --> Server
  Server -- "typed JSON" --> Agent
```

## Model Resolution and Capability Layer

The `model-core` package owns the policy that decides which provider/model pair an agent actually uses at runtime. It re-exports everything needed by callers: `resolveModel`, `resolveModelWithFallback`, `normalizeFallbackModels`, `flattenToFallbackModelStrings`, capability heuristics, alias maps, sanitizers, and error classifiers (`Source: [packages/model-core/src/index.ts:1-50]()`).

Three contracts sit at the center of the layer:

1. **`DelegatedModelConfig`** captures the per-call knob set (provider, model, variant, reasoning effort, temperature, top_p, maxTokens, thinking) (`Source: [packages/model-core/src/model-resolution-types.ts:1-40]()`).
2. **`ModelResolutionRequest`** carries `intent`, `constraints.availableModels`, and an optional `policy.fallbackChain` plus `systemDefaultModel` (`Source: [packages/model-core/src/model-resolution-types.ts:41-70]()`).
3. **`ModelResolutionResult`** returns the chosen model plus a `provenance` tag (`"override" | "category-default" | "provider-fallback" | "system-default"`) and an `attempted` trail for diagnostics (`Source: [packages/model-core/src/model-resolution-types.ts:71-90]()`).

Fallback chains are expressed as ordered `FallbackEntry` lists of `{ providers, model, variant }` triples. For example, the `unspecified-low` category tries Anthropic Claude Sonnet 4.6 first, then `gpt-5.3-codex`, then Kimi K2.6, Gemini 3 Flash, and a MiniMax fallback (`Source: [packages/model-core/src/model-requirements.ts:1-60]()`). Recognized variant tokens are centralized in `KNOWN_VARIANTS` (`low`, `medium`, `high`, `xhigh`, `max`, `minimal`, `none`, `auto`, `thinking`) so parsers and flatten helpers agree on what counts as an effort suffix (`Source: [packages/model-core/src/known-variants.ts:1-12]()`).

`getModelCapabilities` produces a `ModelCapabilitiesDiagnostics` block that tags every field with its resolution source — `"runtime"`, `"override"`, `"heuristic"`, `"snapshot"`, or `"none"` — making it possible to debug why a particular model ends up reasoning-capable or not (`Source: [packages/model-core/src/model-capabilities/get-model-capabilities.ts:1-90]()`).

## Rules Engine and Project Discovery

The `rules-engine` package supplies the discovery layer that locates rule files in a project and ranks them by provenance. Constants cover:

- **Project markers** used to detect repository roots: `.git`, `pyproject.toml`, `package.json`, `Cargo.toml`, `go.mod`, `.venv` (`Source: [packages/rules-engine/src/constants.ts:1-15]()`).
- **Rule subdirectories** consulted in order — `.omo/rules`, `.claude/rules`, `.cursor/rules`, `.github/instructions`, `.sisyphus/rules` — plus the standalone `.github/copilot-instructions.md` file (`Source: [packages/rules-engine/src/constants.ts:16-40]()`).
- **User-level rule directories** under the home folder, mirroring the project set with priority offsets (`Source: [packages/rules-engine/src/constants.ts:41-60]()`).
- **`SOURCE_PRIORITY`** as a `ReadonlyMap<RuleSource, number>` that gives project-local rules priority 0–5 and user-level rules priority 100–103 (`Source: [packages/rules-engine/src/constants.ts:61-90]()`).
- **`EXCLUDED_DIRS`** (`node_modules`, `.git`, `dist`, `build`, `.turbo`, `.next`, `coverage`) and the canonical `AGENTS.md` filename (`Source: [packages/rules-engine/src/constants.ts:91-110]()`).

## Extension Points for Downstream

Two patterns make the architecture extendable without forking the runtime:

- **Git submodule consumption** for the LSP runtime — fixes or features land upstream in `code-yeongyu/lsp-tools-mcp` and are pulled in via a submodule pointer bump (`Source: [packages/lsp-tools-mcp/README.md:1-20]()`).
- **Schema-tagged configuration** — the root package exports both the upstream `oh-my-opencode.schema.json` and a Hecateq-specific `hecateq-openagent.schema.json`, letting forks carry their own config keys without colliding with upstream (`Source: [package.json:20-50]()`).

Together, these choices keep the plugin surface narrow (one entry, two schema variants, one LSP binary) while letting internal packages evolve independently behind their own `tsconfig.json` boundaries.

## See Also

- LSP Tools MCP runtime: [packages/lsp-tools-mcp/README.md](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/README.md)
- Model requirements and fallback chains: [packages/model-core/src/model-requirements.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-requirements.ts)
- Rules engine discovery constants: [packages/rules-engine/src/constants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/rules-engine/src/constants.ts)
- Model resolution pipeline: [packages/model-core/src/model-resolution-types.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-resolution-types.ts)
- Build and typecheck pipeline: [package.json](https://github.com/hecateq/hecateq-openagent/blob/main/package.json)

---

<a id='page-2'></a>

## Hecateq Orchestration Pipeline

### Related Pages

Related topics: [Overview and Plugin Architecture](#page-1), [Memory System and Context Injection](#page-3), [CLI Commands and Doctor Diagnostics](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [package.json](https://github.com/hecateq/hecateq-openagent/blob/main/package.json)
- [packages/model-core/src/index.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/index.ts)
- [packages/model-core/src/model-requirements.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-requirements.ts)
- [packages/model-core/src/model-capability-heuristics.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-capability-heuristics.ts)
- [packages/model-core/src/model-capabilities/get-model-capabilities.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-capabilities/get-model-capabilities.ts)
- [packages/model-core/src/model-capabilities/types.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-capabilities/types.ts)
- [packages/rules-engine/src/constants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/rules-engine/src/constants.ts)
- [packages/lsp-tools-mcp/README.md](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/README.md)
- [packages/ast-grep-mcp/src/mcp.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/ast-grep-mcp/src/mcp.ts)
</details>

# Hecateq Orchestration Pipeline

## Overview and Purpose

The **Hecateq Orchestration Pipeline** is the coordinating layer that turns a user request submitted to OpenCode into a routed, capability-aware, and rule-governed multi-model execution. It is the defining addition in the Hecateq fork of `oh-my-openagent`, packaged and distributed as `@hecateq/hecateq-openagent` (entry point `./dist/index.js`, registered as the OpenCode plugin through `@opencode-ai/plugin`).

Source: [package.json](https://github.com/hecateq/hecateq-openagent/blob/main/package.json)

The pipeline is implemented as a set of cooperating workspaces rather than a single monolith. The `workspaces` field in `package.json` declares nine internal packages (`rules-engine`, `ast-grep-core`, `ast-grep-mcp`, `utils`, `model-core`, `comment-checker-core`, `hashline-core`, `boulder-state`, `agents-md-core`) that together provide the capabilities required to plan, route, and supervise an agent run. Cross-cutting policy is enforced through a single `overrides` block for `hono`, `express-rate-limit`, `fast-uri`, and `path-to-regexp`, indicating the plugin runs alongside an HTTP layer.

Source: [package.json](https://github.com/hecateq/hecateq-openagent/blob/main/package.json)

## Architecture

```mermaid
flowchart LR
    User[User Request in OpenCode] --> Plugin[hecateq-openagent Plugin Entry]
    Plugin --> Rules[Rules Engine<br/>project + user rules]
    Plugin --> Resolver[Model Resolution Pipeline<br/>model-core]
    Rules --> Planner[Task Categorization]
    Resolver --> Planner
    Planner --> Fallback[Fallback Chain<br/>per category]
    Fallback --> LSP[LSP Tools MCP<br/>diagnostics/rename/symbols]
    Fallback --> AST[ast-grep MCP<br/>pattern match/replace]
    Fallback --> Mem[Boulder State<br/>self-healing memory]
    Fallback --> Result[Structured Output]
```

The entry point exposes both a default export and a `./server` export, while `./schema.json` is bundled for configuration validation. The CLI is shipped under three alias names — `hecateq-openagent`, `oh-my-opencode`, and `oh-my-openagent` — all pointing at `bin/oh-my-opencode.js`, with platform-specific binaries provided as optional dependencies (`linux-x64`, `linux-x64-baseline`, `windows-x64`, `windows-x64-baseline`).

Source: [package.json](https://github.com/hecateq/hecateq-openagent/blob/main/package.json)

## Model Resolution and Capability Routing

At the heart of the pipeline is `model-core`, which exports the resolution surface used to pick the right model for each agent category. The barrel file in [`packages/model-core/src/index.ts`](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/index.ts) re-exports `model-requirements`, `model-resolver`, `model-capabilities`, `model-capability-heuristics`, `context-limit-resolver`, and related helpers such as `resolveModel`, `resolveModelWithFallback`, `normalizeFallbackModels`, and `flattenToFallbackModelStrings`.

Each agent role — including the Hecateq-specific `hecateq-planner` — has a `ModelRequirement` with a `fallbackChain`. The planner first tries `gpt-5.4` across `openai`/`github-copilot`/`opencode`/`vercel`, then `claude-sonnet-4-6` across `anthropic`/`github-copilot`/`opencode`/`vercel`, then `qwen3.7-plus` via `opencode-go`, `kimi-k2.6` via `opencode-go`/`vercel`, and finally `big-pickle` on `opencode`. Category-level requirements such as `visual-engineering` add a `variant` qualifier (`gemini-3.1-pro` with `variant: "high"`, `claude-opus-4-7` with `variant: "max"`), letting the pipeline tune reasoning effort per task type.

Source: [packages/model-core/src/model-requirements.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-requirements.ts)

When a model is invoked, `get-model-capabilities.ts` resolves its real capabilities through a layered lookup: runtime metadata first, then `ModelCapabilityOverride`, then the heuristic family registry, and finally the bundled snapshot. Every field is tagged with a diagnostic `source` (`"runtime" | "override" | "heuristic" | "snapshot" | "none"`), which is critical for the pipeline's self-healing posture — when a value comes from `"heuristic"` or `"unknown"`, downstream stages can flag uncertainty.

Source: [packages/model-core/src/model-capabilities/get-model-capabilities.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-capabilities/get-model-capabilities.ts)

The heuristic registry encodes which reasoning controls apply to which model family without requiring a live snapshot. `claude-opus` advertises variants `low|medium|high|max` with `supportsThinking: true`; `openai-reasoning` covers `o1/o3/o4` style identifiers with the standard reasoning-effort ladder; `gpt-5` adds `xhigh` and `max` efforts; and a `gpt-legacy` family captures everything else under the `gpt` prefix. This lets the orchestrator pick the correct `variant` argument for `ModelRequirement` lookups even when the provider's snapshot is missing.

Source: [packages/model-core/src/model-capability-heuristics.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-capability-heuristics.ts)

The capability record itself (`ModelCapabilities`) is the contract between the resolver and the executor. It carries `family`, `variants`, `reasoningEfforts`, `reasoning`, `supportsThinking`, `supportsTemperature`, `supportsTopP`, `maxOutputTokens`, `toolCall`, and `modalities`, together with a `diagnostics` block that traces the origin of every field. Inputs to the resolver are `providerID`, `modelID`, an optional `runtimeModel`, an optional `runtimeSnapshot`, a `bundledSnapshot`, and an optional `providerCache`.

Source: [packages/model-core/src/model-capabilities/types.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-capabilities/types.ts)

## Rules Engine and Tool Surface

The orchestration pipeline binds model selection to project context via the `rules-engine`. Rule sources are ordered by an explicit `SOURCE_PRIORITY` map: `.omo/rules` (0) wins over `.claude/rules` (1), `.cursor/rules` (2), `.github/instructions` (3), `.github/copilot-instructions.md` (4), and `.sisyphus/rules` (5). User-level directories are pushed to `100+` (`~/.omo/rules` → 100, `~/.opencode/rules` → 101, `~/.claude/rules` → 102), preventing global rules from silently overriding project policy. The loader walks project markers (`pyproject.toml`, `Cargo.toml`, `go.mod`, `.venv`, …), respects `EXCLUDED_DIRS` (`node_modules`, `.git`, `dist`, `build`, `.turbo`, `.next`, `coverage`), and recognizes filenames `AGENTS.md` plus `.instructions.md` patterns.

Source: [packages/rules-engine/src/constants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/rules-engine/src/constants.ts)

The orchestrator surfaces two MCP tool tiers to its agents. Tier 1, supplied by `lsp-tools-mcp`, exposes `lsp_diagnostics`, `lsp_goto_definition`, `lsp_find_references`, `lsp_symbols`, `lsp_prepare_rename`, `lsp_rename`, and `lsp_status`. The package's own README documents that downstream plugins (`codex-lsp`, `oh-my-openagent`) consume it as a git submodule so the runtime stays in one place. Language identification is driven by the extension table in `language-mappings.ts`, which maps `.ts/.tsx` to TypeScript, `.py/.pyi` to Python, `.rs` to Rust, and so on, with `makefile` (no extension) and `Rakefile`-style entries handled separately.

Source: [packages/lsp-tools-mcp/README.md](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/README.md)
Source: [packages/lsp-tools-mcp/src/lsp/language-mappings.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/src/lsp/language-mappings.ts)

Tier 2, supplied by `ast-grep-mcp`, exposes pattern-aware code search and rewrite. The MCP handler advertises `find` and `replace` tools with strict JSON Schema inputs (`pattern`, `lang`, optional `paths`/`globs`/`context`, and `rewrite` + `dryRun` for replace). Invalid requests are rejected with JSON-RPC error `-32600 Invalid Request`, ensuring the orchestrator cannot pass malformed tool calls into the agent loop.

Source: [packages/ast-grep-mcp/src/mcp.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/ast-grep-mcp/src/mcp.ts)

## Operational Notes and Common Failure Modes

| Symptom | Likely Cause | Where to Look |
|---------|--------------|---------------|
| Wrong model selected for a category | Stale `bundledSnapshot` overriding runtime | `model-capabilities/get-model-capabilities.ts` diagnostics `source` field |
| User rule silently overrides project rule | Missing entry in `SOURCE_PRIORITY` | `packages/rules-engine/src/constants.ts` |
| LSP tool misclassifies file language | Extension not present in mapping table | `packages/lsp-tools-mcp/src/lsp/language-mappings.ts` |
| AST-grep tool returns `-32600` | Malformed JSON-RPC payload from caller | `packages/ast-grep-mcp/src/mcp.ts` `errorResponse` branch |
| Native binary missing on install | `optionalDependencies` not satisfied on host | Platform packages in `package.json` `optionalDependencies` |

Source: [package.json](https://github.com/hecateq/hecateq-openagent/blob/main/package.json)
Source: [packages/model-core/src/model-capabilities/get-model-capabilities.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-capabilities/get-model-capabilities.ts)

The pipeline's "self-healing memory management" mentioned in the v0.1.0-hecateq.1 release notes is realized through `boulder-state`'s deterministic state model combined with the capability `diagnostics` block, which lets the orchestrator downgrade gracefully when a heuristic is used in place of a confirmed snapshot. "Robust validation safeguards" correspond to the strict JSON Schema on MCP tools and the Zod-backed configuration schema exported as `./schema.json`.

## See Also

- [package.json](https://github.com/hecateq/hecateq-openagent/blob/main/package.json) — workspaces, dependencies, and CLI aliases.
- [packages/model-core/src/index.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/index.ts) — barrel exports for the resolution pipeline.
- [packages/rules-engine/src/constants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/rules-engine/src/constants.ts) — rule source priorities and project markers.
- [packages/lsp-tools-mcp/README.md](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/README.md) — Tier-1 LSP tool inventory and downstream usage.

---

<a id='page-3'></a>

## Memory System and Context Injection

### Related Pages

Related topics: [Hecateq Orchestration Pipeline](#page-2), [CLI Commands and Doctor Diagnostics](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [packages/rules-engine/src/constants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/rules-engine/src/constants.ts)
- [packages/model-core/src/index.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/index.ts)
- [packages/model-core/src/model-resolution-types.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-resolution-types.ts)
- [packages/model-core/src/model-capability-heuristics.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-capability-heuristics.ts)
- [packages/model-core/src/known-variants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/known-variants.ts)
- [packages/lsp-tools-mcp/README.md](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/README.md)
- [packages/lsp-tools-mcp/src/tools.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/src/tools.ts)
</details>

# Memory System and Context Injection

## Overview

Hecateq OpenAgent is a customized fork of `oh-my-openagent` designed to operate inside the Hecateq agentic workflow engine within OpenCode. The v0.1.0-hecateq.1 release introduces "self-healing memory management" together with advanced task graph orchestration, but the repository exposes the supporting context-injection substrate through several distinct, well-bounded subsystems rather than a single monolithic memory module.

Three subsystems visible in the source tree contribute directly to how context is discovered, shaped, and routed into agent invocations:

| Subsystem | Package | Role in context injection |
|-----------|---------|---------------------------|
| Rules engine | `packages/rules-engine` | Discovers and prioritizes project/user rule files that augment agent prompts |
| Model core | `packages/model-core` | Resolves which model, variant, and capability set governs each request |
| LSP tools MCP | `packages/lsp-tools-mcp` | Provides live language-server context (diagnostics, symbols, references) |

Each subsystem is independently consumable, and together they form the practical "memory" layer that agents query at runtime.

## Rules Engine: Project and User Rule Discovery

The rules engine is the closest analogue to a memory bootstrap step because it walks the filesystem to discover what context an agent should inherit before any reasoning begins. Project markers, rule subdirectories, and source priorities are all defined as readonly constants so that every consumer agrees on ordering.

Source: [packages/rules-engine/src/constants.ts:3-5]()
- `PROJECT_MARKERS` enumerates the directory markers that identify a project root, including `.git`, `pyproject.toml`, `package.json`, `Cargo.toml`, `go.mod`, and `.venv`.

Source: [packages/rules-engine/src/constants.ts:7-13]()
- `PROJECT_RULE_SUBDIRS` lists the well-known subdirectories searched for rule files: `.omo/rules`, `.claude/rules`, `.cursor/rules`, `.github/instructions`, and `.sisyphus/rules`.
- `PROJECT_RULE_FILES` registers `.github/copilot-instructions.md` as a single-file rule source.
- `OPENCODE_USER_RULE_DIRS` adds `.omo/rules`, `.opencode/rules`, and `.sisyphus/rules` for user-scope rules.
- `RULE_EXTENSIONS` constrains loader behaviour to `.md` and `.mdc`.

Source: [packages/rules-engine/src/constants.ts:23-31]()
- `SOURCE_PRIORITY` assigns numeric precedence to each rule source. Project-scope sources occupy priorities 0–5, while user-scope sources occupy 100–103, ensuring that explicit project rules win ties over ambient user rules.

Excluded directories (`node_modules`, `.git`, `dist`, `build`, `.turbo`, `.next`, `coverage`) are pruned from traversal so that the rules walk does not waste I/O on build output. Source: [packages/rules-engine/src/constants.ts:17]()

## Model Core: Capability and Variant Context

While the rules engine decides *what text* enters the prompt, the model core decides *which model* consumes that prompt and which capability flags travel with the request. The package re-exports a single barrel that downstream agents import. Source: [packages/model-core/src/index.ts:1-50]()

```mermaid
flowchart LR
  A[Agent Request] --> B[Model Resolution Pipeline]
  B --> C{Available Models?}
  C -- yes --> D[Match Provider/Model]
  C -- no --> E[Apply Fallback Chain]
  D --> F[Apply Heuristic Capabilities]
  E --> F
  F --> G[DelegatedModelConfig]
  G --> H[Provider Call]
```

The core data contract is `DelegatedModelConfig`, which carries the resolved `providerID`, `modelID`, optional `variant`, `reasoningEffort`, `temperature`, `top_p`, `maxTokens`, and a `thinking` toggle. Source: [packages/model-core/src/model-resolution-types.ts:3-12]()

`ModelResolutionRequest` distinguishes three intent inputs — `uiSelectedModel`, `userModel`, and `categoryDefaultModel` — alongside an `availableModels` set constraint, while `ModelResolutionResult` tags the answer with a `provenance` of `"override" | "category-default" | "provider-fallback" | "system-default"`. This provenance acts as a small memory trace explaining *why* a particular model was chosen. Source: [packages/model-core/src/model-resolution-types.ts:14-39]()

When no override is available, heuristic families fill the capability gap. The registry encodes per-family patterns and aliases: for example, `gpt-5` declares variants `low`, `medium`, `high`, `xhigh` and reasoning efforts `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Source: [packages/model-core/src/model-capability-heuristics.ts:5-21]()

Canonical variant tokens are kept in a single readonly set so that the parser, fallback flattener, and capability resolver all agree on what counts as a known effort level. Source: [packages/model-core/src/known-variants.ts:1-13]()

```ts
export const KNOWN_VARIANTS = new Set([
  "low", "medium", "high", "xhigh", "max",
  "minimal", "none", "auto", "thinking",
])
```

## LSP Tools MCP: Live Language Context

The LSP tools package is registered as a Tier-1 stdio MCP server and exposes language-server queries as agent-callable tools, supplying the *dynamic* half of context injection (fresh editor state rather than static rules). Source: [packages/lsp-tools-mcp/README.md:1-15]()

The tool surface, defined through the `LspMcpTool` interface, standardizes execution, schema, and structured error reporting. Source: [packages/lsp-tools-mcp/src/tools.ts:11-19]()

| Tool | Purpose |
|------|---------|
| `lsp_diagnostics` | Pull compiler/linter errors filtered by severity |
| `lsp_goto_definition` | Resolve symbols to their declaration sites |
| `lsp_find_references` | Enumerate all uses of a symbol |
| `lsp_symbols` | List document or workspace symbols |
| `lsp_prepare_rename` / `lsp_rename` | Validate and execute symbol renames |
| `lsp_status` | Report which language servers are alive |

Diagnostic results carry `severity`, `mode` (file or directory), `totalDiagnostics`, and a `truncated` flag, plus a structured `errorKind` so an agent can decide whether to fall back to a different context provider. Source: [packages/lsp-tools-mcp/src/tools.ts:21-29]()

## Integration: Composing the Context Layer

At runtime, an agent turn in OpenCode typically composes context as follows:

1. The rules engine injects static markdown rules discovered under the priority ladder.
2. The model resolver picks a model and capability flags, recording provenance in the result.
3. The agent optionally invokes `lsp_*` tools to enrich the prompt with fresh diagnostics and symbol maps.

This decomposition keeps each concern testable in isolation — `packages/model-core/src/model-requirements.test.ts` validates fallback-chain ordering, while the LSP package ships its own `vitest` suite — and means that "self-healing memory" surfaced in the release notes can rely on a deterministic, contract-driven substrate rather than implicit globals.

## See Also

- [Rules Engine](rules-engine.md)
- [Model Resolution Pipeline](model-resolution.md)
- [LSP Tools MCP](lsp-tools-mcp.md)
- [Task Graph Orchestration](task-graph.md)

---

<a id='page-4'></a>

## CLI Commands and Doctor Diagnostics

### Related Pages

Related topics: [Hecateq Orchestration Pipeline](#page-2), [Memory System and Context Injection](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [package.json](https://github.com/hecateq/hecateq-openagent/blob/main/package.json)
- [packages/lsp-tools-mcp/README.md](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/README.md)
- [packages/lsp-tools-mcp/package.json](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/package.json)
- [packages/lsp-tools-mcp/src/lsp/language-mappings.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/src/lsp/language-mappings.ts)
- [packages/lsp-tools-mcp/src/lsp/types.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/src/lsp/types.ts)
- [packages/lsp-tools-mcp/src/tools.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/src/tools.ts)
- [packages/model-core/src/model-capabilities/get-model-capabilities.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-capabilities/get-model-capabilities.ts)
- [packages/model-core/src/model-capabilities/types.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-capabilities/types.ts)
- [packages/model-core/src/known-variants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/known-variants.ts)
- [packages/rules-engine/src/constants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/rules-engine/src/constants.ts)
</details>

# CLI Commands and Doctor Diagnostics

## Overview

Hecateq OpenAgent exposes its functionality through a layered set of command-line entry points and built-in diagnostic machinery. The root `package.json` declares an ESM-only CLI whose default export targets the OpenAgent plugin runtime, and it also wires up auxiliary build targets for a TypeScript Language Server Protocol (LSP) MCP server and a JSON Schema artifact (`hecateq-openagent.schema.json`). Source: [package.json](https://github.com/hecateq/hecateq-openagent/blob/main/package.json).

The CLI surface area is intentionally minimal at the top level: the package ships a `bin` entry for the LSP MCP runtime (a standalone `lsp-tools-mcp` binary) and exposes both the plugin entry (`./dist/index.js`) and a server entry (`./server`) for embedding. The `scripts` field defines a deterministic build pipeline that compiles the plugin, the LSP runtime, and the schema in a single command (`bun run build`). Source: [package.json](https://github.com/hecateq/hecateq-openagent/blob/main/package.json).

## LSP Tools MCP Command

The `lsp-tools-mcp` package is the user-facing CLI for LSP-backed code intelligence. It is published as a separate npm package (`@code-yeongyu/lsp-tools-mcp`) and is consumed by downstream plugins such as `oh-my-openagent` via a git submodule. Source: [packages/lsp-tools-mcp/README.md](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/README.md).

The CLI is a stdio-based Model Context Protocol (MCP) server. Its only supported subcommand is `mcp`, which starts the server and waits for JSON-RPC messages on stdin. Source: [packages/lsp-tools-mcp/README.md](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/README.md). The package's `bin` field maps the `lsp-tools-mcp` command to `./dist/cli.js`, and the `files` whitelist keeps the distribution minimal (only `dist/`, `LICENSE`, `NOTICE`, `README.md`, and `CHANGELOG.md`). Source: [packages/lsp-tools-mcp/package.json](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/package.json).

```mermaid
flowchart LR
    A[User Agent] -->|stdio JSON-RPC| B[lsp-tools-mcp CLI]
    B --> C[tools.ts handlers]
    C --> D[src/lsp runtime]
    D -->|spawn| E[Language Server]
    E --> D --> C --> A
```

The runtime maps a wide range of file extensions to canonical LSP language identifiers (e.g. `.ts` → `typescript`, `.py` → `python`, `.rs` → `rust`, `.tf` → `terraform`) via `getLanguageId`, ensuring the correct server is selected per document. Source: [packages/lsp-tools-mcp/src/lsp/language-mappings.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/src/lsp/language-mappings.ts).

### Exposed MCP Tools

The MCP server registers a fixed set of tool handlers, each with both a canonical name and an `lsp_*` alias for compatibility with downstream plugins. Source: [packages/lsp-tools-mcp/src/tools.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/src/tools.ts). The diagnostic-relevant tool is `lsp_diagnostics` (alias of `diagnostics`), which surfaces LSP `Diagnostic` records — `range`, optional `severity`, `code`, `source`, and `message` — as defined in the runtime type definitions. Source: [packages/lsp-tools-mcp/src/lsp/types.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/src/lsp/types.ts).

| Tool Name | Alias | Purpose |
|-----------|-------|---------|
| `goto_definition` | `lsp_goto_definition` | Resolve a symbol to its definition |
| `find_references` | `lsp_find_references` | Find references across the workspace |
| `symbols` | `lsp_symbols` | Document/workspace symbol search |
| `prepare_rename` | `lsp_prepare_rename` | Validate rename feasibility |
| `rename` | `lsp_rename` | Perform a workspace rename edit |
| `diagnostics` | `lsp_diagnostics` | Surface compiler/language diagnostics |

Source: [packages/lsp-tools-mcp/src/tools.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/src/tools.ts).

### Configuration and Path Overrides

By default the LSP client reads `.codex/lsp-client.json` for project-level configuration and `~/.codex/lsp-client.json` for user-level configuration. Two environment variables allow downstream consumers to redirect these paths — `LSP_TOOLS_MCP_PROJECT_CONFIG` and `LSP_TOOLS_MCP_USER_CONFIG`. The README documents that `oh-my-openagent` uses `LSP_TOOLS_MCP_PROJECT_CONFIG=.opencode/lsp.json` to integrate with OpenCode. Source: [packages/lsp-tools-mcp/README.md](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/README.md).

A minimal configuration file declares one LSP entry per language:

```json
{
  "lsp": {
    "typescript": {
      "command": ["typescript-language-server", "--stdio"],
      "extensions": [".ts", ".tsx", ".js", ".jsx"]
    }
  }
}
```

Source: [packages/lsp-tools-mcp/README.md](https://github.com/hecateq/hecateq-openagent/blob/main/packages/lsp-tools-mcp/README.md).

## Model Capabilities as a Doctor-Style Diagnostic

Hecateq OpenAgent treats model capability resolution as a transparent, multi-source diagnostic process. The `getModelCapabilities` function returns a `ModelCapabilities` record that, alongside each field, includes a `diagnostics` block enumerating the `source` of every resolved value — `runtime`, `override`, `heuristic`, `snapshot`, or `none`. Source: [packages/model-core/src/model-capabilities/get-model-capabilities.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-capabilities/get-model-capabilities.ts).

This design lets a "doctor" command or operator inspect why a given model behaved a certain way. For example, `variants.source` reports whether the list of supported variants came from runtime metadata, an explicit override, a heuristic family match, or was unavailable. The same applies to `reasoningEfforts`, `supportsThinking`, `supportsTemperature`, `supportsTopP`, and `maxOutputTokens`. Source: [packages/model-core/src/model-capabilities/get-model-capabilities.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-capabilities/get-model-capabilities.ts).

The shape of the override is fixed via `ModelCapabilityOverride`, allowing operators to pin `variants`, `reasoningEfforts`, `supportsThinking`, `supportsTemperature`, or `supportsTopP` to known-good values when the runtime is uncertain. Source: [packages/model-core/src/model-capabilities/types.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-capabilities/types.ts).

The set of canonical variant tokens that the resolver recognises is intentionally small and is shared between the parser and the flattener to keep agent-to-model mapping consistent. Source: [packages/model-core/src/known-variants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/known-variants.ts).

## Rule Discovery Constants

The `rules-engine` package encodes the search order and source priority for project rules, which is useful for diagnostic commands that want to report "which rules were loaded and from where". `SOURCE_PRIORITY` assigns a numeric weight to each rule source, with `~/.opencode/rules` ranking at priority `101` and `~/.claude/rules` at `102`, ensuring deterministic precedence when multiple sources define the same rule. Source: [packages/rules-engine/src/constants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/rules-engine/src/constants.ts).

`PROJECT_MARKERS` lists the files whose presence signals a project root (`.git`, `pyproject.toml`, `package.json`, `Cargo.toml`, `go.mod`, `.venv`), and `EXCLUDED_DIRS` enumerates directories that should never be traversed during rule discovery (`node_modules`, `.git`, `dist`, `build`, `.turbo`, `.next`, `coverage`). A doctor command can reuse these constants to explain why a particular rules file was or was not picked up. Source: [packages/rules-engine/src/constants.ts](https://github.com/hecateq/hecateq-openagent/blob/main/packages/rules-engine/src/constants.ts).

## See Also

- [Hecateq OpenAgent README and schema](https://github.com/hecateq/hecateq-openagent)
- [LSP Tools MCP upstream](https://github.com/code-yeongyu/lsp-tools-mcp)
- [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent) — downstream consumer of the LSP runtime
- [Model capabilities resolution](https://github.com/hecateq/hecateq-openagent/blob/main/packages/model-core/src/model-capabilities/get-model-capabilities.ts)
- [Rules engine constants](https://github.com/hecateq/hecateq-openagent/blob/main/packages/rules-engine/src/constants.ts)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: hecateq/hecateq-openagent

Summary: Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

## 1. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/hecateq/hecateq-openagent

## 2. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/hecateq/hecateq-openagent

## 3. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/hecateq/hecateq-openagent

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/hecateq/hecateq-openagent

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/hecateq/hecateq-openagent

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/hecateq/hecateq-openagent

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/hecateq/hecateq-openagent

<!-- canonical_name: hecateq/hecateq-openagent; human_manual_source: deepwiki_human_wiki -->