GET STARTED
A first project end to end with CLike, then the everyday features: the agent chat, auto-eval, acceptance-first, and CLike from Claude Code or Codex. Install first: INSTALL.
1. The chat and its three modes
Open CLike: Chat (Q&A / Harper / Coding).
| Mode | For | What happens |
|---|---|---|
| Free (Q&A) | questions about the project | answers only, nothing is written |
| Coding | quick code generation | files written under generated/<id>/ |
| Harper | the governed delivery process | IDEA → SPEC → PLAN → KIT → EVAL → GATE → FINALIZE |
Execution (selector in the chat): cloud (the model chosen in the model selector, through the
gateway) or agent (Claude Code / Codex on your machine). /agent-model shows what is in use.
Layout (clike.chat.theme, or the Layout selector in the chat): the default cockpit keeps
the chat on the left and, on the right, the mode, execution, models, agent, methodology (Harper or
BMAD with the role per phase) and the project — release progress, phases, REQs, the next action
with Run and ▶ Autopilot, the last eval. Beside the editor it becomes one column with the
cockpit in a drawer (☰). classic, pro, studio and paper have the same features. The whole
UI, area by area, with its picture: chat-ui.md.
Run card (every layout): while a command runs, a card above the chat shows its real steps
(KIT, EVAL 1, REPAIR 1, EVAL 2, GATE…) with their outcome, the cycle of a --fix loop, the time
and an estimate from the last time, the eval’s checks as they run in the sandbox (13/31 · now:
test:e2e, then the regression of the promoted REQs), what the agent is doing, the cost. The VS
Code status bar shows the same line. ⏸ After this step lets the current step finish (its report
is kept) and starts nothing new (for /autopilot: after the current kit / eval / gate, or after
this REQ); ⏹ Stop now (or Esc) first says what stopping now loses — a running eval leaves no
report, files an agent already wrote stay uncommitted — then stops. After a stop the card lists what
was done and offers the command to resume.
🧠 Memory (every layout, or CLike: Memory): a panel of its own next to the chat. Ask in natural language, in any language, what the project holds (Harper documents, REQ KITs, reports, attachments) or how CLike works (its documentation is there from the start); each result shows the lines that answer and opens the file. The two panels only open each other. See rag.md.
Conversations (every layout): + New chat starts a new conversation in the mode and keeps the previous one; in the cockpit, History lists them and reopens one with a click. What CLike says while a command runs is grouped in one card with the time of each message.
Autocompletion (every layout): type / — commands, then the REQs that fit the command, flags
and values; the command’s signature stays visible and an invalid command shows the parser’s error
with its fix before you send. Tab or ↵ inserts, Esc closes, ↑ in an empty prompt recalls the last
commands.
Talking to the agent directly
With execution = agent, the chat is a conversation with Claude Code or Codex:
- each mode keeps one agent session: the next message resumes it, so the agent remembers the
conversation (
/agent-sessionshows the sessions,/agent-session newstarts a fresh one); - the agent’s answer and the tools it uses (files read or edited, commands) appear live;
- Cancel stops the agent, and a running
/eval,/gateor--fixloop with it; any Harper phase (/kit,/spec,/plan,/finalize…), cloud or local agent, too: its response is discarded (nothing written, nothing committed), a stopped agent is not replaced by a cloud run, and the next step (auto-eval after a KIT, the/finalizeverification) does not start; files an agent wrote before the stop stay inruns/kit/<REQ>/, uncommitted. - Free is read-only (questions only). Coding and Harper free text let the agent also create
files, only under
generated/<id>/(e.g. in Harper: “create a script that computes N!”); the Harper artifacts (SPEC, PLAN, KIT, …) change only through the phase commands; - in Coding and Harper, every edit and command waits for your choice (Allow, Allow all this turn,
Deny) and writes outside
generated/are denied without asking. Claude Code asks through CLike, Codex runs throughcodex app-server.clike.agentChat.approvals = autoturns the questions off (edits undergenerated/then run without asking).
2. A first Harper project
The pilots in benchmark/projects/ (pingboard: backend only; shortlink: frontend + backend)
are small IDEAs to start with.
- Create a folder under
CLIKE_PROJECTS_DIR, open it in VS Code, chat in Harper mode. /init pingboard- Put the IDEA in
docs/harper/IDEA.md(its Technology Constraints block becomesTECH_CONSTRAINTS.yaml), or write it with/idea. /specthen/plan→docs/harper/SPEC.md,PLAN.md,plan.json(the REQs). Put requirement documents (docx, pdf, xlsx, pptx, md) indocs/inputs/and UI material (HTML prototypes, CSS, screenshots) indocs/harper/ux/: the phases read them as declared in.clike/context.yaml(context sources).- For each REQ:
/kit REQ-001 # code, tests, eval profile under runs/kit/REQ-001/ /eval REQ-001 --fix # canonical eval; on failure a governed repair, then eval again /gate REQ-001 # promotion decision; on PASS auto-merge into src/ and test/ + reportOr
/autopilot: the same three steps for every REQ, unattended (a REQ that needs you is parked and the others go on; after an interruption it resumes where it was; report inruns/autopilot/report.md). /finalizewhen the REQs are done: it does not run the REQs’ tests again (the gates did). It brings the solution to running and configured: CLike installs, builds, configures and starts it in the sandbox, checks that it answers and repairs it until it passes. Readdocs/harper/FINALIZE_REPORT.md(how to start and see it, configuration, what you still have to provide, what changed and why); CLike then offers to configure and start it on your machine (scripts/setup_local, thenscripts/start_solution_local; with Docker or Podman, or natively). A host port already taken on your machine is replaced by a free one in your local.env.- Next release. Put the new requirements in
docs/inputs/v2/(background, blueprints indocs/reference/v2/;v3/for the release after) and run/idea --extend— or attach them to the command (an attachment is required whendocs/inputs/v2/is empty; with files there you can still attach more, they add to them). CLike merges the release into IDEA, SPEC and TECH_CONSTRAINTS, adds the new REQs to the PLAN typedADDED,MODIFIED(changes a delivered REQ, naming the checks it replaces) orREMOVED, keeps every delivered REQ as it is, tags the delivered stateharper/v1and writesdocs/harper/EXTEND_<date>_<first>_<last>.md. Review it (--dry-runwrites only the report), then step 5 for each new REQ and step 6 at the end of the release.
/help lists every command; /status shows where you are.
3. What CLike guarantees
- Tests are locked at the first eval: a repair cannot weaken them. If a test is itself wrong (Python or JS/TS), the repair fixes the test (assertions unchanged) and the gate asks for your review.
- The test environment is created for you: sessions, ids, a disposable PostgreSQL database per
REQ and the services of other REQs (e.g. the API of REQ-001 for the integration tests of
REQ-002) are declared by the KIT and provisioned by CLike in the sandbox; you set only
CLIKE_EVAL_POSTGRES_URLand the values only you have indocker/eval.env(INSTALL §2). - Promotion never overwrites your changes: the gate merges file by file (base = what the KIT
started from); a file changed on both sides at the same lines is left untouched with a
.conflict-<REQ>-<ts>file next to it, and the REQ stays in progress until you resolve it;conflicts.mdin the promotion report shows each spot with its diff. - Regression: eval and gate also re-run the tests of the REQs already promoted.
- Sandbox: checks run in an isolated container without credentials.
- Audit: every amendment and override is recorded.
4. Options worth knowing
| Setting / command | Effect |
|---|---|
/eval REQ --accept "reason" |
accept, audited, a deliberate edit of the REQ’s locked tests or ci/LTC.json (nothing weakened) without a new /kit |
/eval REQ --fix ["hint"] |
auto-eval: up to clike.autoEval.maxCycles (2) governed repairs, plus clike.autoEval.extraCyclesOnProgress (3) while the failures decrease; rerun to continue, the hint guides the fix |
clike.autoEval.afterKit |
auto-eval after every /kit |
/autopilot [N], clike.autopilot.quotaWaitMinutes (30), clike.autopilot.quotaRetries (8) |
every REQ unattended (/kit → /eval --fix → /gate); parks a REQ that needs you, waits and retries on a provider quota; /autopilot stop, /autopilot status |
/tools, clike.evalTools.install (ask) |
native tools of the eval sandbox (kcat, mysqldump, aws, kubectl, jdk@17…): installed when an eval needs them, after asking; /tools add <tool>[@version] installs and approves for the project (.clike/eval-tools.yaml); /tools update or ./rebuild.sh --update-tools updates them (versions are otherwise locked) |
clike.kit.acceptanceFirst |
tests written from SPEC/PLAN and locked before the code |
clike.eval.regression (on) |
regression of promoted REQs in eval and gate |
clike.gate.strictWarnings |
warnings block the gate |
clike.gate.autoPromote (merge) |
how /gate promotes: merge auto-merge + report, ask strategy list, off; /gate REQ --auto-merge, --ask, --no-promote for one run |
clike.git.autoCommit |
commit every phase on feature/req-<n> — User settings only (CLike warns if it is in the project) |
/agent-default, /agent-model, /agent-session |
choose the agent, its model, its session |
clike.plan.capacityProfile (C2) |
REQ size by executor: C1 cloud single call, C2 agent vertical slice, C3 epic feature by feature |
CLike: Sync agent skills, clike.agentSkills.autoSync (on) |
the project’s skills as native skills of the local agents, CLike rules in the agent instruction files, eval guard hook |
clike.localAgent.resumeRepairs (on) |
an auto-eval repair resumes the agent session that wrote the KIT |
clike.localAgent.codex.reasoningEffort (high), clike.claudeCode.effort (CLI default) |
reasoning depth of the local agents on every Harper phase (low … xhigh, max for the second); empty = the agent CLI’s default |
Details: auto-eval · commands · local agents · quality and granularity · estimating with CLike.
5. CLike from Claude Code or Codex
After the MCP setup in INSTALL §6, ask your agent in plain words, for example:
Use the clike tools: list the REQs of /path/to/pingboard, then run the KIT of the next open REQ,
evaluate it with fix=true and run the gate. Report the outcome of each step.
The operational tools (harper_run_phase, eval_run, gate_check, harper_run_status) run inside
VS Code through CLike’s normal flow: same test lock, gate and write rules as the chat. Long phases
return status: running and a run_id to poll; eval_run with fix returns the final report after
the repairs. Overrides, promotion and git are not exposed. Codex: approve the CLike tools once
(INSTALL §6) or each call asks.
6. See what happened
- Chat and the Files / Text tabs for each run.
- Telemetry portal
http://127.0.0.1:8000/v1/metrics/harper/ui: tokens (cached ones included), cost, model per phase, cloud and agent runs (agent cost is the API-equivalent cost). - Promotion reports
runs/kit/<REQ>/promotion/<ts>/report.md(per-file outcome) andpromotion.diff. - Reports under
runs/eval,runs/gateand the KIT folders.
7. Troubleshooting
| Symptom | Fix |
|---|---|
The eval report warns env::disk-space |
the eval volume is short of space even after CLike removed the project’s other eval work directories: free space (other projects’ evals on the volume) or enlarge the VM disk (podman machine set --disk-size), lower CLIKE_EVAL_MIN_FREE_GB only if you know the evals fit |
An eval ends with EVAL ERROR … eval sandbox unavailable: ReadTimeout |
the eval lasted longer than the orchestrator’s wait for the sandbox (one hour before 1.9.4, six hours now: CLIKE_EVAL_SANDBOX_TIMEOUT_S); a long regression also needs clike.harperTimeout (minutes) above its duration. Run the eval again |
Eval checks time out and the report says Sandbox resources exhausted (… memory …) |
the eval sandbox is out of memory: raise CLIKE_EVAL_SANDBOX_MEM_LIMIT (docker/.env) and the container VM memory (podman machine set --memory 16384), or CLIKE_EVAL_REGRESSION_WORKERS=1; restart the services |
| Eval returns 503 or the orchestrator restarts | container VM memory too low: raise it (INSTALL §1), lower CLIKE_EVAL_SANDBOX_MEM_LIMIT |
| “No local agent is available” | install/log in claude or codex, or switch execution to cloud |
| An answer from the agent seems to forget the conversation | /agent-session — a failed resume starts a new session |
| Browser (Playwright) checks are slow the first time | Chromium is downloaded on first use in the sandbox |
EVAL BLOCKED — missing in docker/eval.env |
set the named value in docker/eval.env and rebuild; EVAL BLOCKED — CLike cannot create yet → /eval REQ --fix declares it |
| Gate PASS but the REQ stays in progress | the promotion left conflicts: read conflicts.md in the promotion report, resolve the .conflict-… files, /gate again |
Phases not committed although autoCommit is on |
it is set in the project settings: apply it in User settings (CLike shows a warning) |