For anyone who has installed kit and wants to see the Issue-driven loop once, end to end. There are two ways to run it: Pattern A takes one Issue at a time from plan to merge, and Pattern B files several Issues first and then lets the agent work through them unattended. Each step names the one thing to type and links to the guide or reference that holds the details — this page is the map, not the manual.
kickoff, halfrun, prrun, fullrun and backlogrun are keywords you type to the agent, not josh commands; the agent drives josh and gh for you. Run Issues with the workflow keywords explains each one.
Not using GitHub? Both patterns need it — go to Without GitHub: one change, checked locally.
- kit is set up with
josh start, and its setup is onmain— merge the setup pull request it opened, if it opened one (init.md →josh initorjosh start). The profile guides walk through it: Set up the basic profile forbasic, Set up the full profile forfull. - Use a practice repository on GitHub that you are happy to experiment in, with
ghinstalled and signed in (gh auth login). - An agent that reads the repository's
CLAUDE.md, such as Claude Code, is open in the repository. - Telegram notifications are set up, so a stopped run reaches you off-screen — or turned off with
JOSH_NOTIFY=offin.env. Without either,josh notifyexits non-zero (Set up notifications).
Do not file the Issue yourself. Talk the change through with the agent first — what should be true when it is done, what is out of scope, how to check it. When the plan is settled, type:
kickoff new
The agent files the Issue from the conversation, posts the agreed plan on it and stops without touching the code. Note the Issue number #N. If the plan on the Issue is wrong, comment with the correction — a later comment wins over the body.
When you want to look at the change before it is committed — UI work, or anything you would rather check by eye — type:
halfrun #N
The agent implements the change, runs the verification gate and a self-review, then stops before committing. Look at the working tree yourself — git diff, and open the changed page or run the changed code — and ask the agent for changes until you are happy. Skip this step when you do not need to see the code.
Type:
fullrun #N
The agent writes the plan on the Issue if it has none (the one kickoff new filed already does), implements the change, runs the gate and the self-review, opens the pull request with the closes #N line, waits for CI and merges it. The run ends with the Issue closed and a notification; it stops only when something needs you.
To merge the pull request by hand instead, type prrun #N: it goes as far as a green, mergeable pull request and stops there (Run Issues with the workflow keywords).
If you ran halfrun in step 2, its changes are still uncommitted in the working tree. Type fullrun #N all the same: it picks the stopped halfrun up from the gate, skipping the plan and the implementation, and ships the change you checked. Without an agent, the commit command in the stop notification finishes that run instead of fullrun #N or prrun #N (Recover a stopped run).
Repeat step 1 of Pattern A for each change: agree the plan with the agent, then type kickoff new. A change too large for one Issue is split by the agent into several Issues under an epic, so you may get an epic back instead of a single Issue.
Add the auto-ok label to each Issue the agent may implement and merge without you — or to the epic, which opts in every Issue under it. An Issue the agent files, including one you asked for with kickoff new, gets it when it meets the criteria and needs no judgement from you. josh start creates the label, and josh sync adds it to a repository that lacks it.
Type:
backlogrun
The agent runs every opted-in Issue in dependency order, each one from implementation through the gate, the review and the merge, and notifies you as each finishes. You do not order the Issues or decide which may run side by side: before the first one starts, the agent reads them, records which must land before another as a blocked-by relation, and labels run:solo any Issue fixing a defect in kit's own verification (the gate, the review, the push hook or the merge checks) that makes unrelated PRs answer wrongly on main today, and run:lane every other one. The run then starts a run:solo Issue alone, and runs the rest in parallel lanes. An Issue you opt in while the run is going is judged the same way before anything else starts. Run the backlog unattended covers naming Issues to run first, running one epic only, and where the run stops.
Not part of the loop above. After upgrading @joshuafolkken/kit, run pnpm josh sync to refresh the rules and files kit manages; it writes only the file set of the project's profile. Update kit has the steps, and sync.md lists what it overwrites.
For a project set up with josh init and no GitHub. The workflow keywords above need GitHub, so do not type them — ask in plain words. What josh init set up: TypeScript projects · other projects.
-
Open an agent that reads the project's
CLAUDE.md, such as Claude Code, in the project directory. -
Ask for one small change:
Change the page title to "Hello", then tell me what you checked. -
The agent reads the file before changing it, makes the change, checks it and reports what it saw. In a
fullprofile project it also adds a test where one fits, runspnpm josh gate, and reports which checks passed and which did not. -
Check it yourself: run
pnpm josh gate(what it checks and skips), and open the page in a browser when the change is visible.
Want Issues, pull requests and merges handled too? Run pnpm exec josh start — in a repository that already has commits, commit your changes first (init.md → josh init or josh start), then follow Pattern A.
- One guide per task: how-to.md.
- A word on this page you did not recognize: glossary.md.
- A run stopped and you want to continue or clean up: Recover a stopped run.
- A run fails on the gate or CI: Fix a failing gate or CI.
- Every command: josh-commands.md.