Before you start
You need three things:- An AI coding app such as Claude Code or Codex, installed and signed in. It must be able to open a folder on your computer and edit its files. You use your own AI account.
- A project folder. An empty folder is fine for a new idea. For existing work, open the folder that contains the project’s files.
- Git, the tool that saves the history of your files. If it is missing, follow Git’s installation guide. The Windows installer below can install it for you.
What is a terminal, and where do I paste commands?
What is a terminal, and where do I paste commands?
A terminal is an app where you give your computer written commands. On macOS, open Terminal
using Spotlight. On Windows, open PowerShell from the Start menu. On Linux, open your
Terminal app.Copy a command, paste it into the terminal, and press Enter. Wait for it to finish before
pasting the next one. Messages labelled Send to your agent go into your AI chat instead.
1. Install Jig on your machine
Choose your operating system. These commands download and run Jig’s installer; expand the details if you want to inspect the script or see what it changes first.- macOS and Linux
- Windows
Paste this into Terminal:Open a new terminal window when it finishes.
What the installer changes and system requirements
What the installer changes and system requirements
The installer:
-
clones Jig into
~/.local/share/jig, at the newest release; -
links
~/.local/bin/jigto it; -
only when
~/.local/binis not on yourPATHyet, adds one marked line to~/.zshrc,~/.bashrcor~/.profile; -
links the
jig-pr-reviewskill for you, so you can review a pull request from any folder: to~/.claude/skills/jig-pr-reviewwhen you have Claude Code (~/.claude), and to~/.agents/skills/jig-pr-reviewwhen you have Codex (~/.codex). A skill of your own under that name is left alone.jig self-updatekeeps it current. To turn it off, delete the link: Jig leaves a record beside it (.jig-pr-review.placed) and does not put back a skill you removed. Delete that record too to have the skill placed again at the nextjig self-update. Coming from 0.43.0 or older, the firstjig self-updateruns the old updater, which does not place the skill; runjig self-updateonce more.
sudo and does not touch the folder you ran it from. Open a new terminal
afterwards so the new PATH is picked up. Running the line again is safe: it moves a clean
installation forward and refuses to overwrite anything it did not create.Jig needs Bash 3.2 or newer, Git and the standard Unix tools, all of which macOS and Linux have.
WSL2 works as Linux; keep the project on the Linux filesystem, not under /mnt/c.command not found, see installation help.
Read the script before running it, or install without it
Read the script before running it, or install without it
To read the macOS/Linux installer first:Its options: A clone made this way follows
--ref main installs the development channel instead of a release, --ref vX.Y.Z
a specific release; --install-dir, --bin-dir and --no-path change where things go and skip
the startup-file line.A checkout on a branch, such as --ref main, is the development channel: its code is not in any
release. A project that keeps Jig’s files in its own repository will not take files from it
without --unreleased; see
the source is not a release.Without the installer, clone Jig into a permanent folder and put its executable on PATH:main, the development channel, so projects will refuse to upgrade
from it until you check out a release tag: git -C "$HOME/.local/share/jig" checkout vX.Y.Z.2. Set up a project
Open your project folder in your AI coding app. Then send:Send to your agent
For developers: set up an empty project by hand
For developers: set up an empty project by hand
After installing Jig, run these commands in a terminal. Use Git Bash on Windows for this example.
Choose a new folder name rather than a folder holding existing work.Review the generated files, then save this initial setup:If Git asks for an identity, set your name and email for this repository, then retry the commit:For an existing repository, run only
jig init, review the diff, and stage the setup files
explicitly. Do not include unrelated changes in the setup commit.For developers: what project setup adds
For developers: what project setup adds
jig init adds .ai/ (knowledge, configuration, scripts), skills in .claude/skills/ and
.codex/skills/, and entries in .gitignore and .gitattributes. It creates AGENTS.md and
CLAUDE.md only when absent. It detects verification profiles from manifests such as
package.json, composer.json, and pyproject.toml.jig init commits nothing. Commit the setup so teammates receive the same project copy of Jig.
An empty project starts with the generic profile; stack-specific profiles follow when you choose
the technology. Jig itself needs no Node.js, Python, or build step; your application may need them.The Jig section for AGENTS.md
The Jig section for AGENTS.md
3. Let the agent learn the project
Send to your agent
Setup is ready when Jig runs, the initial setup is saved in Git, and your agent recognizes
Jig’s workflow. You can now describe what you want to build or change.
Build a new project
Turn your idea into a plan and ask for the first working result.
Improve an existing project
Bring in your existing rules and start a focused change.
Keep Jig up to date
Updating is two separate steps, because updating the tool on your machine must never change a project behind your back. A project on Jig 0.38.1 or older may need its first upgrade, to 0.39.0 or newer, run with the Jig on your machine by its full path: see From 0.38.1 to 0.39.0.self-update refuses a checkout with uncommitted changes and changes no project. upgrade fetches
nothing: it copies from the Jig on your machine, updates only files Jig installed and you did not
edit, removes the ones Jig no longer ships unless you edited them, keeps and reports the edited ones, and never touches project knowledge or configuration.
In AGENTS.md it updates one thing — the section between <!-- jig:begin --> and
<!-- jig:end -->, and only while that section is still exactly what Jig last wrote there, so
improvements to Jig’s own instructions reach your project without you doing anything. Edit inside
those markers and Jig keeps your version instead. jig status tells you when the project’s copy is older than the tool. Review the
diff and commit it.
Run jig doctor any time something seems off: it checks the tool, the project and the agent
instructions, one line each, with a fix for every warning.