Skip to the content.

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:

2. A first Harper project

The pilots in benchmark/projects/ (pingboard: backend only; shortlink: frontend + backend) are small IDEAs to start with.

  1. Create a folder under CLIKE_PROJECTS_DIR, open it in VS Code, chat in Harper mode.
  2. /init pingboard
  3. Put the IDEA in docs/harper/IDEA.md (its Technology Constraints block becomes TECH_CONSTRAINTS.yaml), or write it with /idea.
  4. /spec then /plan → docs/harper/SPEC.md, PLAN.md, plan.json (the REQs). Put requirement documents (docx, pdf, xlsx, pptx, md) in docs/inputs/ and UI material (HTML prototypes, CSS, screenshots) in docs/harper/ux/: the phases read them as declared in .clike/context.yaml (context sources).
  5. 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/ + report
    

    Or /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 in runs/autopilot/report.md).

  6. /finalize when 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. Read docs/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, then scripts/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.
  7. Next release. Put the new requirements in docs/inputs/v2/ (background, blueprints in docs/reference/v2/; v3/ for the release after) and run /idea --extend — or attach them to the command (an attachment is required when docs/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 typed ADDED, MODIFIED (changes a delivered REQ, naming the checks it replaces) or REMOVED, keeps every delivered REQ as it is, tags the delivered state harper/v1 and writes docs/harper/EXTEND_<date>_<first>_<last>.md. Review it (--dry-run writes 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

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

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)