Skip to the content.

Local Agents

Overview

The current extension supports a local-agent execution path for compatible Harper flows and for the standalone CLike chat modes (Free Q&A and Coding). Across all CLike modes, a request can run via the local agent (Claude Code / Codex CLI) instead of the cloud, governed by the Execution preference.

This path is implemented in:

Supported local executors

Current supported executor IDs:

Display labels used by the extension:

Execution preference model

Current normalized execution preferences

Backward compatibility normalization

The extension normalizes legacy values:

Executor selection model

Executor selection is resolved in this order:

  1. explicit executor in state, if any
  2. configured preferred executor
  3. available executor fallback order

Current fallback order adds both:

The extension checks:

Current settings

Common local-agent settings

Timeouts

Model of the local agent

Claude Code settings

GPT Codex settings

clike.localAgent.codex.sandboxMode defaults to auto. In auto, CLike launches Codex with --sandbox workspace-write for every Harper phase (they all write files) and for Coding, and --sandbox read-only for Free (Q&A) chat. The supported explicit values are read-only, workspace-write, and danger-full-access; an explicit read-only is rejected for Harper phases (see below). Harper phases also pass --skip-git-repo-check, so they work in a project that is not a git repository yet.

The configured model is checked before the agent starts: clike.localAgent.codex.model against the models of the Codex login (~/.codex/models_cache.json), clike.claudeCode.model against the Claude aliases and claude-* ids. An invalid id blocks the run with LOCAL_AGENT_MODEL_INVALID and the closest valid id. A failed run reports LOCAL_AGENT_EXITED_WITH_ERROR with the agent’s own error message. An agent that exits with an error after writing files (the model at capacity, a rate limit, a crash mid-run) is LOCAL_AGENT_INTERRUPTED: its files stay on disk but the phase has no result, nothing is committed or evaluated; run the phase again to complete it. Claude Code’s failed run is read from its result (is_error), Codex’s from its exit code and turn.failed. Under /autopilot a model at capacity waits and retries like a rate limit.

Whoever writes it (cloud model, Codex, Claude Code), a KIT without runs/kit/<REQ>/ci/LTC.json is incomplete (KIT_INCOMPLETE, or LOCAL_AGENT_REQUIRED_OUTPUTS_MISSING for an agent): ci/ also holds files CLike writes itself, so the directory alone does not prove the eval profile is there.

Codex write mode

Every Harper local-agent run (document phases, EXTEND, KIT, eval repair/hardening, finalize) is a write-required task. CLike must not launch Codex for those phases in read-only mode because the agent is expected to create or patch controlled candidate artifacts.

For /kit, Codex may write only inside the CLike candidate tree for the active REQ:

Canonical workspace roots remain forbidden local-agent outputs:

/finalize writes the integrated solution instead: inside the write roots of its package (src/, scripts/, docs/harper/, root manifests, ci/SOLUTION_LTC.json, …), never test/, tests/, runs/, .git or a path the package forbids (.env, caches).

If the selected Codex sandbox mode is not write-capable for a write-required phase, CLike aborts before launching Codex with LOCAL_AGENT_WRITE_MODE_UNAVAILABLE. The diagnostic includes the phase, REQ, executor, selected sandbox, and allowed write roots. This is intentionally a fail-fast condition; a read-only Codex launch cannot produce a valid KIT candidate.

After Codex exits, CLike validates the collected candidate artifacts before submitting them to /local-agent/complete. For KIT, a result that contains only the local-agent input package under runs/kit/<REQ-ID>/docs/** is rejected with LOCAL_AGENT_REQUIRED_OUTPUTS_MISSING. At minimum, the candidate must include readable artifacts under the required src, test, and ci KIT roots unless a future active contract explicitly marks those output families as unsupported.

To diagnose a read-only launch, inspect the extension output line that starts with [CLike] [local-agent:gpt_codex]. A valid write-required Codex KIT launch shows an argument list containing --sandbox and workspace-write.

Current phase support

Execution-agent (local-agent) support now covers the early Harper document phases as well as the existing actuator phases:

All phases share the same architecture: orchestrator execution policy, run_phase dispatch, the local-agent package envelope, the /local-agent/complete normalization step, the extension actuator, and the phase-aware write policy. Cloud and local execution remain semantically equivalent; CLike governance stays canonical and validates every result. The agent performs bounded work; CLike validates and governs.

Early document phases (/idea, /spec, /plan)

These phases produce only their canonical Harper documents. The write policy is narrow:

docs/harper/ remains protected: any other docs/harper/ path (except the BMAD companion documents of the selected BMAD agent), and all of src/, test/, tests/, and .git/, stay forbidden for these phases. Methodology/BMAD context is passed through when enabled, but BMAD is never mandatory and the canonical Harper outputs above are always required.

The project context sources (.clike/context.yaml, see context-sources.md) reach the agent as a list of files to read in place; office and PDF documents are converted to text under runs/context/<phase>/.

EXTEND (/extend, /idea --extend)

The agent may write docs/harper/IDEA.md, SPEC.md, PLAN.md, plan.json, lane guides and the dated docs/harper/EXTEND_<date>_<first>_<last>.md report; TECH_CONSTRAINTS.yaml only in the release cascade (/idea --extend, by addition). The extension then checks the result: existing REQs are restored if changed, IDEA/SPEC sections of the earlier release are restored if dropped, the delta rules (ADDED/MODIFIED/REMOVED, release, amends/supersedes/retires) are verified, and a CLike verification section is appended to the EXTEND report. /extend gets TECH_CONSTRAINTS.yaml restored.

Attachments and run tracking

For document phases the orchestrator materializes the current-run attachments into a workspace-local, run-scoped folder so the agent reads them from its cwd without any external-path Read approval. Everything is tracked under runs/<phase>/ (e.g. runs/idea/):

Attachment rules:

Frontend from Figma (framework-agnostic)

CLike can generate a web frontend from Harper SPEC pages and an optional Figma design. The model is intentionally stack-neutral: the concrete framework (React, Next.js, Angular, Svelte/SvelteKit, Vue, or plain HTML) comes from docs/harper/TECH_CONSTRAINTS.yaml (project_definition.framework, technology_stack.*), not from the capabilities.

Capabilities are shipped by /init from the template under .clike/{skills,packs,design-profiles} and composed per FE REQ in /plan:

Figma source modes (work with both the Claude and Codex executors):

Fallback / gating policy (from figma-fidelity):

Typical flow: declare the stack in TECH_CONSTRAINTS.yaml → reference the Figma (MCP link or export) in /idea → declare page functionalities in /spec → bind a UI design profile + figma-fidelity + journey-ui-states (+ design-tokens-sync) per FE REQ in /plan → generate sources in /kit → verify in /eval and /gate.

KIT

Both local executors currently support:

Governance with agents: the agent writes directly, so the extension snapshots test/ and ci/ before a repair or a code-only KIT, submits what changed to POST /v1/acceptance/amend and restores what is rejected (and any deleted file), before the phase commit. Safe mechanical lint fixes (e.g. import order) computed by the orchestrator come back as format_fixes and are written before the first eval.

Every KIT prompt ends with an eval-readiness self-check (checks the LTC runs, files asserted by tests, behaviour over internals, real library APIs, time-bounded tests, read-only project root).

Telemetry of agent runs

Claude Code runs with --output-format stream-json --verbose, Codex with --json: both stream events, so the chat’s run card shows what the agent is doing (the tool it uses, the file it edits, the command it runs) while it works. For Claude, CLike keeps only the final result event of the stream as the run’s output — the same envelope --output-format json prints — so the checks of a blocked, failed or interrupted run never read the tools’ outputs. CLike records usage, the API-equivalent cost (subscription runs are not billed per token), the model, the number of turns and the duration, in .clike/telemetry/ and in the gateway telemetry portal (execution: local_agent), and adds them to the cost of the run and of the session in the chat. The eval pre-pass is recorded too.

EVAL

Both local executors can participate in:

Follow-up KIT phases

clike.localAgent.restrictToKitPhases and clike.claudeCode.restrictToKitPhases are still declared and read, but no phase is currently restricted by them. Follow-up KIT stages work on the current candidate: once the tests are locked, their changes to test/ and ci/ are governed like a repair.

The eval verdict is never the agent’s: /eval and /gate always end with the canonical eval in the CLike sandbox.

Standalone Free (Q&A) and Coding local execution

Beyond the Harper pipeline, the local agent also serves the standalone CLike chat modes. These flows are intentionally separate from the Harper machinery: there is no REQ binding, no runs/kit/<REQ-ID>/ tree, and no Harper output validation.

The architecture mirrors Harper: the orchestrator (/v1/chat and /v1/generate) assembles the prompt and context and returns a local-execution package ({ local_execution: true, mode, prompt, executor_hint, output_root? }) instead of calling the gateway; the extension is the only component that spawns the CLI.

Free chat (Q&A)

Coding

Authentication

Local agents authenticate through their own CLI session. No cloud API key is required or forwarded for the local path; cloud provider keys are stripped from the spawned process environment by default.

Provider availability and executor gating

Provider availability is computed once at the gateway, which is the only process that holds the cloud API keys:

GET /v1/providers exposes this snapshot and GET /v1/models annotates each model with available / unavailable_reason. The orchestrator hides models whose provider is unavailable and forwards the providers summary to the extension.

The extension uses this to gate the Execution selector:

Profile/routing resolution is unchanged. If a request resolves to a provider whose key is not configured (for example, an OpenAI model while only an Anthropic key is set), the orchestrator returns a clean message that the extension renders in the chat Text panel instead of letting the gateway raise a raw 401.

AGENT_EXECUTION_CONTEXT.json

Before invoking a local agent, the extension writes:

This file is the primary local execution contract.

Content the package also writes as its own file is referenced by path instead of repeated (context_envelope.clike_capabilities.context_markdown_path / context_json_path, file_requirements.path): the agent re-reads its context on every turn.

For KIT

The contract includes:

For EVAL

The contract includes:

Local KIT prompt model

The extension builds a dedicated local KIT prompt that instructs the executor to:

Required candidate outputs explicitly listed by the prompt:

Local eval prompt model

The extension builds a dedicated local eval pre-pass prompt that instructs the executor to:

Fallback behavior

If local-agent execution is requested but no suitable executor is available:

If local KIT fails:

If local eval pre-pass fails:

What should be documented as current truth

Current truth

Not stable enough to document as unrestricted capability