Skip to content

PluggableHarness Agent#

The AI coding harness you never have to fork. A small Go microkernel owns plugin lifecycle, the plan/apply policy gate, configuration, and the session log — everything opinionated lives in out-of-process gRPC plugins.

Note

New here? Read in order: conventions (how these documents are written and cross-referenced), then the glossary, then the architecture narrative. Everything else branches from there.

Specifications#

The authoritative protocol contracts. RFC 2119 keywords are load-bearing; where anything else disagrees with these documents, these documents win.

Architecture

Microkernel philosophy, the seven plugin categories, Emit → Render → Paint, transport, registry, policy.

Agent loop

The kernel's turn algorithm, hook dispatch, plan/apply gate, sub-agents, and error recovery.

Configuration

agent.hcl, the policy DSL, agent profiles, settings and global config, the lock file.

Model provider

The LLM vendor plugin protocol — capabilities, streaming completion, token counting, pricing.

Tool provider

Tool plugins: resource, data_source, and interactive kinds, risk classes, and the reference catalog.

Context provider

Pre-model-call prompt injection: protocol, data types, and conformance.

Memory provider

Cross-session persistence and recall, plus the record taxonomy.

Frontend & widget

Frontend and widget plugin protocols and the shared render tree IR.

Slashcommand provider

Direct-invoke commands: a tool-shaped operation declared and executed in its own right.

Kernel callbacks

The plugin → kernel direction: RunSession, CountTokens, Emit, Log. See also the state backend.

First-party catalog#

Descriptive reference reports on the providers and tool capabilities the project ships or studies first-party — not protocol specs.

Model providers

Sourced capability data for Anthropic, OpenAI, Google, and xAI: rosters, reasoning, caching, wire formats.

Tools

Twenty-two capability reports, from file I/O and search through browser automation, MCP, and sub-agent spawning.

Sixty-second agent.hcl#

One file declares the whole harness — providers are versioned plugins, and policy gates every tool call:

required_providers {
  anthropic = {
    source  = "github.com/agentco/provider-anthropic"
    version = "~> 1.2.3"
  }
  filesystem = {
    source  = "github.com/agentco/provider-filesystem"
    version = "~> 1.0"
  }
}

provider "anthropic" {
  api_key = env("ANTHROPIC_API_KEY")
}

provider "filesystem" {
  roots = ["."]
}

policy "auto_approve_reads" {
  match  = { kind = "data_source" }
  action = "allow"
}

policy "gate_filesystem_writes" {
  match  = { provider = "filesystem", kind = "resource" }
  action = "ask"
}

agent_profile "default" {
  model {
    primary {
      provider = "anthropic"
      id       = "claude-opus-4-8"
    }
  }

  tools = ["filesystem.*"]
}

The full worked example, including fallback models and every block, lives in configuration examples.