Core concepts

Workspace

A workspace is a folder on your machine that contains everything an agent session needs — prompts, configs, data, scripts. If it has a rig.toml at the root, it's a rig workspace.

A workspace can exist with or without rig. Rig doesn't take it over; it adds a manifest and (optionally) a few helper files in .claude/ and .rig/.

Manifest

The rig.toml at the root of a workspace declares what the workspace needs to function: env vars, MCP servers, CLI tools, Claude permissions, folders, install hooks. It's the source of truth.

Manifests are split into sections, each documented individually:

• [rig] — identity (name, author, version, runtime).
• [package] — what gets included in the artifact.
• [env], [tools], [mcp], [plugins] — runtime requirements.
• [permissions] — Claude allow/deny rules.
• [local] — folders that aren't shared.
• [install], [run] — lifecycle hooks.
• [sync] — optional; opts the rig into shared mode.

Artifact

Run rig pack and you get a .rig.tgz: a gzipped tarball of the workspace files that the manifest says should be shared, plus the manifest itself. This is what gets published, downloaded, and installed.

Three properties matter:

• Reproducible — anyone who installs the same artifact gets the same workspace.
• Verifiable — every artifact has a SHA-256 the CLI checks on install.
• Minimal — no secrets, no .git/, no node_modules/, no outputs/ by default.

Source

A source specifier tells rig use where to fetch an artifact from. There are four kinds:

Full breakdown: Source specifiers.

The loop

Once you internalise this, the rest of the CLI snaps into place:

declare    →  rig.toml      (the manifest)
observe    →  rig doctor    (what's missing)
diff       →  the gaps list (a structured to-do)
record     →  rig install   (cache the observation, apply safe fixes)

Rig declares what's needed. rig doctor observes what's present. The gap between them is structured data — readable by humans and by agents — that either you or your agent can act on. After acting, run rig doctor again to confirm the gap closed.

This is also why rig install is idempotent and safe to re-run.

Next

• Install a rig with the loop in mind: Quickstart: install.
• Build one: Quickstart: create.
• The manifest in depth: Manifest reference.