Skip to main content
Installing Jig is two steps: put the jig tool on your machine once, then set up each project that should use it. Jig needs Git and a coding agent — Claude Code or Codex. It needs no Node.js, Python, package manager or build step.

​
1. Install Jig on your machine

Paste one line into a terminal:
The installer:
  • clones Jig into ~/.local/share/jig, at the newest release;
  • links ~/.local/bin/jig to it;
  • only when ~/.local/bin is not on your PATH yet, adds one marked line to ~/.zshrc, ~/.bashrc or ~/.profile.
It needs no 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.
To read the macOS/Linux installer first:
Its options: --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.Without the installer, clone Jig into a permanent folder and put its executable on PATH:
A clone made this way follows main, the development channel.

​
2. Set up a project

In your project folder — a Git repository — run once:
It adds:
  • .ai/ — project knowledge, configuration and Jig’s scripts (so a teammate needs no global install);
  • AGENTS.md and CLAUDE.md — the instructions your agent reads, when they do not exist yet;
  • the Jig skills for Claude Code (.claude/skills/) and Codex (.codex/skills/);
  • a few lines in .gitignore and .gitattributes.
It detects your stack from its manifests (package.json, composer.json, pyproject.toml …) and turns on the matching verification profiles. Nothing is committed: review the change and commit it, so everyone who clones the project gets the same setup. Commit right after jig init. A task starts on its own branch, and Git cannot branch from a repository with no commits yet.
Already have your own AGENTS.md or CLAUDE.md? jig init never changes them. Until they carry the Jig section, your agent does not know Jig’s workflow and will not use its skills by itself. jig init, jig status and jig doctor all tell you when this is the case.The easy way: ask your agent “connect Jig to my AGENTS.md”. The jig-init skill shows you the section and adds it once you agree. To do it by hand, append the section below to AGENTS.md; for CLAUDE.md, add the line @AGENTS.md (or the same section, if your CLAUDE.md does not import AGENTS.md).

​
3. Let the agent learn the project

Open the project in your agent and say “set up Jig for this project” (or name the skill: /jig-init in Claude Code, $jig-init in Codex). The agent studies the code and writes the project’s glossary, architecture and rules into .ai/knowledge/, shows you each document in full, and asks where a term or a boundary is ambiguous. What happens next depends on where you start: a new project begins with an idea, an existing project with the documentation it already has.

​
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.
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, configuration or your AGENTS.md. 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.