---
title: "Build a Code Health Extension"
source: https://docs.autohand.ai/tutorials/extensions/code-health-extension
---

# Build the Code Health extension

Recreate the shipped autohand.code-health example and learn the basic pattern for bundling one deterministic tool with one specialist agent.

## Pattern under test

Code Health proves that a package can combine tool and agent contributions. The tool finds TODO/FIXME markers in Git-tracked content. The agent combines that output with file reads and search to prioritize maintainability risks.

``` text
autohand.code-health/
  autohand.extension.json
  README.md
  tools/find-todos.json
  agents/code-health-reviewer.md
```

## Create the exact reference manifest

``` json
{
  "$schema": "https://raw.githubusercontent.com/autohandai/code-extensions/main/schema/autohand.extension.schema.json",
  "schemaVersion": 1,
  "extensionApi": 1,
  "id": "autohand.code-health",
  "name": "Code Health",
  "version": "1.0.0",
  "description": "Find maintainability risks and delegate focused code-health reviews.",
  "license": "Apache-2.0",
  "repository": "https://github.com/autohandai/code-extensions",
  "contributes": {
    "tools": ["tools/find-todos.json"],
    "agents": ["agents/code-health-reviewer.md"]
  }
}
```

The manifest declares one contribution of each type. If either path is misspelled, the entire package is rejected; the valid contribution does not activate alone.

## Add the Git-aware discovery tool

``` json
{
  "name": "find_todos",
  "description": "Find TODO and FIXME comments under a path tracked by Git",
  "parameters": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Repository-relative file or directory"
      }
    },
    "required": ["path"]
  },
  "handler": "git grep -n -E 'TODO|FIXME' -- {{path}}",
  "source": "user"
}
```

`git grep` intentionally searches tracked content. The `--` separates revisions/options from the path argument. Autohand additionally shell-escapes the value, but this command structure keeps path intent visible to human reviewers.

## Add the reviewer

``` markdown
---
description: Review maintainability risks and prioritize focused cleanup
tools: read_file, fff_grep, find_todos
---
Review the requested code for correctness, unnecessary complexity, stale TODOs,
duplication, and maintainability risks. Preserve working contracts. Return a
prioritized set of specific findings with file evidence and the smallest safe
remediation for each finding.
```

The prompt distinguishes discovery from remediation. It asks for evidence and small safe changes rather than encouraging the agent to delete every TODO or launch an unbounded refactor.

## Validate and install at project scope

``` bash
autohand --path /work/sample extensions validate ./autohand.code-health
autohand --path /work/sample extensions install ./autohand.code-health --scope project
autohand --path /work/sample extensions show autohand.code-health --scope project
autohand --path /work/sample extensions doctor
```

Expected inspection: version `1.0.0`, project scope, enabled, copied, tool `find_todos`, and agent `code-health-reviewer`.

## Create a controlled fixture

In a disposable Git repository, add and commit a file containing one current TODO, one stale FIXME, and a nearby implementation. The expected output should include both markers with file and line context.

``` text
Ask Autohand:

Use code-health-reviewer on src/. Treat TODO and FIXME markers as leads,
not automatic defects. Read the surrounding implementation, rank only
evidence-backed risks, and make no edits.
```

Approve the `git grep` call if prompted. Confirm the reviewer reads context before assigning severity and distinguishes a tracked debt item from an actual correctness risk.

## Test failure and denial paths

-   Pass a nonexistent path and confirm the tool returns a truthful Git error.
-   Request an untracked file and confirm the documented tracked-content behavior.
-   Deny the tool permission and confirm the agent does not invent TODO results.
-   Create a standalone meta-tool named `find_todos` in an isolated profile and confirm `doctor` reports a conflict instead of replacing it.
-   Disable the package and confirm both contributions disappear together.

## Clean up

``` bash
autohand --path /work/sample extensions disable autohand.code-health --scope project
autohand --path /work/sample extensions enable autohand.code-health --scope project
autohand --path /work/sample extensions remove autohand.code-health --scope project --yes
```

The source package remains untouched. If you installed with a copy, only the installed project copy and separate state are removed.