Quick start

From a fresh machine to a closed sprint in six steps. You need Git (on Windows the installer offers to install it) and one of Claude Code, Pi or Copilot CLI.

1. Install

On macOS or Linux:

macOS / Linuxcurl -fsSL https://getcanon.dev/install.sh | bash

On Windows 11, in PowerShell (no WSL and no git clone needed):

Windowsirm https://getcanon.dev/install.ps1 | iex

Open a new terminal afterwards so canon, sprint and tkt are on your PATH.

If Git for Windows is missing

canon's tools run in Git Bash, which comes with Git for Windows. If the Windows installer does not find it, it stops and asks first:

A PowerShell window running the install command. The installer says canon's tools run in Git Bash, which comes with Git for Windows, that it is not installed yet, that it installs it once with winget, and that Windows will show an admin (UAC) prompt where you click Yes. The last line asks Install Git for Windows now? [Y/n].
The installer asks before it installs Git.

The message reads:

canon's tools run in Git Bash, which comes with Git for Windows. It is not installed yet. This installs it once with winget. Windows will show an admin (UAC) prompt; click Yes.

Install Git for Windows now? [Y/n]:

Answer Y. If you answer n, nothing is installed and the folder ~\.canon is not created. The installer prints the Git for Windows download link and the command to run again once Git is installed. After Y, Windows asks you to approve the change:

A Windows User Account Control dialog asking whether to allow the Git for Windows app to make changes to your device, with Yes and No buttons. The No button is highlighted.
Click Yes. The highlighted button is No, so click Yes rather than pressing Enter.

Git's own setup window then runs with a progress bar:

The Git Setup window with the heading Installing and a progress bar while files are extracted.
Wait for Git's setup to finish.

The canon install then carries on. It prints that you can run canon in this PowerShell window, and that for future windows you open a new one and run canon there. Its last line is canon installed successfully.

2. Open the Cockpit from a Terminal, Command Prompt or PowerShell window

canon

This opens the Cockpit at http://127.0.0.1:8899/cockpit. Canon prints its version, the port and the project it started in, then where that project's tickets are. The terminal stays busy while the Cockpit runs, so leave that window open.

A PowerShell window: the command canon, then the line Canon Cockpit 0.46.0 (c040e04a) listening on 127.0.0.1:8899 (project: agentops), then tickets: C:\Users\agentops\.tickets.
The first run. The project name is the folder canon was run from.

The Cockpit opens on the Projects page. On a new machine it has no projects yet.

The Cockpit Projects page with no projects: the sidebar lists Projects (0), Factory and Admin, and the page says No projects registered yet. Click + Add Project to register a project folder.
The Cockpit on a new machine.

Run canon again while it is up and it does not start a second Cockpit. It prints The Cockpit is already running on port 8899. Opening it., opens the same address and returns your prompt.

A second PowerShell tab: canon prints The Cockpit is already running on port 8899. Opening it. and returns to the prompt.
A second run.

3. Add a project

On the Projects page, click + Add Project. Type the folder path, or click Browse…, move to the folder and click Use this folder. A description is optional. Then click Add Project.

The Add Project dialog browsing C:\Users\agentops\Documents, with a Use this folder button and one folder listed, ToDo-Demo.
Browse to the folder and click Use this folder.
The Add Project dialog with the path C:\Users\agentops\Documents\ToDo-Demo and the description A small Todo app for the Quick start, ready to add.
Then click Add Project.

This guide uses git, so that the end of the sprint has commits to show. While git is not enabled for a folder, the git icon beside the project's name is grey. Click it and confirm Turn on: canon runs git init in the folder, writes a .gitignore if there is none and makes its first commit, chore: start tracking changes with canon. It needs Git installed, and nothing is uploaded.

The Turn on version history for ToDo-Demo dialog, saying it needs Git installed and that nothing is uploaded, with the buttons Cancel and Turn on.
Click Turn on.

The icon turns blue and the card lists what is not registered yet: + efficiency (optional) and + sprint.

The Cockpit Projects page with one project card, ToDo-Demo, with a blue git icon beside its name. Its rows read Added, Updated, Total Tickets 0, Skills —, Learnings Not needed yet, Skill Eval Open and Factory Not set up, and its buttons are + efficiency (optional), + sprint, Scratch, a cross and a green arrow.
The project is added, with git on.

A folder without git works too: add it and run agents in it, and skip the icon. See Projects without git.

4. Register sprint and efficiency

On the project's card, click + sprint and confirm Register. This wires the sprint workflow into the project: it updates AGENTS.md and CLAUDE.md, installs a git pre-commit hook (if the folder uses git), creates .tickets/ and links the skills folder. It is safe to run again. The card then lists sprint under Skills.

The Register the sprint skill dialog: it says it wires the sprint workflow into the project, updates AGENTS.md and CLAUDE.md, installs a git pre-commit hook, creates .tickets/ and links the skills dir, with the buttons Cancel and Register.
Confirm Register.
The project card after registering: Skills lists sprint, the + sprint button is gone and + efficiency (optional) remains.
After registering: Skills lists sprint.
Efficiency is optional

Register efficiency the same way, with the + efficiency (optional) button. Canon's own dialog calls it optional and says sprint does not need it. It is the standards file your agent reads in every session: coding rules, the format for review feedback, git conventions, triggers for what to do when it sees a problem, and token-saving habits. This guide registers it, so you see the prompt it adds in step 5.

The Register the efficiency skill dialog: it says This is optional, that it adds canon's coding and git conventions for all agent work, updates AGENTS.md and CLAUDE.md and links the skills dir, with the buttons Cancel and Register.
The efficiency dialog says it is optional.

sprint brings its helper skills (wrapup, learnings-sweep, promote-learnings) with it, so most projects need nothing else. See Registering skills.

Prefer the terminal?

From the project folder, run:

skills.sh add sprint
skills.sh add efficiency
skills.sh status

The same registration, with the same files written. It also adds ~/.canon/tools to your PATH if you agree to it.

5. Run your first sprint

Click the green › button on the project's card to open its board. Then click + New, type what needs to be done and click Create →. Canon suggests the type from your title (here, Feature); the defaults are fine for a first ticket. The Options row has CI, Eval-only and Lite; leave them off, so this guide shows the full close.

A project card with the green arrow button, at the bottom right, outlined.
The green button opens the project.
The New Ticket dialog filled in: the title Create a Todo app, Detected: Feature, priority P2, no tags, the options CI, Eval-only and Lite, and a description with Problem, Outcome and Constraints. Create and Cancel are at the top right.
The New Ticket form.

The ticket lands in Open. Click Start on its card. Its tab opens with a Worktree panel: leave it on Main checkout, choose your agent and press ▶ Start sprint.

The project board with one card in the Open column: t-c662, Create a Todo app, a Feature, just now, P2, needs acc, with a Start button.
The ticket lands in Open. Click Start on its card.
The ticket tab before the sprint starts: a Ticket details card listing Description, Plan and Acceptance with an Open link, a Worktree panel set to Main checkout, a Status panel, and a terminal saying press Start sprint with the agent picker set to Claude Code and a Start sprint button.
Pick the agent and press Start sprint.

The first time Claude Code opens in a new folder it asks whether you trust it. No, exit is highlighted, so move to Yes, I trust this folder before you press Enter. It also notes one pre-approved permission in .claude/settings.json, Bash(subagent-log.sh:*): canon's own rule for logging review runs.

Claude Code's folder trust prompt in the Cockpit terminal, listing the one pre-approved tool permission and the choices No, exit and Yes, I trust this folder.
Claude Code's one-time trust check for a new folder.

When efficiency is registered, Claude Code then asks Allow external CLAUDE.md file imports?. Your project's AGENTS.md imports canon's efficiency standard from .canon/standards/efficiency.md in your home folder, which is outside the project, and the prompt lists that file. Choose Yes, allow external imports and the agent loads the standard. With No, disable external imports the agent still starts, but without the standard, and nothing tells you.

Claude Code's external-imports prompt in the Cockpit terminal, listing C:\Users\agentops\.canon\standards\efficiency.md and the choices No, disable external imports and Yes, allow external imports.
Claude Code asks before loading a file outside the project.

Then sprint start runs. The agent reads your repo, writes its research.md, acceptance.md and plan.md, and stops with a brief: the goal, the tier, any DECISIONS.md entries that apply, the files, the acceptance criteria, the test plan and any open questions. In this run it also gave a short perspective check from the user's, security's and architecture's side. It ends by asking Shall I proceed?, and nothing is built yet.

The end of the agent's brief in the Cockpit terminal: six criteria for the Todo app, a Test Plan, Open questions reading The ticket has none, and the question Shall I proceed?
The agent stops at the plan. Approve it, or tell it what to change.

The strip above the terminal, 89% cache · 6 calls · 8 tools, counts what the session has done so far. Only Claude Code sessions show it:

Canon reads the figures from the session's own Claude Code transcript and refreshes them about every 5 seconds. They are not saved anywhere: after a restart, canon counts the transcript again.

Tell the agent to go ahead (or what to change). It ticks the sign-off box in plan.md, builds and tests. In this run it then stopped and asked for a browser check: open index.html and look at the look, the hover and focus states, dark mode and a narrow window, then tell it what you see, and it would tick the remaining boxes once it looked good. The app had been restyled during the build, so the acceptance list had grown from six criteria to seven.

The agent's message after the build: the Test Plan, what is done so far, the plan left alone, and the request to open index.html and check the look, the hover and focus states, dark mode and a narrow window.
The agent asks you to try the app before it closes.

When you ask for sprint complete, the agent first asks you to confirm the close. Then a fresh reviewer and, after it, a fresh evaluator, with no memory of the build, check the work. A failing evaluator blocks the close. See Sprint and gates.

The agent's close confirmation: it ticked every box in acceptance.md, then asks Ready to close sprint t-c662?, and lists what the close does: wrapup, a fresh reviewer (advisory) and a fresh evaluator (binding), the test gate, and that it will not push without asking.
The agent asks before it closes.

The checks read committed changes, so before them the agent commits the sprint's work if it is not committed yet. When both pass, the ticket closes and the agent commits the closing docs. Anything else still uncommitted in the project stays that way, so commit it before you run a second ticket in its own worktree; see Working in worktrees. It also saves a lesson candidate; see Learnings. In this run the closing message reports Reviewer (advisory): YES, with nothing to act on. and Evaluator (binding): pass on all 7 criteria and 3 Test Plan items. At the end the agent asks whether to add a remote, and it does not push unless you ask.

The end of the close in the terminal: the Reviewer (advisory) line reads YES, with nothing to act on, with one noted item, the Evaluator (binding) line reads pass on all 7 criteria and 3 Test Plan items, there is no test script, two commits are listed, d4c6d35 feat: add single-file Todo app and add54bc chore: close sprint t-c662 with gate reports, a learnings candidate was written, and the agent asks Do you want to add a remote, or leave it local?
Closed: the gates passed, two commits are local and nothing is pushed.

Prefer your own terminal? Open your agent in the project folder and ask it to run sprint start.

6. See the result

The sprint is closed, so end the agent's session: click End session at the top right of the ticket tab.

The top of the closed ticket's tab: the Board button and the t-c662 tab at the left, the CLOSED badge on the ticket card, and the End session button at the top right, outlined.
The End session button, at the top right of the ticket tab.

Then choose End without saving. The dialog says the ticket is closed and there is nothing to save. While a sprint is still open it also offers Save & End; see Agents and sessions.

The End session dialog for a closed ticket: it says a sprint session is still running and that the ticket is closed, so there is nothing to save, with the buttons End without saving and Cancel.
End without saving: a closed ticket has nothing to save.

The agent built a working app in the project folder. Open index.html in a browser to try it.

The Todo app in a browser: a card headed Todo with an input that reads What needs doing?, an Add button, and two items, one ticked and struck through, each with a red Delete button.
The app the agent built.

Back on the board, the ticket is in Done. Open the side panel with the › at the left of the board. It shows the git state, the project's current focus from HANDOFF.md, the recent commits and a count of tickets by type and by status; Cockpit and board describes each part. The git line counts changed and untracked files; here it reads 6 modified. Click the ticket to read its plan, acceptance criteria, eval report and summary.

The project board with the side panel open: the ticket Create a Todo app in the Done column, and a panel with Git on master with 6 modified, Current focus reading ## In Progress, three recent commits and a Tickets donut reading 1 with 1 feature and 1 done.
Done: the ticket has moved, and the panel shows the commits.

Click a commit in the panel to see what it changed: the message, the files and the ticket it closed.

The commit details dialog for feat: add single-file Todo app: the author and date, the message body reading Closes: t-c662, Related tickets with a link to t-c662 Create a Todo app, and 3 files changed: DECISIONS.md, HANDOFF.md and index.html.
A commit, linked back to its ticket.

Where next

To remove canon later, see Uninstall canon: it starts with a dry run that changes nothing.