ConferLLM

ConferLLM is a minimalist agent harness with multi-model support and essential host tools. It enables AI agents (such as Claude Code, Codex, Cursor, and Cline) and human developers to consult, delegate, and collaborate across models on complex tasks with full session state and local execution capabilities.

┌──────────────────────────────────────────────────────────────────────────────┐
│  AI Agent / Developer (Claude Code, Codex, Cursor, CLI, Script)             │
└──────────────────────────────────────┬───────────────────────────────────────┘
                                       │ CLI (--json) or MCP (stdio/sse/http)
                                       ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│  ConferLLM Engine                                                            │
│  • Stateful Session Store (atomic JSONL + fcntl locking)                     │
│  • Self-Correcting Tool Runtime (up to 1,000 tool rounds per turn)           │
│  • Multimodal Pipeline (artifact tracking + auto-saving)                     │
└──────────────┬───────────────────────────────────────────────┬───────────────┘
               │ Native Tool Calls                             │ LiteLLM /
               ▼                                               │ Responses API
┌──────────────────────────────┐                ┌──────────────▼───────────────┐
│ Host Tools (Unrestricted)    │                │ Configured AI Models         │
│ • Shell: bash, pwsh, git     │                │ • OpenAI GPT-6 Astra         │
│ • Background: output, kill   │                │ • Claude Opus/Sonnet         │
│ • Files: read, write, edit,  │                │ • DeepSeek Flash / Pro       │
│   append, list_directory     │                │ • Google Gemini              │
│                              │                │ • Local Ollama               │
└──────────────────────────────┘                └──────────────────────────────┘

---

Highlights

• Multi-Model Delegation: Connect to 100+ providers via LiteLLM (OpenAI, Anthropic, Gemini, DeepSeek, local Ollama, Azure, Bedrock, etc.) using clean local aliases.
• 10 Native Built-in Host Tools: Delegated models get access to shell (run_shell, run_powershell, shell_output, shell_kill, git_command) and filesystem tools (read_file, write_file, append_file, edit_file, list_directory) without extra flags.
• Self-Correcting Tool Loop: Tool execution errors are returned as native results so the model can inspect errors and self-correct across up to 1,000 rounds in a single turn.
• Persistent Multi-Turn Sessions: Conversations are stored as atomic JSONL files with process-safe locking. Resume any session at any time with --session <id>.
• First-Class Multimodal Support: Send input images (--image); model-generated images are automatically saved to disk, linked via URIs, and safely replayed in history.
• Agent-Ready Surfaces: Dual interface out of the box—bundled Agent Skill (conferllm skill install) for Claude Code/Codex and standard MCP Server (conferllm serve) for Claude Desktop/Cursor/Cline.

---

Quick Start

Requires Python 3.10+ on macOS or Linux (POSIX file locking required; native Windows is not supported).

1. Install

Install with uv (recommended):

uv tool install conferllm

Or install with pip in an activated virtual environment:

pip install conferllm

Verify the installation:

conferllm --version
conferllm doctor --json

Note: If the command is not found after uv tool install, run uv tool update-shell and restart your terminal.

2. Configure Models

Create the configuration directory and file:

mkdir -p ~/.conferllm
chmod 700 ~/.conferllm
touch ~/.conferllm/config.yaml
chmod 600 ~/.conferllm/config.yaml

Populate ~/.conferllm/config.yaml with your preferred providers. For example:

model_list:
  - model_name: gpt-6-astra
    api_format: responses
    capabilities:
      input_modalities: [text, image]
      output_modalities: [text]
    litellm_params:
      model: openai/gpt-6-astra
      api_key: "your-openai-key"

  - model_name: claude-opus-5
    capabilities:
      input_modalities: [text, image]
      output_modalities: [text]
    litellm_params:
      model: anthropic/claude-opus-5
      api_key: "your-anthropic-key"

  - model_name: DeepSeek-V4.1-Flash
    capabilities:
      input_modalities: [text, image]
      output_modalities: [text]
    litellm_params:
      model: deepseek/deepseek-flash
      api_key: "your-deepseek-key"

  - model_name: gemini-3.8-flash
    capabilities:
      input_modalities: [text, image]
      output_modalities: [text]
    litellm_params:
      model: gemini/gemini-3.8-flash
      api_key: "your-gemini-key"

  - model_name: local-qwen3
    litellm_params:
      model: ollama_chat/qwen3-coder:30b
      api_base: "http://localhost:11434"

Tip: See config_example.yaml for more provider templates including Gemini 3.8 Flash, Qwen 3 Coder, Mistral Large, Together AI, Hugging Face, Azure, and AWS Bedrock.

3. Run Your First Chat

conferllm chat --model gpt-6-astra --prompt "Explain Raft leader election in two sentences."

Output includes the answer and a reusable Session ID:

Session: 20260905-0123456789abcdef0123456789abcdef
Name: Explain Raft leader election in two sentences.

Raft leader election ensures a cluster chooses a single leader through randomized election timeouts and majority voting. Nodes transition to candidates, request votes, and become leaders upon securing a majority.

---

AI Agent Integration

ConferLLM is designed from the ground up for agent consumption. AI agents use ConferLLM to obtain attributed second opinions, delegate specialized tasks (e.g., deep math proofs to DeepSeek V4.1 Flash, visual analysis to GPT-6 Astra, or private offline tasks to local Llama 4), and let external models interact with the host repository.

Option A: Use as an Agent Skill (Claude Code & Codex)

Install the bundled skill into your agent's skill directory:

# For Claude Code and general agents (~/.agents/skills/conferllm):
conferllm skill install

# For Codex (~/.codex/skills/conferllm):
conferllm skill install --target codex

Once installed, your agent automatically knows how to discover configured models, run queries with --json, parse outputs, and continue conversations.

Example agent instruction:

"Use $conferllm to ask DeepSeek-V4.1-Flash to review our Raft consensus implementation in src/consensus.py and check for election split-vote edge cases."

Option B: Use as an MCP Server (Claude Desktop, Cursor, Cline, Windsurf)

ConferLLM includes a full-featured MCP (Model Context Protocol) server over stdio, SSE, or streamable HTTP.

Add to your MCP configuration (e.g. claude_desktop_config.json or Cursor Settings):

{
  "mcpServers": {
    "conferllm": {
      "command": "conferllm",
      "args": ["serve"]
    }
  }
}

MCP Tools Provided

| MCP Tool | Description | | --- | --- | | create_chat(message, model, name=None, images=None, ...) | Start a new conversation with host shell and file tools enabled. | | continue_chat(message, session_id, images=None, ...) | Continue an existing session with conversation history restored. | | list_sessions(query=None, model=None, since=None, until=None, limit=50) | Search past sessions by ID, name, model, or creation date. | | list_models() | Return all configured model aliases. | | get_model_info(model) | Return declared capabilities, modalities, and format details. |

Generated images are accessible via the MCP resource conferllm://sessions/{session_id}/artifacts/{artifact_id}.

---

Common Workflows

1. Multi-Turn Conversation (Follow-Up)

Pass --session with the returned session ID to continue with full context:

conferllm chat --session 20260905-0123456789abcdef0123456789abcdef --prompt "Now compare it with Paxos."

Note: A session retains its original model alias. History and past tool calls are restored automatically without re-executing old commands.

2. Machine-Readable JSON Mode

AI agents and scripts should always pass --json for predictable parsing:

conferllm chat --model gpt-6-astra --prompt "Explain Raft." --json

JSON Response Contract (conferllm.chat.response.v1):

{
  "schema_version": "conferllm.chat.response.v1",
  "ok": true,
  "session": {
    "id": "20260905-0123456789abcdef0123456789abcdef",
    "name": "Explain Raft.",
    "model": "gpt-6-astra",
    "turn": 1
  },
  "message": {
    "text": "Raft is a consensus algorithm...",
    "content": [
      {
        "type": "text",
        "text": "Raft is a consensus algorithm..."
      }
    ]
  },
  "artifacts": [],
  "warnings": []
}

Key fields:

• session.id: Unique session identifier to pass to --session on follow-up.
• session.turn: Turn counter (starts at 1).
• message.text: The complete assistant answer (with image payloads replaced by saved paths).
• artifacts: List of turn artifacts (images input/output, paths, mime types, hashes).
• warnings: Non-fatal notices (e.g. background processes stopped at turn end).

3. Long Prompts from Files

For complex multi-line prompts, markdown instructions, or code snippets:

conferllm chat --model DeepSeek-V4.1-Flash --prompt-file ./review_prompt.md --json

4. Multimodal Analysis (Images)

Attach one or more images using repeated --image flags:

conferllm chat \
  --model gpt-6-astra \
  --prompt "Analyze the architectural bottleneck shown in this diagram." \
  --image ./architecture.png \
  --json

• Images are validated against model capabilities and copied into session-owned storage for safe replay across turns.
• Model-generated images are automatically written to --image-output-dir (defaults to /tmp) and listed in artifacts with direction: "output".

5. Local File and Shell Operations

Delegated models have native access to host files and commands without extra flags:

conferllm chat \
  --model gpt-6-astra \
  --prompt "Read pyproject.toml and tell me what dependencies need attention." \
  --json

Safety note: If you want an opinion or review only without risking file modifications, include in your prompt: "Provide an analysis only; do not edit files or execute modifying commands."

6. Search and Inspect Past Sessions

# List recent sessions
conferllm sessions list

# Search by keyword in name or ID
conferllm sessions list --query raft --json

# Filter by model alias and date range
conferllm sessions list --model gpt-6-astra --since 2026-09-01 --limit 10 --json

7. Compare Models Side-by-Side

To compare how different models handle the same challenge, start independent chats:

conferllm chat --model DeepSeek-V4.1-Flash --prompt-file ./challenge.md --json
conferllm chat --model claude-opus-5 --prompt-file ./challenge.md --json

---

Built-in Host Tools

ConferLLM provides every configured model with 10 native tools. Native tool calls execute on the host machine with the user's OS permissions:

| Tool | Purpose | Key Parameters | | --- | --- | --- | | run_shell | Run bash/sh commands | command, timeout (1–600s, def 120s), cwd, run_in_background | | run_powershell | Run PowerShell commands | command, timeout, cwd, run_in_background | | `shel