> ## Documentation Index
> Fetch the complete documentation index at: https://jig-ui.fapost.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Connecting projects

> Add a Jig project to Jig UI and remove it again.

Jig UI shows the projects you connect on one page: each with its tasks counted and what waits for
you in it, a board of its tasks one click away, and each task's details from its card.

## Connect a project

Paste the path of the project's **main checkout** — the folder you cloned — into the field on the
page and choose **Connect**. A path inside the project works too; Jig UI connects the project's
root. `~/` stands for your home folder.

The project needs [Jig 0.29.0 or later](/requirements). Each project gets a short id from its
folder name (`My Project` becomes `my-project`, a second `api` becomes `api-2`); the page names
it by that id.

A path is refused when it is:

* **not inside a git repository**, or does not exist;
* **a worktree.** A task started in a worktree keeps its records in the main checkout, which lists
  every task of the clone. Connect the main checkout instead;
* **a repository without Jig.** Run `jig init` in it first.

Connecting a project that is already connected changes nothing.

## What the page shows

Each connected project, in the order you connected them. For a readable project:

* **Its live tasks counted** — `active`, `paused` and `ready` (finished tasks are not counted).
* **What needs you** — the same items `jig status` lists under "Needs you", most urgent first: a
  design waiting at its gate, a stopped autopilot run, a pull request waiting for review, a task to
  close. Each says what happened and what to do; a pull request comes with a link to it.
* **A note when pull request facts may be out of date.** Jig reads pull requests only during
  `jig housekeeping`; when its last run is old or the forge did not answer, a waiting pull request
  may be missing until you run it.

The page follows the projects while it is open — see [Staying current](#staying-current). A
project whose state is not readable shows why:

| Shown | Meaning |
| - | - |
| `Jig 0.29.0` | The project is connected and readable. |
| Answers in a form this Jig UI does not read | The project's Jig is newer than this Jig UI understands. Update Jig UI: `npx @fapost/jig-ui@latest`. |
| Jig could not be read | Jig refused the read — for example while an agent is writing to the project. The code in brackets is Jig's; the next change in the project tries again. |
| Jig UI needs 0.29.0 or later | The project's Jig is older than Jig UI reads. Run `jig upgrade` in the project; it is shown as readable once the upgrade lands, without connecting it again. |
| The project directory is not there any more | The folder was moved or deleted. Disconnect it, then connect its new path. |
| There is no Jig in the project any more | Jig was removed from the project. |

## The board

**Open board** on a readable project shows its live tasks in five columns. Jig UI works the
column out from the task's state in Jig every time it reads it, and stores it nowhere; the first
rule that fits wins:

| Column | A task is here when |
| - | - |
| Paused | it is paused (`jig task pause`) |
| Backlog | it is filed but not started (`jig task start` not run yet) |
| Needs you | its design waits at its gate, or changed after approval, or its autopilot run stopped with a question |
| Ready | its work is done (`status ready`); the card says whether a pull request is open, its CI, or merged |
| In progress | anything else that is live |

A card shows the task's id, class and goal, and what it waits for. Finished tasks are only
counted under the board. The order inside a column is Jig's (by id) for now.

## Task details

The task id on a card opens the task's details:

* **Where it stands** — its column, status, class, branch and the branch it lands on, how many
  files are uncommitted in its worktree, whether its knowledge decision is recorded, and when it
  was filed and last changed.
* **Its design gate** (T3 and T4) — waiting for approval, changed after approval, or approved.
* **Its autopilot run** — the stage it entered last and, when it stopped, the question it stopped
  on.
* **Its pull request** — open, merged or closed, its CI, and a link, as Jig's last
  `jig housekeeping` heard it.
* **What needs you** about it, and the housekeeping flags that still stand for it.
* **What Jig offers now** — each step Jig would accept on the task as it is (approve the design,
  answer the autopilot, pause, ship, close…) with the command to run in the project. Jig UI runs
  none of them; the page follows the change once you do.

Two things are not shown yet: which of the task's documents exist (Jig does not report them in a
form Jig UI reads) and dependencies between tasks (they come with Jig's task queue). A finished
task has no details page; its link says so.

## Staying current

While the page is open, Jig UI watches each connected project's `.ai/` folder. When an agent or
a person changes a task — through Jig, by editing a file, or with git (a pull, a checkout) — the
workspace and the board show it within about two seconds, without a reload. Every minute each
project is also read again, for a change the system did not report.

A read that fails while an agent is in the middle of writing does not blank the page: the last
good read stays until the next one. A project that keeps failing shows why, as in the table above.

Watching stops when the last page closes; nothing is written in the project. If the page says its
session has ended, Jig UI was restarted: run `npx @fapost/jig-ui` again to reopen it.

## Disconnect a project

**Disconnect** removes the project from Jig UI. Nothing in the project changes: Jig UI never
writes a file in a project.

## Where the list is kept

The list of connected projects is `projects.json` in Jig UI's config folder —
`~/.config/jig-ui/` (or `$XDG_CONFIG_HOME/jig-ui/`) on Linux and macOS, `%APPDATA%\jig-ui\` on
Windows. It survives a reinstall. If the file is damaged, Jig UI says so and leaves it as it is,
so you can fix or remove it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.