Harness Intelligence Wiki
SpecsCLICodex TypeScript MCP

Codex TypeScript MCP: implementation notes

Codex TypeScript MCP implementation notes

Branch spec/codex-typescript-mcp, PR #243. Backlog: Linear Epic IP-476 (Tasks IP-480 to IP-484). The same branch also fixes GitHub issues #239, #240, #241 and #242.

What changed

  • Registry:
    • New item typegraph-runtime (kind: "tools", no files). Its meta.hi.toolRuntime carries the exact manifest and lockfile from apps/cli/src/data/tool-runtimes/typegraph-mcp/.
    • pack-typescript depends on it, so the TypeScript Pack is the only selector.
    • Pack meta also publishes promptSurfaces (#241).
  • CLI modules in apps/cli/src/features/typescript-semantic-reads/:
    • runtime.ts: pinned install with reuse, a receipt and an atomic swap.
    • probe.ts: load probe through Typegraph's ApiClient.
    • discovery.ts: finds tsconfigs via git, with the wiki excluded, solution-only configs excluded, nested configs reported as ambiguous, and a settings override.
    • codex-config.ts: the fenced # BEGIN hi typegraph block.
    • sync.ts: runs the update step and provides the shared check helpers.
  • Pipeline: new step semantic-reads after the Installed Record in registry/pipeline.ts. UpdateReport.semanticReads reports it, and lifecycle output renders it.
  • Settings: override typescript.compilerProjects. XDG_DATA_HOME was added to the command-environment allowlist.
  • hi check: new semanticReads output with runtime, registered and compilerProjects, printed as three human lines. Probes share a 30 s budget so the SessionStart hook stays under its 45 s timeout.
  • Built handoff: a section that appears only with the TypeScript Pack. It covers the five reads and says a new Codex session is needed after a tsconfig, dependency or branch change.
  • Docs and release: Codex TypeScript semantic reads runbook, the scaffolding runbook (hi update step, hi check fields, Pack routing, #239/#240), Scaffold Pack, and the docs index. CLI 6.1.0 in CHANGELOG.md; BASELINE_CHANGELOG.md Unreleased with Compatibility: >=6.1.0 <7.0.0, so the release is mixed.
  • Issue fixes:
    • #239: hi tools ensure passes the command environment, and the runtime is now required.
    • #240: the operator skill's compatibility range follows the running CLI major.
    • #241: surface Packs are gated per workspace, and default Packs are routed by promptSurfaces.
    • #242: detection skips git-ignored paths, and the docs prompt spec is written only when docs/ exists (new RecordedShape.docsRoot).

Decisions made during delivery

  • Approval value: default_tools_approval_mode = "approve".
    • codex-cli 0.156.1 exec completed the reads under approve, prompt and unset alike, with the global policy approval_policy = "never".
    • Vendor docs describe approve as "execute without user intervention".
    • Prompting in the interactive desktop app is not observable on this headless host, so it is recorded as a limitation (AC-021, AC-023).
  • Lock identity: the pinned lock was regenerated on Linux on 2026-09-28. It resolves the tested dependency set (Typegraph 0.9.56, TypeScript 7.0.2, @effect/tsgo 0.36.5, MCP SDK 1.30.1).
    • Its SHA-256 is 279b63b811c1466fd46b036067591f4f2863ebdcfc6868440ee96600a0ee9e5d. The macOS spike lock was 3bcfab52….
    • AC-003 is about this set of versions, which matches.
    • The repository stores no digest. The receipt records the hash at install time.
  • Launch command: sh -c 'TYPEGRAPH_PROJECT_ROOT="$(git rev-parse --show-toplevel)" exec node "${XDG_DATA_HOME:-$HOME/.local/share}/hi-tools/typegraph-mcp/<version>/…/server.cjs"'.
    • The committed Codex file stays portable because it contains no absolute home path.
    • Windows needs sh on PATH. There is no per-platform matrix (Q19).
  • CLI compatibility: the new Baseline needs CLI ≥ 6.1.0, set on the BASELINE_CHANGELOG.md Compatibility: line.
    • Older CLIs would record no docsRoot and would drop the docs prompt spec.
    • They would also ignore toolRuntime silently.

Acceptance evidence (2026-09-28)

Live runs used a local Registry built from the working tree (registry:build, 171 items, served over file://) and CLI source (bun run apps/cli/src/index.ts). Both ran in disposable worktrees of this repository at 30cfcc0e5, with no changes to this checkout's managed files. Environment: Linux x86_64, Node 24.19.0, codex-cli 0.156.1.

ACResultEvidence
AC-001passhi update with the TypeScript Pack selected: semanticReads.runtime.status = installed, codexConfig = written. No extra setting.
AC-002passNo Pack means no runtime call and no table. Covered by pipeline.test.ts, and live on deselection (below).
AC-003pass~/.local/share/hi-tools/typegraph-mcp/0.9.56/package-lock.json resolves typegraph-mcp 0.9.56, typescript 7.0.2, @effect/tsgo 0.36.5, @modelcontextprotocol/sdk 1.30.1.
AC-004, AC-011passsha256sum -c of all 105 tracked package.json, bun.lock, tsconfig* and oxlint files is unchanged after the install and update.
AC-005pass (test)pipeline.test.ts and runtime.test.ts: Node below 22.18 or a missing npm gives unavailable plus a reason, and no block. Status stays applied.
AC-006passSecond hi update: runtime.status = reused. Inode and mtime of the runtime dir, receipt and node_modules are unchanged.
AC-007passAfter deselecting the Pack, the runtime dir still exists.
AC-008pass10 projects: apps/api, backoffice, cli, web and packages auth, contract, db, env, scaffold, ui. The root is excluded as solution-only.
AC-009passapps/wiki/tsconfig.json is excluded as wiki.
AC-010pass (test)pipeline.test.ts and discovery.test.ts: nested configs are reported as ambiguous and get no entry; the settings override resolves them.
AC-012, AC-013passAll 10 probes pass live (82, 78, 225, 14, 26, 8, 17, 4, 8 and 14 files). The failure path and its reason are covered by pipeline.test.ts and check.test.ts.
AC-014passThe workspaces declare TypeScript catalog: / ^6.0.2, not 7.0.2, and all 10 activate.
AC-015passExactly 10 [mcp_servers.typegraph_*] tables.
AC-016passBytes outside the block are identical to the pre-update file, and the original bytes are a prefix of the new file.
AC-017passAfter editing all 10 tables by hand (tool_timeout_sec, adding ts_hover), the next update restored the file byte-identically. A third run reported unchanged.
AC-018passDeselection gives codexConfig = removed, and .codex/config.toml equals the committed bytes.
AC-019passParallel Codex sessions in worktrees A and B: ts_definition(commandRegistry) → command-registry.ts:248 in A and :251 in B, where 3 lines were prepended.
AC-020passcodex mcp get typegraph_apps_cli --json shows enabled_tools as the five reads. The session lists only those five for the server.
AC-021pass with limitationEvery call completed with no prompt in codex exec under the host default. Interactive desktop behavior was not observed.
AC-022passNo approval_policy in the generated file. hi never writes ~/.codex/config.toml.
AC-023passThe runbook states the desktop-prompt limitation.
AC-024passhi check --json: runtime.installed = true, registered.count = 10, and each of the 10 projects has probe: pass, registered: true. It took 2.4 s.
AC-025passAfter removing the block: status = current, installed = true, registered = 0.
AC-026passHuman output has three separate lines: Typegraph runtime: installed 0.9.56 (…), Codex entries: 10 registered, Compiler projects: 10 pass, 0 fail.
AC-027passNew Codex session: typegraph_apps_cli ts_definition(apps/cli/src/index.ts, commandRegistry) → apps/cli/src/cli/command-registry.ts:248.
AC-028passts_type_info(HarnessReportType) returns "bug" | "docs" | "other" | "tooling" | "workflow" on both typegraph_packages_contract and typegraph_apps_cli.
AC-029passIn the same session, fixtureResult changed from string to number after Codex edited the imported fixtureValue return type through the shell.
AC-030passThe Built handoff section and the runbook both state the new-session requirement.
AC-031passhi update and hi check leave no process behind. After the sessions ended, 0 Typegraph server processes were running.
AC-032recordedSee the measurements below.

Session cost (AC-032, per-project topology, no threshold)

  • Exposed tools: 10 servers × 5 reads = 50. Each server advertises 22 tools before enabled_tools filters them.
  • Startup: each server was ready (MCP initialize plus tools/list) in 493–745 ms, with all 10 started in parallel. That is under Codex's default mcp_optional_startup_grace_ms of 1000 ms. All 10 server processes appeared within about 1 s of codex exec starting.
  • Resident memory (RSS of Typegraph and tsgo processes under the Codex process tree):
    • Idle, 10 servers: about 0.93 GB.
    • Peak, with 1 native TypeScript child started by a query: about 1.37 GB.
    • After the query settled: about 0.54 GB.
  • Whole session: a single-query session took about 21 s end to end, mostly model time.

Rule evaluation

  • HI-CLI-001 pass: the install is machine-local, uses no credentials, and makes no remote platform call.
  • HI-CLI-002 pass: the version bump and CHANGELOG.md notes are in this delivery.
  • HI-CLI-003 pass: code is in apps/cli/src/features, data in apps/cli/src/data.
  • HI-CLI-004 pass: content ships only as Registry Items, and no digest is stored.
  • HI-DOCS-001, HI-WIKI-001 and HI-WIKI-003 pass: see the docs changes.
  • HI-REPO-004 not applicable: no shared skill source was edited.

Known limits and follow-ups

  • Interactive Codex desktop approval behavior is unverified on this host (AC-021, AC-023).
  • A tsconfig, dependency or branch change needs a new Codex session (Q17).
  • Old Tool Runtime versions are never pruned (Q20).
  • #241: apps/wiki still has no scoped spec listing the planning skills. It is not a workspace, and the docs spec now needs docs/. This needs a separate decision.
  • #242: stale Software Scopes stay in settings; hi update neither edits nor reports them (remove by hand).
  • Pre-existing, not introduced here: commit 30cfcc0e5 on this branch also added 496 .devpunks/pre-existing-skills/*.backup files, a rewritten .githooks/pre-commit, and 8 stray apps/cli files. One of them, validation-cache/cache.test.ts, imports a missing module, so check-types fails. They are left untouched pending the owner's decision.

Codex TypeScript MCP: execution plan

Previous Page

Codex TypeScript MCP

Next Page

On this page

Codex TypeScript MCP implementation notesWhat changedDecisions made during deliveryAcceptance evidence (2026-09-28)Session cost (AC-032, per-project topology, no threshold)Rule evaluationKnown limits and follow-ups