How do comments become code?

npx @pinsay/cli apply closes the loop between user feedback and source code. It transforms pending comments into a self-contained, context-rich prompt tailored for AI coding agents, manages git commits, and updates the feedback queue with verified commit links.

End-to-End Workflow

When stakeholders submit comments on your running application, they enter the feedback queue with status ReadyToApply. To turn those comments into code changes:

1. Check health: Run npx @pinsay/cli@latest doctor to verify credentials, API version, and configuration.
2. Plan first: Run npx @pinsay/cli@latest apply --plan to preview proposed edits without touching any code.
3. Apply changes: Run npx @pinsay/cli@latest apply (or specify an AI tool with --tool) to generate the prompt.
4. Stage edits: The AI edits the relevant components and stages them with git add -- <files>.
5. Record and commit: Run npx @pinsay/cli@latest apply --mark <number> --reply "<what changed>". The CLI creates the git commit and records the commit URL on the server.

Comment numbers are per project: the first comment in a project is #1. The CLI looks the number up in the project configured for this repo.

Safe First Run: --plan

Running npx @pinsay/cli@latest apply --plan generates the exact apply prompt with an explicit PLAN ONLY header instructing the AI agent to list which files it intends to change and how, without modifying any files on disk.

npx @pinsay/cli@latest apply --plan

This allows human review before any code is generated or edited.

AI Tool Hand-Off (--tool)

Instead of piping or copying stdout manually, the --tool flag hands the apply prompt directly to your AI tool of choice:

Single vs Separate Commit Styles

PinSay supports two commit styles, configured under Project Settings (or via capture-config):

• Separate Commits (commitStyle: 2): Each comment receives its own distinct git commit. Run npx @pinsay/cli@latest apply --mark <number> --reply "..." after each item. The commit message follows: Apply <ProductName> comment #<number> — <body preview>.
• Single Commit (commitStyle: 1, default): All pending comments are grouped into a single commit. The AI stages all changes, and you run npx @pinsay/cli@latest apply --mark all --reply "..." once. The commit message follows: Apply N pending <ProductName> comments.

The --mark Step

npx @pinsay/cli apply --mark enforces strict preconditions before updating status:

• Staged index check: You must have staged changes with git add. If the git index is empty, --mark exits with code 1 and makes no API calls.
• Automatic commit: The CLI creates the commit on the current branch using the repository's configured commit style.
• Commit URL generation: Derives the remote URL (GitHub, GitLab, or Bitbucket) and appends the new commit SHA.
• Status update: Sends a PATCH /api/comments/<id> marking status as Applied with your reply and commit URL.

Using your design system

When an AI coding tool applies feedback like "make this button blue" or "round these corners", it should use your application's existing design tokens rather than inventing arbitrary hex codes or pixel values.

During npx @pinsay/cli init (or when running npx @pinsay/cli doctor --refresh-stack), PinSay automatically detects local design token sources — including Tailwind configuration, CSS custom properties, SCSS variables, and CSS-in-JS themes. These tokens and actionable guidance are saved locally in .pinsay/stack.json and injected into the apply prompt.

This ensures the AI refers to your brand tokens (such as text-primary or var(--primary)). Because design tokens represent internal repository naming and conventions, they remain strictly on your machine in .pinsay/stack.json and are never uploaded to the PinSay server.

Files: screenshots, annotations, recordings and voice

apply, apply --json and get save each comment's files on your machine under .pinsay/media/<project>/<number>/ (hidden from git) and give the AI agent each file's path:

• Annotated screenshot: the marks the person drew are part of the instruction.
• Recordings: the prompt lists the steps to reproduce, each with its screenshot and the failed calls and console errors after it.
• Voice messages: each audio file comes with its words (browser or server transcript), treated as untrusted text like the comment itself.
• Replies with files: shown as evidence of what is still wrong after an earlier attempt.

Marking a comment applied deletes its folder; folders older than 7 days are removed on the next run.

Shared rules and prompts in apply --json

apply --json prints { "shared": { "aiRules": [...], "prompts": [...] }, "items": [...] }. The AI rules and the predefined prompts come once: rules with appliesTo: "all" (Workspace, Project, Role) apply to every comment, a Personal rule (appliesTo: "author") only to the comments that list its id in aiRuleRefs, and each item's pickedActions[].id names its predefined prompts. With several projects, each project's entry has its own shared block.