AGENT SKILL

cherry

How to install, run, use and drive Cherry, the local web workspace (127.0.0.1) where Claude Code plans, documents and builds the projects in ~/Projects. Use when the user mentions Cherry or the `cherry` command; asks to start, stop or open it; wants a project calibrated, surveyed, chatted with, scanned (security, tests, code health, dependencies) or handed to a background agent; asks for a scan report or what an agent did; wants to write a custom scan agent (~/.cherry/agents/*.md); edits _project/ notes the Cherry UI shows; or hits a Cherry problem (white screen, port 4317/5173 in use, 401, "Claude Code not found").

License 许可
MIT
最近更新
2026-11-10
Stars
★ 3
Forks
0

01 前言 Front Matter

name
cherry
description
How to install, run, use and drive Cherry, the local web workspace (127.0.0.1) where Claude Code plans, documents and builds the projects in ~/Projects. Use when the user mentions Cherry or the `cherry` command; asks to start, stop or open it; wants a project calibrated, surveyed, chatted with, scanned (security, tests, code health, dependencies) or handed to a background agent; asks for a scan report or what an agent did; wants to write a custom scan agent (~/.cherry/agents/*.md); edits _project/ notes the Cherry UI shows; or hits a Cherry problem (white screen, port 4317/5173 in use, 401, "Claude Code not found").

02 资源文件 1

03 SKILL.md 正文

Cherry

Cherry is a local workspace where Claude Code works on the user's projects the way an engineer would: survey first, decide, document, then build. A daemon (Fastify, 127.0.0.1:4317) drives the local claude CLI; a React UI talks to it. Nothing listens beyond loopback.

Two ways to help with it:

  • Tell the user what to do in the UI: the sections below say where everything is.
  • Drive the running app yourself through its API with scripts/api.sh (next to this file). Use this to start scans and agents, read reports, and check state. Never use it to answer approvals or decisions; those are the user's (see Safety).

Install and run

Needs Node 22, pnpm, git, and Claude Code signed in (claude auth status). gh is optional (GitHub box, Push, new repos). The repo pins Node and pnpm in mise.toml.

git clone https://github.com/syedmehedihussain/cherry && cd cherry
mise install && pnpm install
./scripts/install-cli.sh   # puts `cherry` in ~/.local/bin
cherry                    # start, print a login link, open the browser
Command Does
cherry / cherry up start the daemon (builds the UI if stale) and open the login link; --no-open only prints it
cherry start / stop / restart always on: a systemd user service that starts at login / off / restart after an update (ADR-0063)
cherry down / status stop it until the next cherry or login / say if it runs, how many projects, Claude status
cherry . / cherry open <folder> add a folder from anywhere to Home and open it (ADR-0031)
cherry open <project> open that project's workspace
cherry doctor check Node, git, gh and claude
cherry logout end every browser (and api.sh) session

Working on Cherry's own code: pnpm dev runs the daemon on 4317 and Vite on http://127.0.0.1:5173 with live reload. It and cherry cannot run at the same time (same port, same ~/.cherry); pnpm dev pauses the always-on service while it runs and starts it again after. The repo's CLAUDE.md has the dev rules.

Where things live

Path What
~/Projects/<name>/ one project per folder (the folder name is the project id); projectsDir in config changes the root
<project>/_project/ personal notes, git-excluded: STATUS.md (where we left off, next steps), project.json (phase, stack), tasks.json, notes.md, survey.json, decisions.md
<project>/CLAUDE.md, docs/ committed docs; the Docs tab lists them (ADRs in docs/adr/)
<project>/cherry/ git-ignored: uploads/ (chat attachments), reports/<agent>/<date>.md (scan reports)
~/.cherry/config.json the project list (projects), the new projects folder, default model, agent limits
~/.cherry/agents/*.md custom scan agents
~/.cherry/magnet/ Magnet's profile: MAGNET.md, me.md, work.md, generated projects.md
~/.cherry/run/daemon.json port, pid and CLI secret of the running daemon (0600)
<projectsDir>/.cherry-worktrees/ git worktrees of background agents

The UI

Home lists projects by last worked, with state (Ready, cctop notes only, Not calibrated), phase and git. The prompt box starts a new project survey (seven steps, each a decision card, then it writes CLAUDE.md, PRD, ADRs, STATUS and the first commit) or asks Magnet.

Calibration (on a project that is not Ready): Claude reads the project read-only, asks a few questions, then proposes files. Nothing is written until the user ticks the files; existing files only get additions.

Workspace (/p/<project>), three columns:

  • Left: file tree with git letters (M, A, U, D) and coloured type tags; "Claude touched" filter.
  • Centre tabs: Chat, Docs (reader for CLAUDE.md, docs/ and ADRs), Notes & Tasks, the open file (read-only, diff vs HEAD), and an open report (/p/<id>/reports/<agent>). The Status notch shows STATUS.md and can ask Claude to update it.
  • Right views: Overview, Live, GitHub (branch, pull, push, PRs, and Commits: stage and commit as you, or the Auto commit switch, where Claude commits its work through commit_changes, ADR-0030). Centre tabs: Chat, Docs, Notes & Tasks, Agents, Decisions.

Chat composer: attach files (paperclip, drop or paste, max 8 x 10 MB), Plan mode (Claude plans, no edits), model (Sonnet, Opus, Haiku), Effort (Default, Low to Max; hidden for Haiku). Every edit and command shows an approval card: Allow, Allow for this session, Deny. Claude may ask a decision card with options and a recommendation.

Agents view:

  • Scans: one-click read-only agents that write a report. Built in: Security review (Opus), Test runner, Code health, Dependency audit (Sonnet). They never ask anything: read tools run, edits and the web are off, and only the agent's own commands run (test/lint/typecheck for the Test runner, audit/outdated for Dependency audit, read-only git for all). The report opens in the centre with the history of earlier runs. Dependency audit contacts the package registry.
  • Tasks: a background agent gets a free-text task and works in its own worktree on agent/<slug>. It always runs in Auto: edits and commands need no approval. Push, publish, deploy and rm -r are skipped and listed as Needs you; Continue in chat hands them to the chat (ADR-0028). When done: Review diff, then Merge (into the current branch; on a conflict Merge with agent lets the agent fix it) or Discard. Needs a git repo with one commit.

Magnet is the cross-project assistant: read-only across all projects; it can propose actions (start an agent, calibrate, new project) that run only after the user approves.

Driving Cherry with scripts/api.sh

scripts/api.sh METHOD PATH [JSON] prints the JSON response; exit 1 on an HTTP error, 2 when Cherry is not running. It signs in with the CLI secret and keeps a cookie in ~/.cherry/run/skill-cookies.txt. Run it by its full path, e.g. .claude/skills/cherry/scripts/api.sh inside the repo or ~/.claude/skills/cherry/scripts/api.sh when installed for the user.

api.sh GET  /api/health                          # Claude found and signed in?
api.sh GET  /api/projects                        # project cards (id, state, phase, next step)
api.sh GET  /api/projects/<id>                   # card, STATUS.md, docs, git
api.sh GET  /api/projects/<id>/scans             # scan agents, running run, last report
api.sh POST /api/projects/<id>/scans/security/run
api.sh GET  /api/projects/<id>/reports/security  # history, newest first
api.sh GET  /api/projects/<id>/reports/security/<reportId>   # { meta, markdown }
api.sh POST /api/projects/<id>/agents '{"task":"Write tests for the streak service","model":"sonnet"}'
api.sh GET  /api/projects/<id>/agents            # status, summary, waiting approval
api.sh GET  /api/agents/<agentId>/diff
api.sh GET  /api/approvals?status=pending
api.sh GET  /api/projects/<id>/chat              # transcript of the current chat

A scan takes one to several minutes. Poll GET .../scans until that agent's run is null, then read last and fetch the report. Reports are also plain files under <project>/cherry/reports/, so reading them from disk works too. The full API is in the repo's docs/api.md; request bodies are the zod schemas in packages/shared/src/schemas/.

Safety

The approval cards are the user's control over what Claude does to their files. When driving the API:

  • Never POST /api/approvals/:id, POST /api/decisions/:id, .../calibrate/write, /api/agents/:id/accept, .../git/push or /api/magnet/actions/:id/approve unless the user explicitly asked for that exact action in this conversation. Tell them what is waiting and where to click instead.
  • Starting a scan, reading reports, and reading state are fine when they fit the request. Starting a background agent or a chat turn uses the user's Claude plan: say so first.
  • Do not PATCH /api/config or edit ~/.cherry/ without asking.
  • Never print daemon.json or the cookie file; they are credentials.

Writing a custom scan agent

Create ~/.cherry/agents/<id>.md (the file name is the id; an id equal to a built-in replaces it). It shows up under Scans with a "custom" tag; a broken file shows its error there.

---
name: Accessibility check
description: Labels, alt text, keyboard traps and contrast
icon: shield            # shield | flask | heart | package | bot
model: sonnet           # sonnet | opus | haiku
commands: pnpm lint, pnpm test   # optional; exact command or it plus arguments
---
What to look for, in what order, and how to rate severity (critical, high, medium, low).
Cherry adds the read-only rules and the report format (Summary, Findings, What to do next).

Reports are in ASD-STE100

Every report that an agent or subagent writes is in ASD-STE100 Simplified Technical English. This applies to Cherry scan reports, background agent summaries, custom scan agents, and any subagent you start (Agent tool) while you work with Cherry. Tell each subagent this in its prompt.

  • Short sentences: max 20 words in a procedure, max 25 in a description.
  • One instruction per sentence. Start instructions with the verb ("Run the tests.").
  • Active voice. Use approved words, with one meaning for each word.
  • Keep code, paths, commands, product names and error text exactly as they are.

Cherry adds this rule to the built-in scan and agent prompts. A custom scan agent gets it from the report format, so its body does not need to repeat it.

Troubleshooting

Symptom Fix
Port 5173 is already in use / 4317 another pnpm dev or cherry runs: cherry down, or find it with ss -ltnp | grep -E '4317|5173' and stop that process
White screen in dev, console says a module "does not provide an export" Vite cached a half-written file (often after a bulk prettier --write); touch that file and reload
401 unauthorized in the browser run cherry and open the link it prints (codes are single-use, 10 minutes)
"Claude Code not found" / not signed in install Claude Code, run claude auth login, then "Check again" or cherry doctor
Agent: "Agents need a git repository" / "Make a first commit" git init and commit once in the project
Scan ends "Did not finish" open the report for the error; usually Claude sign-in or a stop; run it again
Project missing on Home Cherry lists only opened or created projects: Open folder… on Home or cherry . in the folder (ADR-0032)

04 同仓库更多 Skills

syedmehedihussain
syedmehedihussain/cherry

verification-loop

Run a six-phase verification of a Claude Code session's work — build, type check, lint, tests with coverage, security grep, and diff review — then produce a PASS/FAIL verification report. Use when verifying work after completing a feature or refactor, before creating a PR, or when quality gates must pass.

★ 3
syedmehedihussain
syedmehedihussain/cherry

e2e-testing

Playwright E2E testing patterns, Page Object Model, configuration, CI/CD integration, artifact management, and flaky test strategies. Use when writing Playwright tests, structuring page objects, or fixing flaky E2E runs in CI.

★ 3
syedmehedihussain
syedmehedihussain/cherry

browser-qa

Run automated post-deploy UI verification with a browser automation MCP (claude-in-chrome, Playwright, or Puppeteer): console-error and Core Web Vitals smoke checks, form and auth-flow interaction tests, screenshot visual regression across three breakpoints, and axe-core accessibility audits ending in a SHIP / DO-NOT-SHIP verdict. Use when testing a deployed feature on staging or preview, before shipping frontend changes, reviewing a frontend PR, or checking responsive layout and accessibility.

★ 3
syedmehedihussain
syedmehedihussain/cherry

ai-regression-testing

Regression testing strategies for AI-assisted development. Sandbox-mode API testing without database dependencies, automated bug-check workflows, and patterns to catch AI blind spots where the same model writes and reviews code. Use when adding regression coverage to AI-assisted code, or when the same model both wrote and reviewed a change.

★ 3
syedmehedihussain
syedmehedihussain/cherry

story-lifecycle

Manage a file-based epic → story → sprint development loop without requiring an external project management tool. Creates and tracks epics, breaks them into user stories, assigns them to sprints, and drives implementation story by story. Use when starting a new feature initiative or when the team has no Jira/Linear/Taiga but needs structured delivery tracking.

★ 3
syedmehedihussain
syedmehedihussain/cherry

intent-driven-development

Turn ambiguous or high-impact product and engineering changes into scoped, verifiable acceptance criteria before or alongside implementation. Use when a user asks to clarify a feature, define acceptance criteria, de-risk a security/data/migration/integration change, prepare implementation requirements for another agent, or make a complex request testable. Do not trigger for trivial edits, straightforward fixes, active debugging, code review, or implementation requests whose acceptance conditions are already clear unless the user explicitly invokes this skill.

★ 3