OPENCONFER / AGENT DOCUMENT

# OpenConfer

> Human Decision Infrastructure for autonomous AI agents.

When an AI agent reaches a decision it should not make alone, OpenConfer lets the agent contact a human, discuss the situation naturally, capture a confirmed structured outcome, return that result to the originating workflow, and resume the agent's work.

- Website: https://openconfer.com
- Source: https://github.com/richardsondx/OpenConfer
- License: Apache 2.0
- Deployment: self-hosted
- Compatibility: model-agnostic and transport-agnostic
- Hosted cloud product: not available yet

## The key distinction

OpenConfer is not a general-purpose platform for building voice agents. Voice is one possible interface for resolving a decision inside an existing autonomous workflow.

The complete loop is:

1. An agent works inside an existing thread or run.
2. The agent reaches a decision boundary and creates a confer session with the relevant context.
3. OpenConfer contacts the authorized human through a configured channel.
4. The agent and human discuss the decision by voice or use the text fallback.
5. The human confirms an outcome.
6. OpenConfer returns structured context to the exact workflow that requested it.
7. The agent acknowledges the result and resumes work.

Typical session progression:

`created -> agent_waiting -> human_contacted -> active -> decision_confirmed -> result_delivered -> agent_resumed`

## Install from source

Requirements: Node.js 20 or newer and pnpm. Enable pnpm with `corepack enable` if needed.

```bash
git clone https://github.com/richardsondx/OpenConfer.git
cd OpenConfer
pnpm setup
```

The setup command builds the repository and installs the `openconfer` command to `~/.local/bin/openconfer`.

If the command is not found, add the installation directory to your shell path:

```bash
export PATH="$HOME/.local/bin:$PATH"
```

## Initialize and run

```bash
openconfer --version
openconfer init
openconfer doctor
openconfer serve
```

In a second terminal, start the operator interface:

```bash
openconfer web
```

Open http://127.0.0.1:5173 and enter the access key printed by `openconfer init`. The key can be printed again with `openconfer token`.

To connect Hermes:

```bash
openconfer connect hermes
```

## Useful CLI commands

```bash
openconfer init
openconfer serve
openconfer web
openconfer doctor
openconfer session create --file session.json
openconfer session wait SESSION_ID
openconfer session result SESSION_ID
openconfer session ack SESSION_ID
openconfer events tail --session SESSION_ID
```

## Protocol and runtime

OpenConfer is both a protocol and a runtime.

The protocol defines:

- how an agent requests a human session;
- the objective, urgency, context, continuation identity, and preferred channel;
- valid session states and transitions;
- how a confirmed outcome is represented and returned.

The runtime:

- contacts the human;
- manages the browser, phone, voice, or configured transport;
- maintains session state and continuity;
- captures and confirms the decision;
- delivers the structured result to the originating agent;
- allows the agent to acknowledge the result and resume.

## Configurable layers

- Model: use an open, local, or hosted model for the conversation.
- Voice: choose the speech pipeline and voice.
- Channel: use an in-browser voice session, phone call, text fallback, or custom transport.
- Policy: control which agents may contact which people, with what urgency and context.

Voice transport and conversation intelligence are separate. The current runtime can use a LiveKit room for audio transport and an OpenAI Realtime speaking agent. Text decision forms remain available when voice is unavailable.

## Agent and harness compatibility

OpenConfer is designed for Hermes, OpenClaw, Codex, Claude Code, MCP-based tools, and custom agent harnesses. It does not orchestrate those agents; it supplies a human-decision interface they can invoke from an existing run.

## Good use cases

- deployment and migration approvals;
- incident-response decisions;
- architecture and implementation tradeoffs;
- briefings that require human direction;
- policy-controlled escalation from an autonomous workflow.

## Structured outcome example

```json
{
  "decision": "approve",
  "conditions": ["feature_flag", "monitor_10m"],
  "confirmed_by": "human",
  "continuation": "run_7f31"
}
```

The exact schema and integration examples live in the canonical repository. Agents should inspect the current repository documentation before generating production configuration or relying on a specific API field.

## Links

- Repository and documentation: https://github.com/richardsondx/OpenConfer
- Issues: https://github.com/richardsondx/OpenConfer/issues
- Richardson Dackam on GitHub: https://github.com/richardsondx
- Richardson Dackam on X: https://x.com/richardsondx
- Agent-readable summary: https://openconfer.com/llms.txt
- Full agent-readable document: https://openconfer.com/llms-full.txt