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

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
• 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 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:

ollama serve

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

npm install --global taskgrade
taskgrade setup
taskgrade doctor

Or run it without a global installation:

npx -y taskgrade setup
npx -y taskgrade doctor

Classify a task

From a file:

taskgrade classify issue.md
taskgrade classify issue.md --json

From stdin:

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:

{
  "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:

taskgrade init

This writes:

• taskgrade.config.json;
• taskgrade.policy.json.

Configuration precedence is:

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

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:

node dist/evaluate.js

See CONTRIBUTING.md and SECURITY.md.

License

Apache-2.0