---
title: "Linked Extension Development Workflow"
source: https://docs.autohand.ai/tutorials/extensions/linked-development-workflow
---

# Develop with links and live refresh

Use --link for a fast authoring loop without confusing linked source with the immutable copied artifact users will install.

## Understand linked state

A linked install places a directory link at the selected extension root and records `linked: true` in separate Autohand state. The authored package remains at its original path. Disable and enable update state only; removal deletes the registered link and state, not the source.

| Mode | Runtime reads | Best use | Release proof? |
|---|---|---|---|
| Linked | Your working directory | Fast editing and local iteration | No |
| Copied | A validated copy under the extension root | Normal use and immutable-version testing | Yes, with a fresh process |

## Install an explicit development link

``` bash
autohand extensions validate ./acme.code-health
autohand extensions install ./acme.code-health --link
autohand extensions show acme.code-health --json
```

Confirm `linked` is true and `root` resolves to the authored package. If a different package with the same id is installed, do not delete it manually; remove it deliberately or use `--replace` after reviewing the ownership change.

## Run the edit–validate–refresh loop

1.  Edit one declared tool or agent file.
2.  Run `autohand extensions validate ./acme.code-health` against source.
3.  Run `autohand extensions doctor` against the installed registry.
4.  In a normal active session, disable and re-enable the package to load a new complete snapshot.
5.  Repeat a focused smoke task and inspect the result.

``` text
/extensions disable acme.code-health
/extensions enable acme.code-health
/extensions show acme.code-health
/extensions doctor
```

Mutations refresh tools and agents in the active session transactionally. For prompt changes that could be affected by conversation context, start a new session after refresh.

## Recover from an invalid edit

Temporarily add an unknown field to a tool fixture or break a declared path. Validation should fail, and `doctor` should diagnose the installed linked package. Because a package activates as a unit, its other contributions should not remain partially active.

``` bash
autohand extensions validate ./acme.code-health --json
autohand extensions doctor --json
```

Restore the last valid file, validate again, then disable/enable. Do not edit files inside `~/.autohand/extensions`; the source directory is the authoring truth.

## Test removal safety

``` bash
autohand extensions remove acme.code-health --yes
test -d ./acme.code-health
autohand extensions list
autohand extensions doctor
```

The source-directory check should succeed. The installed registry should no longer list the package. If it does, use `show` with an explicit scope to find a second user or project installation.

## Prove a copied installation

After the linked loop passes, install a copy from a clean source checkout:

``` bash
autohand extensions validate ./acme.code-health
autohand extensions install ./acme.code-health
autohand extensions show acme.code-health --json
autohand extensions doctor --json
```

1.  Move or temporarily rename the source checkout; the installed package should remain usable.
2.  Start a new Autohand process.
3.  Exercise every contributed tool with expected approvals.
4.  Delegate one task to every contributed agent.
5.  Disable, enable, and remove the copied package.

**Release rule:** never publish from a tree that only passed linked testing. Copied installation catches undeclared files, path mistakes, and accidental dependencies on the authoring checkout.