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:
extensions/vscode/local-agent-executors.jsextensions/vscode/utility.jsextensions/vscode/extension.jsorchestrator/routes/v1.py(free/coding local-execution package)gateway/providers_availability.pyandgateway/routes/models.py(provider/key availability)
Supported local executors
Current supported executor IDs:
claude_codegpt_codex
Display labels used by the extension:
Claude CodeGPT Codex
Execution preference model
Current normalized execution preferences
cloud_onlyprefer_local_agentlocal_agent_only(default ofclike.execution.defaultPreference)
Backward compatibility normalization
The extension normalizes legacy values:
prefer_claude_code→prefer_local_agentclaude_code_only→local_agent_onlyauto→cloud_onlyhybrid→prefer_local_agent
Executor selection model
Executor selection is resolved in this order:
- explicit executor in state, if any
- configured preferred executor
- available executor fallback order
Current fallback order adds both:
gpt_codexclaude_code
The extension checks:
- whether the executor is enabled
- whether the command exists on the machine
- whether the phase is supported
Current settings
Common local-agent settings
clike.localAgent.enabledclike.localAgent.preferredExecutorclike.localAgent.allowEvalclike.localAgent.restrictToKitPhasesclike.localAgent.timeoutMinutes
Timeouts
- A run uses the executor’s own timeout (
clike.claudeCode.timeoutMinutes,clike.localAgent.codex.timeoutMinutes) when you set it, otherwiseclike.localAgent.timeoutMinutes(default 30). A repair that re-runs eval checks gets extra time for each check it may run. - A timeout is a time budget, not a verdict. CLike stops the agent and checks the files it wrote: if the phase’s required outputs are there, the run continues like a finished one (orchestrator normalization, then eval decides the quality) and the chat says the agent timed out. If they are not, the error says so and names the setting to raise; the files stay on disk for the next run.
Model of the local agent
clike.claudeCode.model(defaultopus) andclike.localAgent.codex.modelare passed as--modelto every run, chat and Harper phases alike./agent-model listlists the models you can set: Codex’s from your Codex login, Claude Code’s aliases and catalog ids;(cloud too)marks those the cloud selector has as well. Agent and cloud models are chosen separately.- From the chat, in any mode:
/agent-modelshows the execution preference, the default agent and the models in use;/agent-model claude sonnet(oropus,haiku, an exact id) and/agent-model codex <model-id>change them (workspace settings). /agent-default claude|codex|autochooses which agent runs.
Claude Code settings
clike.claudeCode.enabledclike.claudeCode.commandclike.claudeCode.modelclike.claudeCode.printModeFlagclike.claudeCode.timeoutMinutesclike.claudeCode.permissionMode
GPT Codex settings
clike.localAgent.codex.enabledclike.localAgent.codex.commandclike.localAgent.codex.modelclike.localAgent.codex.sandboxModeclike.localAgent.codex.timeoutMinutes
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:
runs/kit/<REQ-ID>/src/**runs/kit/<REQ-ID>/test/**runs/kit/<REQ-ID>/ci/**runs/kit/<REQ-ID>/docs/**
Canonical workspace roots remain forbidden local-agent outputs:
src/**test/**tests/**docs/harper/**.git/**
/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:
/idea/spec/plan/kit/eval/finalize/extendand/idea --extend
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:
/idealocal agent writesdocs/harper/IDEA.md./speclocal agent writesdocs/harper/SPEC.md./planlocal agent writesdocs/harper/PLAN.mdanddocs/harper/plan.json(plusdocs/harper/lane-guides/<lane>.mdfor each detected lane).
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/):
runs/<phase>/docs/AGENT_<TITLE>_CONTEXT.json— the package the agent must treat as the source of truth (mission, required reads, allowed writes, attachment manifest).runs/<phase>/docs/AGENT_<TITLE>_PROMPT.md— the rendered execution prompt.runs/<phase>/attachments/<name>— one materialized copy per attachment.
Attachment rules:
- Multiple files are supported; each file up to 10 MB is inlined by the
extension and written to
runs/<phase>/attachments/. Files over 10 MB are referenced by path only and are not materialized (a warning is shown). - The attachment manifest (inside
AGENT_*_CONTEXT.jsonand the prompt) exposesname,workspace_path(the run-local copy the agent reads),original_path(metadata only — never read),mime, andsize. /idearequires at least one attachment;/specand/plando not.- PDF attachments are read for their text; image attachments are described via vision and used as evidence (native multimodal Read of the Claude Code executor; Codex support for images/PDF may be limited).
- Non-text binaries are excluded from RAG indexing; only their materialized copy reaches the agent.
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:
-
skill figma-fidelity— fidelity to the Figma source by mode (mcpattachment  none); governs design fidelity only. - skill
design-tokens-sync— Figma Variables → project tokens (advisory). - skill
journey-ui-states— explicit loading/empty/error/success states and accessibility (reused, not duplicated). - a UI design profile appropriate to the product (e.g.
startup-product-app,enterprise-console,developer-tooling-console,mobile-operator-app).
Figma source modes (work with both the Claude and Codex executors):
- mcp — remote Figma MCP at
https://mcp.figma.com/mcp: highest fidelity (node tree, Auto Layout, components, Variables). Configure it per local agent; a cloud KIT (one generation call) cannot query it and uses the attachment mode. - attachment — a Figma export attached to the request and materialized under
runs/<phase>/attachments/(HTML > PDF > image fidelity). - none — no Figma source: CLike still generates a coherent, accessible default-styled UI from the SPEC and records the applied style as an assumption.
Fallback / gating policy (from figma-fidelity):
- Missing Figma evidence does not block generation or promotion; default-styled
output is acceptable (the
nonemode is explicitly warn-only). - When a Figma source is provided, the gate blocks promotion if a page has no frame mapping or omits its frame’s primary components.
- Stack/quality checks come from the declared stack and reused FE skills: the declared
build/typecheck/lint must pass and every SPEC page REQ must have a page/view plus a
functional test (see
journey-ui-states).
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:
- base
kit - the acceptance-first stages (
clike.kit.acceptanceFirst): the acceptance stage writes onlytest/,ci/anddocs/ACCEPTANCE_<REQ>.md; the code stage implements against the locked tests - the auto-eval / auto-gate repair (
/eval REQ --fix,/gate REQ --fix): the package states the repair task, the failed checks (with their errors) and the rules in the prompt itself (repair_context.auto_evalin the context); the agent can re-run the failed checks in the real eval sandbox withnode .clike/bin/eval-check.mjs <check>…(served by the extension,clike.autoEval.agentEvalChecks), without the token or network access; the setup checks the LTC runs before the selected ones (dependencies, install, virtualenv) run with them - verify before finish: a base KIT (and the code stage of acceptance-first) runs all its checks in
the real eval sandbox before it finishes, with
node .clike/bin/eval-check.mjsand no arguments (databases, browsers and registry installs its own sandbox may lack; up toclike.kit.agentEvalChecksruns, 0 = off), and writesACCEPTANCE.jsonfrom that run, so the first eval passes instead of starting a repair. The full eval, with the regression, still decides.
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:
- local eval pre-pass when
clike.localAgent.allowEval=true
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)
- Invocation is read-only (Claude Code in print mode; Codex
exec). - Harper free text (Harper mode, not a slash command) is a conversation with
the agent that may also create files: the orchestrator returns a
harperpackage with anoutput_root(generated/<id>), the agent writes only there (same sandbox and approvals as Coding) and the chat shows the answer plus the files in the Files tab. The Harper artifacts change only through the phase commands. - The agent answer (stdout) is rendered as a normal chat bubble, badged with the
agent used —
agent-claudeoragent-codex— the way the cloud path shows the model name. - A short execution synthesis is shown in the Text panel.
Coding
- Invocation is write-capable; the agent writes the requested artifacts
(documentation, code, images, etc.) under
generated/<id>/in the workspace root, mirroring the cloud generation layout. - The chat bubble shows the agent badge plus the generated-file list; the files are already on disk and are clickable in the Files tab (no Apply step).
- Approvals (
clike.agentChat.approvals, defaultask): each edit and command waits for Allow / Allow all this turn / Deny in VS Code (closing the dialog denies); writes outsidegenerated/<id>/are denied without asking. Claude Code runs with--permission-mode defaultand--permission-prompt-tool, answered by a local MCP server that lives for one turn (http://localhost:<random port>, random token). Codex runs throughcodex app-server(workspace-writesandbox,untrustedapproval policy) and keeps the same session ascodex exec.auto: no questions (ClaudeacceptEdits, Codex sandbox).
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:
- Cloud providers (
openai,anthropic) are available when their API key env var is set to a non-empty value. - Local providers (
ollama, through its OpenAI-compatible API) are available when their base URL responds.
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:
- When at least one cloud key is configured, all Execution options are available
and
agent only(local_agent_only) is the default. - When no cloud key is configured, the cloud-dependent options are disabled and
only
agent onlyremains selectable.
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:
runs/kit/<REQ-ID>/docs/AGENT_EXECUTION_CONTEXT.json
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:
- requested phases
- required reads
- allowed write roots
- forbidden paths
- expected outputs
- generation rules
- project metadata
- repository root assumptions
For EVAL
The contract includes:
eval_contract- tools
- commands
- reports
- gate policy
- constraints applied
- evaluation rules
Local KIT prompt model
The extension builds a dedicated local KIT prompt that instructs the executor to:
- read
.clike/project.json - read plan and core Harper docs
- follow
AGENT_EXECUTION_CONTEXT.json - write only under candidate roots
- not modify canonical plan files
- not perform Git actions
- generate real source, tests, and docs
Required candidate outputs explicitly listed by the prompt:
runs/kit/<REQ-ID>/src/...runs/kit/<REQ-ID>/test/...runs/kit/<REQ-ID>/ci/LTC.jsonruns/kit/<REQ-ID>/ci/HOWTO.mdruns/kit/<REQ-ID>/ci/requirements.txtruns/kit/<REQ-ID>/docs/README_<REQ-ID>.mdruns/kit/<REQ-ID>/docs/KIT_<REQ-ID>.md
Local eval prompt model
The extension builds a dedicated local eval pre-pass prompt that instructs the executor to:
- read
LTC.json - read
AGENT_EXECUTION_CONTEXT.json - read
HOWTO.md - operate only inside candidate roots
- run checks and limited remediation
- avoid canonical workspace roots
- avoid Git operations
- return a concise stdout summary
Fallback behavior
If local-agent execution is requested but no suitable executor is available:
- the extension logs availability
local_agent_onlyfails hard- other compatible preferences fall back to the cloud path
If local KIT fails:
local_agent_onlyfails hard- otherwise the extension falls back to current CLike cloud path
If local eval pre-pass fails:
- canonical eval still runs unless the flow is explicitly blocked by
local_agent_only
What should be documented as current truth
Current truth
- Local agent execution exists
- GPT Codex and Claude Code are both supported
- Local-agent execution covers all Harper phases (
/idea,/spec,/plan,/kit,/eval,/finalize,/extend) - Standalone Free (Q&A) and Coding chat modes can run via the local agent
- EVAL pre-pass exists
AGENT_EXECUTION_CONTEXT.jsonis part of the Harper execution contract- Provider/key availability gates the model list and the Execution selector
Not stable enough to document as unrestricted capability
- local agents as canonical eval or gate authority