convertible

One harness, many engines. A swappable coder-agent harness that turns any model into a repo worker behind a shared task contract.

How it works Features

The car around the model

Convertible is the chassis, controls, and handoff. The model is just the engine.

Engine

Model backend

The LLM or coder model — local vLLM, OpenAI, or any compatible endpoint.

Driver

Per-engine adapter

The code that invokes and controls one specific engine type.

Chassis

Shared task contract

Typed Task → TaskResult lifecycle every engine shares.

Tool-loop

Bounded agentic loop

The engine drives the repo through read/write/command tools until done or budget hit.

Wheels

Pluggable engines

Replaceable engine plugins discovered via Python entry points.

Dashboard

JSON result artifact

Every run writes a structured result with step trace for downstream handoff.

GPS

OpenTelemetry

Opt-in traces and metrics over OTLP — off by default, strict no-op when disabled.

Key features

Everything ships in the chassis — no engine-specific code paths.

⇄

Swappable engines

Swap mock for vllm-openai or any future wheel — same CLI, same contract.

⎇

Git / PR handoff

Branch → commit → push → gh pr create, gated for offline and CI.

📜

Command templates

Reusable, parameterized task recipes under .convertible/commands/*.md.

🪝

Lifecycle hooks

Shell commands at task_start, pre_tool, post_tool, and finish — allow, deny, or rewrite.

🧅

Layered per-model config

AGENTS instructions and skills compose per model with strict isolation.

0️⃣

Zero runtime dependencies

The base install has no third-party deps. Optional [otel] extra for telemetry.

Quickstart

Drive a task with the deterministic mock engine — no model, no network.

# Discover installed engines
uv run convertible wheels list

# Run a task with the mock engine
uv run convertible drive "add a CONTRIBUTING.md stub" \
  --repo . --engine mock --no-pr

# Open the interactive palette
uv run convertible session