# TaskGrade

TaskGrade is a local-first classifier for software implementation tasks. It uses
an Ollama model to grade task characteristics, then applies a deterministic,
editable policy to recommend coding-agent models.

It is designed for issue trackers, planning workflows, and agent handoffs where
the cheapest model that can reliably complete the whole task is preferable to
using the most expensive model by default.

## How it works

```text
Issue or task text
        ↓
Local Ollama classifier
        ↓
Structured task grade
        ↓
Deterministic model policy
        ↓
Primary, fallback, escalation, and turn budget
```

The classifier never invents model identifiers. Available models, usage pools,
strength ordering, and routing rules come from a versioned JSON policy.

## Requirements

- Node.js 20.19 or newer
- [Ollama](https://ollama.com/)
- Enough local memory for the selected model

The bundled preset defaults to `qwen3.5:9b`. Model weights are not included in
the npm package and are never downloaded during installation.

## Install

First, [install Ollama](https://ollama.com/download) and ensure its local server
is running. The Ollama desktop application starts the server automatically. If
you use the CLI without the desktop application, start it in a separate
terminal:

```sh
ollama serve
```

Then install TaskGrade, download its default classifier model through Ollama,
and verify the complete setup:

```sh
npm install --global taskgrade
taskgrade setup
taskgrade doctor
```

Or run it without a global installation:

```sh
npx -y taskgrade setup
npx -y taskgrade doctor
```

## Classify a task

From a file:

```sh
taskgrade classify issue.md
taskgrade classify issue.md --json
```

From stdin:

```sh
gh issue view 42 --json title,body | taskgrade classify --json
```

TaskGrade accepts task content; it does not authenticate to GitHub or mutate an
issue tracker.

## MCP server

Add a local stdio server to an MCP-compatible host:

```json
{
  "mcpServers": {
    "taskgrade": {
      "command": "npx",
      "args": ["-y", "taskgrade", "mcp"]
    }
  }
}
```

The server exposes:

- `grade_task` — classify task content and return a model recommendation;
- `taskgrade_health` — inspect configuration, policy, Ollama, and model status.

`grade_task` accepts `title`, `body`, optional `comments`, optional
`planningContext`, and optional `sourceId`.

## Customize the policy

Create editable local configuration and policy files:

```sh
taskgrade init
```

This writes:

- `taskgrade.config.json`;
- `taskgrade.policy.json`.

Configuration precedence is:

```text
CLI flags → TASKGRADE_* environment variables → local config → bundled defaults
```

Supported environment variables:

| Variable | Purpose |
| --- | --- |
| `TASKGRADE_OLLAMA_URL` | Ollama base URL |
| `TASKGRADE_MODEL` | Classifier model |
| `TASKGRADE_TIMEOUT_MS` | Request timeout |
| `TASKGRADE_MAX_INPUT_CHARACTERS` | Explicit input safety limit |
| `TASKGRADE_POLICY_PATH` | Routing policy path |

The bundled `coding-agents-2026-07` policy is an editable example, not a
universal benchmark. Its model catalog will age; copy and maintain it for the
agent products and quota pools available to you.

## Failure behavior

TaskGrade:

- rejects oversized input instead of silently truncating it;
- gives Ollama one repair attempt after invalid structured output;
- does not retry connection failures indefinitely;
- returns no recommendation for non-actionable tasks;
- rejects unknown models, same-pool fallbacks, and invalid escalation ordering;
- treats issue content as untrusted data rather than classifier instructions.

CLI exit codes:

| Code | Meaning |
| ---: | --- |
| `2` | Invalid command usage |
| `3` | Invalid input, configuration, or policy |
| `4` | Ollama unavailable, timed out, or model missing |
| `5` | Invalid classifier response |

## What TaskGrade is not

TaskGrade does not:

- execute coding agents;
- proxy or route LLM API traffic;
- monitor subscription quotas;
- fetch or update GitHub issues;
- train a classifier;
- send telemetry;
- bypass local model safeguards.

Its only runtime network dependency is the configured Ollama endpoint.

## Development

```sh
npm install
npm run check
npm test
npm run build
npm run pack:check
```

Run the non-CI local evaluation corpus after installing the default model:

```sh
node dist/evaluate.js
```

See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).

## License

Apache-2.0