User Guide — gato

Prerequisites #

Make sure you have these before installing.

Active Claude subscription — Pro, Team, or Enterprise. gato is a Claude Code plugin and does not include Claude access.
Claude Code installed and authenticated on your machine.
VS Code (optional) — required only for the sidebar extension. gato works without it.
code CLI in PATH — required for auto-install of the VS Code extension. In VS Code: Cmd+Shift+P → "Shell Command: Install 'code' command in PATH".

Installation #

Two ways to get the installer. Pick one.

Option A — one-line install

Paste this in your terminal. Downloads the installer and runs it automatically.

$ curl -fsSL https://gatoflow.dev/install.sh | sh

Option B — download binary

Download the installer for your platform from gatoflow.dev/#download, then make it executable and run it.

Note Both options place gatoinstaller on your system. Follow the steps below regardless of which option you chose.

01

Activate your license

Run the activate command with your license key. You'll receive the key after purchase at gatoflow.dev/#pricing.

$ gatoinstaller activate <your-key>

02

Install gato

Installs the Claude Code plugin and the VS Code extension (if code is in PATH).

$ gatoinstaller install

03

Verify the installation

Open VS Code. You should see the gato icon in the activity bar (left sidebar). Click it to open the dashboard panel. If the icon isn't there, see Troubleshooting.

Updating #

To update gato to the latest version, run:

$ gatoinstaller update

This updates both the Claude Code plugin and the VS Code extension. No need to re-activate your license.

The Workflow #

Three commands move a ticket from idea to shipped PR. A fourth lets you extend mid-flight without restarting. Run them inside a Claude Code session.

01

/work-on <ticket-or-description>

Pass a ticket ID (e.g. PDW-1234) or a plain description of what you want to build. gato fetches context, determines the work type, and creates a plan in plan mode — it never touches your code at this stage. Review the plan and approve it before moving on.

02

/decompose-plan

Breaks the approved plan into dependency-aware tasks and writes them to STATE.yaml. Independent tasks are grouped so they can run in parallel during implementation. For large plans, run this in a fresh Claude Code session to avoid context overflow.

03

/implement

Runs the full quality-gate pipeline. Each gate enforces a standard before the next begins. The workflow pauses at every checkpoint and waits for your approval. When prompted, say continue (or give feedback) to proceed to the next gate.

Gates Implementation → quality review → PR creation. Each gate must pass before the next starts.

+

/add-work extend

Mid-flight, need to add more work? Run /add-work with a description and gato extends the active plan and appends new tasks to STATE.yaml — no need to restart the workflow from scratch. Then run /implement again to pick up where you left off.

VS Code Extension #

gato adds a dedicated panel to VS Code so you can watch progress without leaving your editor.

01

Open the gato panel

Click the gato icon (◈) in the VS Code activity bar — the vertical icon strip on the left edge of the window. The sidebar panel opens showing the current workflow state.

02

Start a Claude session from VS Code

Press Cmd+Shift+P and run gato: Open Claude Session. This opens a terminal with Claude Code already focused on your project.

03

Read the dashboard

The panel has three tabs:

Tasks — gate stepper showing which checkpoint is active, plus task cards with status, file, and dependency info.
Plan — the approved plan document for the current session.
Lessons — patterns and decisions captured during the workflow.

The panel auto-refreshes as gato writes progress — no manual reload needed.

04

Send a code selection to Claude

Select any code in the editor, then press Cmd+Shift+A. The selection is sent directly to the active Claude Code session as context.

Other Commands #

These slash commands are available in any Claude Code session with gato installed.

command	what it does
/review-code	Runs a thorough code review on the current diff — quality, logic, and security.
/check-test-coverage	Checks test coverage for changed files and reports which lines or branches are missing.
/clarify	Asks gato to ask you clarifying questions before writing a plan — useful for ambiguous tickets.

Troubleshooting #

!

code not found in PATH

The VS Code extension cannot be auto-installed without the code CLI. In VS Code, open the Command Palette (Cmd+Shift+P) and run Shell Command: Install 'code' command in PATH. Then re-run gatoinstaller install.

!

License activation fails

Double-check the key was copied in full — no leading or trailing spaces. If activation still fails, your key may be tied to a different machine. Contact support and include the error message shown in your terminal.

!

gato icon not showing in VS Code

Reload VS Code (Cmd+Shift+P → "Developer: Reload Window"). If it still doesn't appear, open the Extensions panel and verify "gato" is listed and enabled. If not, re-run gatoinstaller install with the code CLI in PATH.

Support Still stuck? Email gatosupport@gmail.com or visit gatoflow.dev.