RalphTUI

Plugin Architecture

Understanding Ralph TUI's plugin system for agent and tracker integrations.

Plugin Architecture

Ralph TUI uses a plugin system to support multiple AI agents and task trackers. This modular design lets you choose the tools that best fit your workflow.

INFO

Plugins are independent - any agent can work with any tracker. Use Claude Code with Beads, or OpenCode with prd.json, or any combination.

Two Plugin Types

Ralph TUI has two categories of plugins:

Agent Plugins

Agent plugins connect to AI coding assistants that execute tasks. They handle:

  • Detecting if the agent CLI is installed
  • Building command-line arguments from prompts
  • Streaming output in real-time
  • Managing execution lifecycle (start, interrupt, timeout)
  • Model selection and configuration

Built-in agents:

  • Claude Code - Anthropic's Claude CLI with subagent tracing
  • OpenCode - Open-source multi-provider agent with subagent tracing
  • Factory Droid - Factory Droid CLI (no subagent tracing)

Tracker Plugins

Tracker plugins connect to task management systems. They handle:

  • Fetching available tasks
  • Selecting the next task (respecting priorities and dependencies)
  • Updating task status (in progress, completed)
  • Syncing with external systems

Built-in trackers:

  • JSON - Simple prd.json file format (no dependencies)
  • Beads - Git-backed issue tracker with hierarchy
  • Beads-BV - Beads with graph analysis for smart task selection

How Plugins Work Together

┌─────────────────────────────────────────────────────────────────┐
│                         Ralph TUI                               │
│                                                                 │
│  ┌──────────────┐                         ┌──────────────┐     │
│  │   Tracker    │──── Get Next Task ─────▶│   Engine     │     │
│  │   Plugin     │◀─── Update Status ──────│              │     │
│  └──────────────┘                         └──────┬───────┘     │
│                                                  │              │
│                                           Build Prompt          │
│                                                  │              │
│                                                  ▼              │
│                                          ┌──────────────┐      │
│                                          │    Agent     │      │
│                                          │    Plugin    │      │
│                                          └──────────────┘      │
└─────────────────────────────────────────────────────────────────┘

The execution engine orchestrates plugins:

  1. Tracker provides the next task (highest priority, no blockers)
  2. Engine builds a prompt from task data + Handlebars template
  3. Agent executes the prompt and streams output
  4. Engine detects completion via <promise>COMPLETE</promise>
  5. Tracker marks the task as complete
  6. Repeat until no tasks remain

Plugin Comparison

Agents

FeatureClaude CodeOpenCodeFactory Droid
ProviderAnthropicMulti-providerFactory
Modelssonnet, opus, haikuAny via provider/model formatFactory model list
Subagent TracingYes (Task tool)Yes (Task tool)No
File ContextYes (--add-dir)Yes (--file)No (uses --cwd)
StreamingYesYesYes
Installationnpm i -g @anthropic-ai/claude-codecurl -fsSL https://opencode.ai/install | bashFactory Droid CLI

Trackers

FeatureJSONBeadsBeads-BV
External CLINonebdbd + bv
DependenciesYesYesYes
Priority OrderingYesYesYes + PageRank
Hierarchy (Epics)NoYesYes
Graph AnalysisNoNoYes
Git SyncNoYesYes
Setup ComplexityLowestMediumHighest

Choosing Plugins

Start with the JSON tracker and Claude Code agent:

Bash
ralph-tui run --prd ./prd.json --agent claude

No external dependencies needed - just create a prd.json file and go.

Configuration

Quick Setup

Set default plugins in your config file:

TOML
# .ralph-tui/config.toml
agent = "claude"
tracker = "json"
 
[agentOptions]
model = "sonnet"

CLI Override

Override config with CLI flags:

Bash
ralph-tui run --agent opencode --tracker beads-bv --epic my-epic

Multiple Plugin Configs

Configure multiple instances for flexibility:

TOML
# Define two agents
[[agents]]
name = "claude-fast"
plugin = "claude"
[agents.options]
model = "haiku"
 
[[agents]]
name = "claude-smart"
plugin = "claude"
default = true
[agents.options]
model = "opus"
 
# Switch between them
# ralph-tui run --agent claude-fast

Plugin Interface

All plugins implement standard interfaces defined in the source:

  • AgentPlugin: src/plugins/agents/types.ts
  • TrackerPlugin: src/plugins/trackers/types.ts

Key methods for agents:

  • detect() - Check if CLI is available
  • execute(prompt, files, options) - Run the agent
  • interrupt(executionId) - Stop execution

Key methods for trackers:

  • getTasks(filter) - Get all matching tasks
  • getNextTask(filter) - Get highest priority ready task
  • completeTask(id, reason) - Mark task done
  • updateTaskStatus(id, status) - Update task state

Next Steps

Learn about specific plugins: