# Repairing projects

Use `tessl project repair` when Tessl detects that the project identity for your current repository no longer matches the project it is linked to.

A Tessl project has two parts of identity:

* its **locator** — the project name in `tessl.json`
* its **source** — the repository Tessl sees for the current directory

If those drift apart, Tessl can stop evals from running until you repair the association.

### What `tessl project repair` does

`tessl project repair` helps you diagnose and fix **project identity drift** for the current repository.

Depending on the problem, you can use it to:

* inspect the current mismatch
* **relink** this repository to a different existing Tessl project
* **update the source** recorded for the currently matched Tessl project
* **update the project name** to match a local rename

### Start by diagnosing

Run this first:

```bash
tessl project repair
```

This checks the current repository and shows whether the problem is:

* a **locator drift**
* a **source drift**
* a **rename drift**
* a more complete mismatch that needs relinking or project creation

If you just want machine-readable output, use:

```bash
tessl project repair --json
```

### When to use each repair action

### Relink to a different project

Use this when your current repository is linked to the **wrong Tessl project**.

```bash
tessl project repair --relink --workspace <workspace> --project <project> --yes
```

Use `--relink` when:

* Tessl matched the wrong project
* your repository should belong to a different existing project
* you are in a monorepo and the current package or subpath was associated with the wrong project
* the locator in `tessl.json` is missing, stale, or points at the wrong project

#### Example: locator drift

Your current repository source matches an existing Tessl project, but the project named in `tessl.json` does not.

For example:

* local `tessl.json` does **not** point to the right project
* Tessl can see that the current repo actually matches `team-two/real-project`

In that case, relink the current repository to the correct project:

```bash
tessl project repair --relink --workspace team-two --project real-project --yes
```

### Update the source for the current project

Use this when the **project is correct**, but Tessl has the wrong **repository source** recorded for it.

```bash
tessl project repair --update-source --yes
```

Use `--update-source` when:

* the repo remote changed
* the repo was renamed or transferred
* the repo subpath changed in a way Tessl should now treat as the project’s canonical source
* Tessl found the right project by name, but the current repository source no longer matches the stored source

#### Example: repoistory name change

Your `tessl.json` still points to the correct project, but the underlying repository source has changed.

For example:

* locator: `team-one/old-name`
* recorded source: `https://github.com/acme/old-name`
* current local source: `https://github.com/acme/new-name`

In that case, keep the same project and update its recorded source:

```bash
tessl project repair --update-source --yes
```

Use this when the project identity is still right and only the source has drifted.

### Update the project name

Use this when the **repository is still linked correctly**, but the **project name has changed** locally.

```bash
tessl project repair --update-name --yes
```

Use `--update-name` when:

* you renamed the project in `tessl.json`
* the repo still matches the existing project source
* you want the Tessl project name to match the new local name

#### Example: rename drift

Your repository still matches the same project source, but the name in `tessl.json` changed.

For example:

* old name: `team-one/old-project`
* new local name: `team-one/renamed-project`

In that case, repair the name without relinking or recreating the project:

```bash
tessl project repair --update-name --yes
```

### How to decide which one to use

Use:

* `--relink` when the repository should point to a **different existing project**
* `--update-source` when the **project is right** but its **recorded source is outdated**
* `--update-name` when the **project is right** but its **name changed**

A simple rule:

* wrong project → **relink**
* wrong repo source → **update source**
* wrong project name → **update name**

### When repair is not the right command

You usually do **not** need repair when:

* you are creating a Tessl project for the first time
* there is no existing project association yet
* Tessl is asking you to create a project before your first eval

In those cases, use the normal create or link flow instead.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tessl.io/projects/repairing-projects.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.