Getting started

This page takes you from nothing to a first completed task. Every command on it exists in the shipped CLI; the full list is in the CLI reference.

Requirements

• Node.js 18 or newer, or Bun 1.0 or newer
• Git
• Claude Code, if you want Troth to hand tasks to an agent for execution

Install

The npm package is troth-dev and the binary it installs is troth.

npm install -g troth-dev
# or
bun add -g troth-dev

To try it without installing anything globally:

npx troth-dev init
# or
bunx troth-dev init

Check the install:

troth --version

The package used to be called jig-dev

Troth was previously named Jig. The old package was jig-dev, the old CLI was jig, and project data lived in a .jig/ directory. Install troth-dev, not jig-dev. If you have an existing .jig/ directory, troth migrate-jig copies it into .troth/ without deleting the original.

Log in

Troth stores projects in the cloud, so authentication comes before initialization. troth init stops and asks you to log in if you have not.

troth login

This opens a browser for GitHub sign-in and waits for the callback on a local port. Two variations:

troth login --provider google      # sign in with Google instead
troth login --token <token>        # paste a token, for SSH or headless machines

If the browser does not open, the command prints the URL to visit. Credentials are stored encrypted under your home directory and refreshed automatically on later invocations.

Confirm it worked:

troth whoami

Initialize a project

From the root of the repository you want to track:

troth init

troth init walks through six steps: it checks for Bun and Git, confirms you are logged in, asks for a project name and the directory to scan, creates the .troth/ directory and its config.yaml, adds a Troth section to CLAUDE.md, installs a post-commit git hook that marks tasks from commit messages, registers the directory as a project, creates the matching cloud project, and offers to run a codebase scan.

Useful flags:

troth init --yes                   # accept defaults, no prompts
troth init --name my-project       # skip the name prompt
troth init --no-hooks              # do not install the git hook

Seed specs from the code

On an existing codebase, let Troth read the code before you write specs by hand:

troth bootstrap

By default this scans the repository and prints a decomposition prompt for you to hand to an agent. troth bootstrap --auto calls Claude directly and applies the generated specs; add --dry-run to see what it would create first.

You can also write a spec yourself:

troth spec new payments
troth spec list
troth spec show payments

A spec is markdown with sections for intent, architecture, key files, patterns, constraints, open questions, and acceptance criteria. Write the body with troth spec update payments --from-file spec.md.

Decompose a spec into tasks

troth decompose payments

Decomposition turns a spec into tasks, each with an objective, an intent, a file scope of one to five files, verification commands, and guardrails. Review what came out:

troth tasks payments
troth task show payments add-refund-endpoint

The work loop

This is the loop you will spend most of your time in.

troth next                                  # ready tasks in priority order
troth task start payments add-refund-endpoint
# ... do the work, or let Claude Code do it ...
troth task done payments add-refund-endpoint --notes "Changed: src/api/refunds.ts. Decisions: reused the existing idempotency key. Watch: no partial refunds yet."
troth next                                  # repeat

Every task ends with a status update. The three endings are:

troth task done <spec> <task> --notes "..."     # passed
troth task fail <spec> <task> --notes "..."     # something blocked it
troth task cancel <spec> <task> --notes "..."   # no longer relevant

troth task done runs the task’s verification gates first and refuses to pass a task whose gates fail. Use --skip-verify only when you know why you are skipping them.

To dispatch several agents at once, ask for tasks that do not overlap:

troth next --parallel 3

That filters for conflict-free file scopes and unmet dependencies, so the returned tasks are safe to run simultaneously.

Hand a task to Claude Code

troth run payments add-refund-endpoint

This builds the task’s prompt and pipes it to the claude CLI. Add --force to skip the dependency check.

File bugs and ideas

Anything you notice mid-flight goes into the findings pile instead of derailing the current task.

troth bug "Refund webhook retries forever when Stripe returns 409"
troth idea "Cache the spec index between CLI invocations"
troth findings                 # list the pile
troth findings --bugs          # bugs only

A finding can be confirmed, promoted into real work, or dismissed:

troth findings confirm <id>
troth findings promote <id> --target task --spec payments --objective "Stop retrying on 409"
troth dismiss <id>

Check where things stand

troth status                   # project-wide status
troth briefing                 # last decision, current drift, what changed
troth tree                     # spec and task hierarchy
troth search "refund"          # across specs, tasks, findings, decisions, requests

Learn the rest

troth guide                    # the full workflow reference, including the task YAML format
troth help                     # command list
troth <command> --help         # options for one command

Next: connect Troth to Claude so you can plan in a chat window and execute in the terminal against the same project.