conductor

README

Conductor

Conductor — talk to each AI agent individually while they work as a team

Each agent keeps its own conversation, context, and domain memory. They share what matters. When one publishes something the team needs, Conductor wakes the others.

No lead agent. No board. No broker. No server.

Everything is on disk. When no agent is active, neither is Conductor.

One task. Three contexts.

Three separate chats: Architecture, Development, and Skills. The user tells Architecture to start Development but hold the commit. Architecture publishes the handoff; the team wakes, and Development writes, then waits. The user tells Skills to finish the dependency. Skills publishes that it is ready; the team wakes again, and Development applies it and commits. Only the handoffs cross. Each agent keeps its own conversation and memories.

How it works

1. Each agent registers an identity and responsibility.
2. Each agent starts a background watcher to listen for publications.
3. The user establishes collaboration rules.
4. Every registered agent wakes and reads them.
5. An agent publishes a decision, question, finding, handoff, or result.
6. Every registered agent wakes and decides whether to act.

Only the result travels. Conversations and working context stay with the agent.

For details on how different AI harnesses wake and watch for publications, see the watcher documentation.

Easy Onboarding

• Install the skill: Follow the installation instructions to load the Conductor skill.
• Load base rules: Run the onboarding mode of the Conductor skill to register your identity and load the recommended base collaboration rules.

Configuration

The agent name is the one identity ever passed explicitly, as the leading argument to every command. Generic one-shot watchers need no conversation or thread identifier. The optional Claude CLI resume adapter reads CLAUDE_SESSION_ID, set automatically by its harness.

One environment variable remains genuinely optional configuration:

• CONDUCTOR_HOME — the state root directory, when a team uses one other than the default.

The optional claude adapter binary is found automatically — on PATH first, then at known install locations — with a clear error if neither resolves.

Use Conductor

Agents: follow the self-contained Conductor skill.

The skill is used in every environment. Harness integration changes only who waits for signals: the agent or its environment.

Guarantees

• Publications become visible atomically.
• Every registered agent is signaled, including the publisher.
• A crash can replay delivered work; it does not silently skip it.
• Nothing remains running between commands.

Limits

Conductor targets trusted, same-user agents on one Windows or Linux host. Delivery is at least once around crashes. History is not compacted automatically, and abandoned-transaction recovery occurs on the next operation.

Initial release: v0.1.0. Latest release: v0.4.0.

License

Apache License 2.0.

Architecture · State model · Runtime boundaries

Protocol · Suggested harness wake · Current limitations · Activity diagrams · Use cases

Documentation

Overview

Package conductor implements disk-backed coordination for independent agents. It has no server, resident process, message broker, or runtime dependency.

Index

• Constants
• func WriteJSON(writer io.Writer, value any) error
• type Agent
• type Client
  • func New(home, agent string) (*Client, error)
• type Delivery
• type DeliveryMode
  • func ParseDeliveryMode(value string) (DeliveryMode, error)
• type ProtocolError
• type ProtocolVersionDetail
• type Publication
• type ReadMode
• type ReadRequest
• type ReadResult
• type Record
• type Snapshot
• type Subscription
• type Summary

Constants

const (
	ReadRange = state.ReadRange
	ReadDelta = state.ReadDelta
	ReadFull  = state.ReadFull
)

const (
	DeliverySummary = state.DeliverySummary
	DeliveryContent = state.DeliveryContent
)

const CurrentProtocolVersion = state.CurrentProtocolVersion

Functions

func WriteJSON

func WriteJSON(writer io.Writer, value any) error

WriteJSON writes indented JSON followed by a newline.

Types

type Agent

type Agent = protocol.Agent

type Client

type Client = state.Client

Client is the public Conductor SDK client.

func New

func New(home, agent string) (*Client, error)

New opens a Conductor state root. An empty home uses ~/.conductor.

type Delivery

type Delivery = state.Delivery

type DeliveryMode

type DeliveryMode = state.DeliveryMode

func ParseDeliveryMode

func ParseDeliveryMode(value string) (DeliveryMode, error)

ParseDeliveryMode validates a --mode flag value. An empty value defaults to content.

type ProtocolError

type ProtocolError = protocol.Error

type ProtocolVersionDetail

type ProtocolVersionDetail = protocol.ProtocolVersionDetail

type Publication

type Publication = protocol.Publication

type ReadMode

type ReadMode = state.ReadMode

type ReadRequest

type ReadRequest = state.ReadRequest

type ReadResult

type ReadResult = state.ReadResult

type Record

type Record = protocol.Record

type Snapshot

type Snapshot = state.Snapshot

type Subscription

type Subscription = state.Subscription

type Summary

type Summary = protocol.Summary