CLike VS Code Extension

CLike at a glance — what CLike does, area by area.
AI-native software engineering assistant for day-to-day coding and Harper-style solutioning inside VS Code. Works with the CLike Orchestrator and CLike Gateway across multiple providers and model families.
CLike is not just an agent that writes code; it is an AI-native platform that orchestrates verifiable capabilities across specs, plans, code, tests, reviews, and release gates.
Clike is
- Harper-governed
- RAG-grounded
- Eval-driven
- Human-in-the-loop
- Multi-model / agent-agnostic
- Cloud + local agent compatible
Install and first steps: docs/INSTALL.md · docs/GET_STARTED.md
What the extension does today
The extension currently supports three main interactive modes inside the chat panel:
- Free — general Q&A and contextual assistance (cloud or local agent).
- Coding — code generation and patch-oriented workflows with files, diffs, and apply flows (cloud or local agent).
- Harper — structured solutioning workflow built around:
IDEASPECPLANKITEVALGATEFINALIZE
It is designed to work with:
- OpenAI models
- Anthropic models
- Ollama / local backends
- other provider-routed models exposed by the Gateway
The extension is provider-aware, model-aware, and keeps a persistent chat timeline per model/history scope.
Current highlights
Chat modes
- Free
- general questions
- architecture discussion
- lightweight contextual assistance
- Coding
- generation results rendered in:
- Text
- Diffs
- Files
- hardened apply flow
- explicit file writing / patch review workflow
- generation results rendered in:
- Harper
- workspace-oriented delivery flow
- document-driven generation
- REQ-based implementation flow
- integration with SPEC / PLAN / plan.json / KIT candidates
Execution: cloud or local agent
Every chat mode can run via the cloud or via a local agent (Claude Code / Codex CLI), selected with the Execution preference in the chat header. There are three canonical modes:
cloud only— never use a local agent; always route to the Gateway/cloud.prefer agent— try a valid, available local agent first, then fall back to cloud if no local executor can run the request.agent only— use only an available local agent; never fall back to cloud (a clear, deterministic error is shown if none is available).
The default is prefer agent. Legacy values are normalized automatically at
runtime, so older persisted settings keep working: auto → cloud_only,
hybrid → prefer_local_agent, prefer_claude_code → prefer_local_agent,
claude_code_only → local_agent_only.
- Local-agent execution covers all Harper phases (
/idea,/spec,/plan,/kit,/eval,/finalize,/extend) as well as the standalone Free (Q&A) and Coding modes. - An installed Claude Code CLI is treated as a first-class local executor by
default (
clike.claudeCode.enableddefaults totrue); set it tofalseto disable Claude locally. Codex stays available when its CLI is installed. - Model selection per agent. On every local run CLike pins the model via the
CLI
--modelflag, usingclike.claudeCode.model(defaultopus) andclike.localAgent.codex.model(defaultgpt-5.5-codex). For Claude, tier aliases likeopus/sonnetalways resolve to the latest model of that tier; leave a setting empty to use the CLI’s own default. Codex exposes no model-list command, so set the exact model id your Codex login supports. - Model actually used is captured. Claude is invoked with
--output-format json, so CLike reads back the real model from the result envelope (also reflecting any fallback model); for Codex the used model is the one pinned via--model. The model is logged to the Clike output channel (model_used=…), shown in the live bubble badge (e.g.agent-claude · claude-opus-4-8), and persisted alongside the message. - In Free, the local agent answers read-only; a short execution synthesis appears in the Text panel and the answer is persisted in the per-model history (like the cloud path), so it survives reload.
- In Coding, the local agent writes the generated files under
generated/<id>/in the workspace root; the bubble shows the agent badge plus the file list, and the files are clickable in the Files tab. - Local agents authenticate through their own CLI session — no cloud API key is required or forwarded.
- Provider availability is computed at the Gateway from configured API keys: when no cloud key is set, the cloud Execution options are disabled and the model list hides cloud models; selecting a model whose provider key is missing surfaces a clear message in the Text panel.
Multi-model / multi-provider chat
The chat header supports:
- mode selection
- model selection
- history scope selection
- current model only
- all models
The extension preserves model selection better than older revisions and avoids unnecessary resets when reopening chat.
Bubble timeline
The chat keeps a persistent bubble timeline with:
- user messages
- assistant messages
- system messages
- timestamps
RAG support
The extension supports manual RAG flows:
- explicit indexing
- explicit search
- attaching RAG hits to the current conversation
Attachments
The chat supports:
- inline attachments
- RAG attachments
These are used across Free / Coding / Harper flows.
Layouts
clike.chat.theme (also the Layout selector in the chat):
cockpit(default): chat on the left, the project on the right (mode and execution, agent and model, methodology, release and phases, REQs, next action, last eval), a run card for the command in flightclassic,pro,studio,paper: the same features in a single column
What each area shows and the settings that change the UI: docs/chat-ui.md.
Quick start
1. Backend
Start the CLike stack (see the main README). The services listen on loopback and require a service token:
- Orchestrator:
http://localhost:8080 - Gateway:
http://localhost:8000
2. Extension
Install the packaged extension:
./build_ext_vs.sh # npm ci, lint, tests, vsce package, install
Open windows keep the version they loaded: reload them (“Developer: Reload Window”). A window still running the previous version says so at its next run, with a Reload Window button.
or develop it:
npm ci
npm run check # ESLint + node:test
then press F5 to launch an Extension Development Host.
3. Service token
Run CLike: Set Service Token and paste the CLIKE_API_TOKEN of the stack (stored in VS Code
SecretStorage, sent only to the configured orchestrator/gateway URLs). Then run
CLike: Chat (Q&A / Harper / Coding).
Defaults worth knowing
- Git automation (auto-commit, push, merge-on-gate, PRs) is off; enable it explicitly in the
clike.git.*settings. When on, only the files of each phase are committed. - The extension’s operational MCP server is off; when enabled it is token-protected (CLike: Copy Extension MCP Token).
- Untrusted workspaces are not supported; security-relevant settings are machine-scoped.
3. Use the chat header
Select:
- mode
- model
- history scope
Then start working in Free, Coding, or Harper mode.
Slash commands
Type commands directly in the chat input.
General
/help— shows the quick help overlay/status— shows current Harper/project context status/where— shows current workspace / doc-root path/switch <name|path>— switches to another Harper project
Harper workspace
/init <name> [--path <abs>] [--force]- initializes a Harper project/workspace scaffold
- creates core Harper files and support structure
/idea- formalizes or updates
IDEA.md
- formalizes or updates
/idea --extend [--from attachment] [--release vN] [--dry-run]- the next release of a delivered project: new requirements in
docs/inputs/vN/(background indocs/reference/vN/), plus any file you attach; withdocs/inputs/vN/empty an attachment is required. Merged into IDEA, SPEC and TECH_CONSTRAINTS - PLAN delta: new REQs typed
ADDED/MODIFIED(amends, supersedes) /REMOVED(retires); delivered REQs read-only; EXTEND report with CLike’s verification; baseline taggedharper/v<N-1> --methodology bmad --agent analyst|pm|architect|ux(defaultpm) guides the cascade- then
/kit,/eval --fix,/gatefor the new REQs and/finalize
- the next release of a delivered project: new requirements in
/spec [file|text]- generates or updates
SPEC.mdfrom IDEA/context
- generates or updates
/plan [spec_path]- generates or updates:
PLAN.mdplan.json- lane guides
- generates or updates:
KIT flow
The extension currently supports a base KIT run by default, plus optional explicit follow-up phases.
/kit- runs KIT on the next eligible REQ
/kit REQ-001- runs base KIT for the selected REQ
/kit REQ-001 --integrity- runs
integrity_eval
- runs
/kit REQ-001 --hardener- runs
promotion_hardener
- runs
/kit REQ-001 --promotion-eval- runs
promotion_eval
- runs
/kit REQ-001 --phases=kit,integrity_eval,promotion_hardener,promotion_eval- runs an explicit chained multi-phase KIT pipeline
Eval / Gate
/eval <REQ-ID>- evaluates the current KIT output for that REQ (plus, by default, the acceptance checks of the
promoted REQs:
clike.eval.regression)
- evaluates the current KIT output for that REQ (plus, by default, the acceptance checks of the
promoted REQs:
/eval <REQ-ID> --fix ["hint"]- auto-eval: on failure, asks for a KIT repair from the real failures and re-evaluates, up to
clike.autoEval.maxCycles(default 2); tests stay locked. Re-run to continue. Setclike.autoEval.afterKitto run it after every/kit. Seedocs/auto-eval.md
- auto-eval: on failure, asks for a KIT repair from the real failures and re-evaluates, up to
/gate <REQ-ID>- runs gate checks and promotion logic for that REQ
/gate <REQ-ID> --fix ["hint"]- auto-gate: on a failing gate, the same KIT repair as
/eval --fix(tests locked, same cycle limits), then a full gate again. The hint is optional: CLike adds its own diagnosis (failures that passed in earlier runs are flagged as nondeterministic) and writes what each repair received inruns/<eval|gate>/<REQ>/repair_<REQ>_<ts>.md. Seedocs/auto-eval.md
- auto-gate: on a failing gate, the same KIT repair as
/tools [search <text> | add <tool[@version]>… | remove <tool>…]- native tools of the eval sandbox (kcat, mysqldump, aws, kubectl, terraform, jdk@17…): CLike installs what an eval needs on its own, after asking (
clike.evalTools.install)./toolslists the catalog and what is installed (with versions),searchfinds an entry by name or program,addinstalls and approves for this project (.clike/eval-tools.yaml),update [tool…]rebuilds them at the latest versions and shows what changed (versions are otherwise locked; reminder after 30 days),removewithdraws the approval. A library of your language (psycopg, ojdbc…) goes in the project manifest instead. Seedocs/auto-eval.md
- native tools of the eval sandbox (kcat, mysqldump, aws, kubectl, terraform, jdk@17…): CLike installs what an eval needs on its own, after asking (
Finalization
/finalize- brings the promoted solution to running and configured: CLike installs, builds, configures, starts and smoke-checks it in the sandbox (the REQ tests are not run again: the gates did) and repairs it until it passes
- writes
docs/harper/FINALIZE_REPORT.md(how to start and see it, configuration, missing information, what changed and why), aREADME.mdmarked as a CLike project (badges and a Made with CLike section linked to the CLike repository) andscripts/setup_local/start_solution_local; then offers to configure and start it on your machine (Docker, Podman or native; a host port already taken is replaced by a free one in the local configuration)
RAG
/rag <query>- searches in RAG and shows top results
/rag +<N>- attaches result
Nfrom the last RAG search
- attaches result
/rag list- shows current attached files / RAG references
/rag clear- clears current attachments
/ragIndex [glob]- manually indexes content into RAG
- examples:
/ragIndex docs/**/*.md/ragIndex **/*
/ragSearch <query>- searches the RAG directly and returns top results
- CLike: Memory (đź§ Memory in the chat)
- a separate panel to query the project memory and the CLike guide in natural language, in any language, and list what each holds (docs/rag.md)
Current Harper behavior
/init
The workspace initializer creates the Harper scaffold and support files such as:
README.md.clike/.github/docs/harper/runs/
/plan
The plan flow is expected to produce promotion-grade planning artifacts, including:
docs/harper/PLAN.mddocs/harper/plan.json- lane guides under
docs/harper/lane-guides/
/kit
The extension supports REQ-based KIT execution and explicit KIT follow-up phases.
At the UX level, the current direction is:
- base KIT first
- additional phases only when explicitly requested
This keeps the extension compatible with more selective and cost-aware workflows.
Command Palette commands
The extension currently contributes these key VS Code commands.
Chat / core
- CLike: Chat (Q&A / Harper / Coding)
- CLike: Clear Chat Session (current model)
- CLike: Chat Session File (current model)
- Clike: Ping Service
- Clike: Check Services
- Clike: List Models (via Gateway)
Coding / patching
- Clike: Code Action…
- Clike: Add Docstring (AI via Orchestrator)
- Clike: Refactor (AI via Orchestrator)
- Clike: Generate Tests (AI via Orchestrator)
- Clike: Fix Errors (AI via Orchestrator)
- Clike: Apply Unified Diff (Hardened)
- Clike: Apply Unified Diff
- Clike: Apply New Content
- Clike: Apply Last Patch
RAG
- Clike: RAG Reindex (via Orchestrator)
- Clike: RAG Search (via Orchestrator)
Git / promotion
- Clike: Git Create Branch
- Clike: Git Commit Patch
- Clike: Git Open PR
- Clike: Git Smart PR
- CLike: Promote source code
- CLike: Quick Promote source code
Eval / governance
- CLike: Run All Evals
- CLike: Gate Check (Phase)
- CLike: Sync Constraints (IDEA/SPEC)
- CLike: Update PLAN Checklist from Eval
- CLike: Harper Init…
UI guide
Header
The chat header contains:
- mode selector
- model selector
- history scope selector
Prompt area
The prompt area supports:
- slash commands
- attachments
- help overlay
- Harper/Coding/Free workflows
Panels / tabs
Generation output is rendered through tabs:
- Text
- Diffs
- Files
Bubble timeline
The timeline keeps contextual continuity for each chat context and supports timestamped interaction traces.
Settings
Current configuration keys exposed by the extension include:
Chat / UI
clike.chat.theme- values:
cockpit(default)classicprostudiopaper
- values:
clike.chat.maxInMemoryMessages-
clike.agentChat.approvals clike.chat.persistDirclike.chat.never_send_source_to_cloudclike.chat.maxInMemoryMessagesclike.chat.autoWriteGeneratedFiles
Execution / local agent
clike.execution.defaultPreference- values:
cloud_only,prefer_local_agent,local_agent_only - default:
prefer_local_agent(legacyauto/hybridare normalized at runtime)
- values:
clike.localAgent.enabled-
clike.localAgent.preferredExecutor—autoclaude_codegpt_codex clike.claudeCode.enabled— defaulttrue; treat an installed Claude CLI as a local executorclike.claudeCode.command— defaultclaudeclike.claudeCode.model— defaultopus; model pinned on every Claude run (--model), chat and Harper phases. Tier aliases (opus/sonnet) always use the latest of that tier; empty = CLI default. Change it from the chat with/agent-model claude <model>clike.localAgent.codex.enabledclike.localAgent.codex.command— defaultcodexclike.localAgent.codex.model— defaultgpt-5.5-codex; model pinned on every Codex run (--model). Set the exact id your Codex login supports; empty = CLI default
Eval / gate / auto-eval
clike.eval.regression— defaulttrue;/evaland/gatealso re-run the acceptance checks of the promoted REQsclike.gate.strictWarnings— defaultfalse; warnings (failed non-blocking checks) block the gateclike.autoEval.maxCycles— default2; repair cycles of/eval REQ --fixand/gate REQ --fixclike.autoEval.afterKit— defaultfalse; run the auto-eval after every successful/kitclike.evalTools.install— defaultask; native tools an eval needs (environment.tools, programs the code runs, a check that stopped on a missing program):askbefore installing,alwaysfrom the catalog without asking,never. Tools in.clike/eval-tools.yamlinstall without askingclike.kit.acceptanceFirst— defaultfalse;/kitfirst writes and locks the acceptance tests (from SPEC/PLAN), then the code against them
Backend endpoints
clike.orchestratorUrlclike.gatewayUrl
Optimization / behavior
clike.optimizeFor- values:
latencycostcapability
- values:
clike.harperTimeout
Apply behavior
clike.apply.backupclike.apply.requireCleanGitclike.apply.dryRunPreview
Git integration
clike.git.autoCommitclike.git.gitMergeOnGateclike.git.gitDeleteBranchOnMergeclike.git.gitReturnToFeatureAfterMergeclike.git.remoteUrlclike.git.commitMessageclike.git.openPRclike.git.remoteclike.git.defaultBranchclike.git.conventionalCommitsclike.git.pushRebaseclike.git.branchPrefixclike.git.tagPrefixclike.git.prPerReqDraft.enabledclike.git.prPerReqDraft.useGhCliclike.git.prBodyPath
Routes
clike.routes- contains orchestrator and gateway route mapping overrides
Typical flows
Free mode
- ask questions
- attach small files inline
- use RAG for larger context
Coding mode
- ask for code / patches
- review output in Text / Diffs / Files
- apply only after inspection
Harper mode
Typical flow:
/init <name> [--path <abs>] [--force]- complete or refine
IDEA.md /spec/plan/kit REQ-XXX- optionally:
/kit REQ-XXX --integrity/kit REQ-XXX --hardener/kit REQ-XXX --promotion-eval- or explicit
--phases=...
/eval <REQ-ID>/gate <REQ-ID>/finalize
Troubleshooting
Chat opens but something looks stale
Reload the VS Code window and reopen chat, especially after source changes in development mode.
KIT target selection issues
If /kit REQ-XXX does not behave as expected, verify:
- slash parsing
- message bridge from webview to extension host
- REQ resolution logic in the extension
- plan state (
open,done, dependencies)
Provider/model issues
If a model/provider combination does not behave correctly:
- verify backend model catalog
- verify Gateway model availability
- verify routing configuration in backend settings
RAG issues
If manual RAG commands do not return expected results:
- verify orchestrator RAG endpoints
- re-index the relevant content
- check attached RAG references
Backend endpoints (reference)
Orchestrator
POST /v1/chatPOST /v1/generatePOST /v1/harper/specPOST /v1/harper/planPOST /v1/harper/kitPOST /v1/harper/evalPOST /v1/harper/gatePOST /v1/harper/finalizePOST /v1/rag/indexPOST /v1/rag/search
Gateway
GET /v1/models- provider/model routed chat-completion compatible endpoints
Current positioning
This extension is no longer just a simple chat panel.
Today it acts as a VS Code front-end for an AI-native software delivery workflow, combining:
- interactive chat
- coding assistance
- Harper document-driven delivery
- REQ-based KIT execution
- RAG-assisted context retrieval
- eval / gate flows
- git-aware promotion flows
Changelog summary for the current state
Compared with earlier simpler revisions, the extension now includes or exposes:
- the cockpit layout (project, phases, REQs, next action, run card) and the other layouts of the chat
- stronger multi-model / multi-provider awareness
- history scope handling in the chat UI
- persistent bubble timeline with timestamps
- manual RAG indexing and attachment workflows
- richer Harper slash commands
- explicit KIT follow-up phases
- promote / quick-promote command palette actions
- expanded git-oriented settings and promotion behavior
- more configurable apply / backup / dry-run behavior
- streamlined Execution model: only
cloud_only/prefer_local_agent/local_agent_only, with legacyauto/hybridnormalized at runtime - Claude Code enabled as a first-class local executor by default
- availability-aware local routing (no unrunnable Codex package;
prefer agentfalls back to cloud,agent onlyfails deterministically) - per-agent model selection via
--model(clike.claudeCode.model,clike.localAgent.codex.model) and capture of the model actually used - local-agent answers persisted in the per-model chat history (survive reload)
Repo
Part of the CLike project family:
- VS Code extension
- Orchestrator
- Gateway
Use together for the full workflow.