YYLO

2026-08-27 · Updated 2026-08-27 · 9 min read

Use Cursor with YYLO

Keep Cursor as your agent surface and add a control plane above it: the IDE-agent-plus-control-plane pattern, the boundary rules, the Cursor service wiring, and worktree isolation for parallel Cursor agents.

By Juno AI INC · cursor · interoperability · yylo

If you already run Cursor's agent, you have the fast half of the problem solved: an agent that plans, edits code, runs commands, and works from the editor, the terminal, or the cloud. What Cursor does not give you is the slow half — a queue of bounded tasks with Git-native truth, recorded evidence, admission gates, and serialized integration when several agents finish at once. This guide is about combining the two without duplicating your IDE workflows: Cursor stays the agent surface you already use, and YYLO becomes the control plane that decides which work the agent does, keeps the receipts, and merges the results.

The pattern is one sentence: IDE agent below, control plane above. Cursor's own docs describe its Agent as an assistant that "can complete complex coding tasks independently, run terminal commands, and edit code," built from three components — instructions, tools, and the model you pick (Cursor Agent overview). YYLO sits above that agent layer: it dispatches work to an installed agent service, bounds each run, and records responses, commits, and session evidence outside the agent. Neither side invades the other's job, which is what makes the combination stable.

What Cursor already owns

Cursor's agent surface is broader than the editor, and every part of it stays Cursor's. Verified against Cursor's published documentation on 2026-08-27:

  • The editor agent. The IDE experience — sidepane agent, plan mode, review — is Cursor's product surface. YYLO never drives the IDE itself; you keep reading diffs and reviewing changes exactly where you do today.
  • The agent CLI. The Cursor CLI "lets you interact with AI agents directly from your terminal," installed with curl https://cursor.com/install -fsS | bash and verified with agent --version (installation). It supports the same modes as the editor, interactive sessions (agent, agent --continue, agent --resume=...), and print mode (agent -p) for scripts and CI.
  • Cloud and background agents. Background agents — long-running tasks moved off your device — are what Cursor calls Cloud Agents: each "runs on its own dedicated virtual machine with a full development environment" (what are background agents?), and you "can run as many agents as you want in parallel" in the cloud (Cloud Agents).
  • Rules and AGENTS.md. Cursor reads agent instructions from four rule types — project rules in .cursor/rules, user rules, team rules, and AGENTS.md, which the docs describe as "Agent instructions in markdown format" and a "Simple alternative to .cursor/rules" (rules).

None of that changes when YYLO enters the picture. The decision you are making is not *which agent product to keep* but *who owns execution above the agent* — the seam the harness boundary guide draws in full.

The boundary between IDE agent and control plane

The pattern only works with explicit boundary rules, so here they are. Cursor owns everything the agent does inside one task; YYLO owns everything about which tasks exist and what happened to them:

  • Cursor owns the doing. Prompt interpretation, file edits, terminal commands, model choice per task, editor review. When you want Cursor-internal fan-out — subagents with their own context windows — that stays inside Cursor too.
  • YYLO owns the deciding and the recording. Task truth and dependencies, bounded dispatch with an iteration limit, responses and commit references on the task, worktree assignment, and the admission gate that turns finished work into merged history. That layer is Git-native task truth, not state inside any IDE.
  • The seam is the dispatch, and it is one flag. YYLO's -s/--subagent option documents cursor alongside claude, codex, gemini, and pi as selectable services — the README's own wording is "Switch between Claude, Codex, Gemini, Pi, or Cursor with one flag." A Cursor run under YYLO is therefore not a different Cursor; it is the same agent dispatched from a control plane that bounds and records it.

That last rule is also the honest limit of the integration today. YYLO's shipped service scripts wrap Claude, Codex, Gemini, and Pi; the services directory ships no Cursor wrapper, because the documented extension point is meant to be exactly here. Wiring your installed Cursor agent in is a small, explicit step — which is the next section.

Wire the Cursor agent into YYLO's dispatch surface

Service dispatch in YYLO resolves a script from the services directory: ~/.yylo/services/cursor.py (or cursor.sh), falling back to the generic subagent.py/subagent.sh. Every service script is an ordinary Python program that accepts -p/--prompt, -m/--model, and -v/--verbose and emits JSON events to stdout — the documented custom-backend contract. If no script matches, dispatch fails closed and prints the checked paths, so a missing service is a loud error, never a silent no-op.

Three steps connect the two sides. First install the Cursor CLI and check it:

sh
curl https://cursor.com/install -fsS | bash
agent --version

Then drop a minimal wrapper at ~/.yylo/services/cursor.py. This illustrative starting point forwards the prompt to the agent CLI in print mode, using only flags from Cursor's CLI docs (-p for print, --force so file changes apply in scripts, --output-format text for clean capture):

python
#!/usr/bin/env python3
"""Minimal YYLO service wrapper around the Cursor agent CLI."""
import argparse
import json
import subprocess
import sys

parser = argparse.ArgumentParser(description="Cursor agent service for YYLO")
parser.add_argument("-p", "--prompt", required=True)
parser.add_argument("-m", "--model", default="auto")
parser.add_argument("-v", "--verbose", action="store_true")
args = parser.parse_args()

command = ["agent", "-p", "--force", "--output-format", "text", args.prompt]
if args.model != "auto":
    command += ["--model", args.model]

result = subprocess.run(command, capture_output=True, text=True)
if args.verbose:
    print(json.dumps({"event": "command", "argv": command}), flush=True)
print(json.dumps({"event": "result", "output": result.stdout.strip()}), flush=True)
sys.exit(result.returncode)

Adapt it to stream richer events or add flags as your runs need — the directory is designed for user customization, and yylo services status (or yylo services install --force after template updates) tells you what YYLO sees. Then dispatch a bounded run:

sh
yy start -b shell -s cursor -i 1 -v

One model note saves confusion later: YYLO's built-in default model string for the cursor service is auto, so model choice stays with Cursor unless you override it — -m on the dispatch, or a configured per-service default, resolved CLI-flag-first. Full flag reference lives in the YYLO documentation. And because this wrapper is yours, moving in-flight work to another harness later costs what the harness-switching guide says it costs: one flag plus a deliberate handoff, with task truth never moving at all.

Give every Cursor agent its own worktree

The second half of the pattern is spatial. An IDE agent edits whatever repository it is pointed at, and the failure mode of agent work is almost always "the agent and I were both editing the checkout." YYLO's answer is the task worktree, and it applies to Cursor agents exactly as it does to every other service:

  • One task, one worktree. Every product change runs in a dedicated yy task worktree returned by yy task start TASK_ID — the README states it plainly: "The worktree is the safety boundary." You implement, run focused tests, and commit inside the returned worktree, whether the editor doing the editing is Cursor or anything else.
  • Parallel-safe by construction. Feature worktrees are independent, so two tasks can implement concurrently from recorded exact bases — one Cursor agent per worktree, no collisions, no shared dirty state.
  • Serialized landing. yy merge serializes only target mutation, so when several Cursor agents finish, integration is still one-at-a-time with review — the discipline the multi-agent workflow guide extends across harnesses.

The practical loop for a Cursor user: start the task, cd into the returned worktree, open it in Cursor (or run the agent CLI there), and let the IDE agent work inside the boundary YYLO drew. There is a satisfying symmetry with Cursor's cloud side — Cursor isolates its Cloud Agents on dedicated VMs, YYLO isolates yours in Git worktrees — but the worktree version has a property the VM version cannot offer: the isolation boundary is your own repository's history, so the agent's output arrives as reviewable commits rather than a finished diff from outside.

Run several Cursor agents in parallel

Cursor itself acknowledges the multi-agent direction — its CLI announcement describes choosing "to use Cursor agent in the editor, or have multiple agents run in parallel in the terminal or remotely," and cloud agents exist to "run many agents at once" without your laptop staying connected (CLI announcement, Cloud Agents announcement). YYLO adds the part those surfaces leave open: what the agents are working from, and what happens when they all finish.

Keep the two fan-out layers separate. Cursor-internal subagents are Cursor's mechanism — useful, and untouched by YYLO. Task-level parallelism is the control plane's mechanism: independent tasks in independent worktrees, each dispatched as a bounded run, each leaving its own response-and-commit evidence. When you scale that past a couple of tasks, the readiness, quota, and isolation habits in safe parallel Kanban execution are the operating manual — the only change here is that the workers are Cursor agents.

AGENTS.md, rules, and what the task carries

Cursor's instruction surfaces and YYLO's task truth solve different problems, and the boundary rule is simple: rules shape the agent; the task defines the work. Your AGENTS.md and .cursor/rules keep telling Cursor's agent how to behave in this repository — style, conventions, review expectations. What YYLO dispatches is the bounded task itself: the description, the response contract, the commit expectation, the stop condition. Neither substitutes for the other, and they compose without conflict because they enter the agent at different layers — one as standing instructions, one as the prompt for this run.

If you keep secrets, skills, or substitution commands in the picture, read prompt and shell-context safety before wiring anything irreversible into either side; the boundaries it teaches apply unchanged when the harness under YYLO is Cursor.

Start one bounded Cursor task today

The cheapest way to prove the pattern is one small task with nothing riding on it:

sh
npm install -g @yylo/cli
yylo init --task "Describe one verifiable outcome" --subagent cursor
yy start -b shell -s cursor -i 1 -v

Watch what lands: the response and commit reference on the task, the session evidence outside the editor, and a checkout that was never at risk. Keep first runs inside the bounds the bounded-loop guide teaches — one verifiable outcome, focused checks on the touched surface — and the combination settles into what it should be: Cursor doing what it is already good at, under a control plane that makes the work auditable. Cursor's published behavior, the CLI flags, and the rule types cited above were verified against Cursor's documentation on 2026-08-27; YYLO's service, dispatch, and worktree claims against the committed README and source. Both sides move — re-verify before relying on either after they change.