DOCSEARCHbyAlgolia
Submit Docs

OpenAgents Control (OAC) Documentation

repository·main·Indexed 26 days ago

https://github.com/darrenhinde/openagentscontrol

An AI agent framework for plan-first development workflows with approval-based execution, extending the OpenCode framework to provide repeatable, pattern-aware coding assistance. It features a System Builder for generating production-ready .opencode AI systems tailored to specific domains, an Evaluation SDK for testing agent behavior against rule validators, and multi-language support for TypeScript, Python, Go, and Rust.

Tokens
196.5K
Snippets
511
Records
992
Agent score
86%

What's inside OpenAgents Control

  1. Overview of System Builder Components

    main

    The Context-Aware System Builder uses a hierarchical coordination pattern to generate AI systems. The core components are:

    • Slash Command (/build-context-system): The entry point located at .opencode/command/build-context-system.md that coordinates the interview.
    • Main Orchestrator (system-builder): Located at .opencode/agent/system-builder.md, it manages the end-to-end generation workflow from requirement analysis to system delivery.
    • Specialized Subagents: A suite of expert agents that handle specific generation tasks:
      • domain-analyzer: Identifies core concepts and recommended agent specializations.
      • agent-generator: Creates XML-optimized agent files using hierarchical context structures.
      • context-organizer: Generates modular knowledge base files (domain, processes, standards, and templates).
      • workflow-designer: Designs workflow definitions with context dependencies.
      • command-creator: Creates custom slash commands with syntax and examples.
    • Template Library: Reusable XML patterns located in .opencode/context/system-builder-templates/ to ensure high-quality generation.

  2. Overview of the Context System Implementation Plan

    main

    The Context System is designed to make context management simple, reliable, and efficient by standardizing file governance, introducing ADR-style (Architecture Decision Record) decision memory, and providing lightweight CLI/agent workflows with strict validation.

    Core Principles:

    • File-first truth: Markdown context files are the canonical source of truth.
    • Deterministic operations: Inputs result in consistent validation and indexing outcomes.
    • Minimal Viable Information (MVI): Context is kept concise, scannable, and reference-heavy.
    • Navigation-first retrieval: The system loads indexes/navigation before deep files to reduce token load.
    • Conflict safety: Uses explicit permissions and supersession rules to manage decision conflicts.

  3. Overview of OAC core concepts

    main

    OpenAgents Control (OAC) is designed for developers who need repeatable, consistent AI results that adhere to established coding standards.

    Key Features:

    • Approval Gates: Agents always request approval before executing actions like writing, editing, or running bash commands.
    • Context System: Uses the MVI (Minimal Viable Information) principle to load only necessary context, preventing token bloat.
    • ContextScout: A smart pattern discovery agent that finds and ranks relevant context files before code generation.
    • Model Agnostic: Supports any model provider (Claude, GPT, Gemini, MiniMax, or local models) to prevent vendor lock-in.

  4. Overview of the Eval Pipeline Architecture

    main

    The OpenCode evaluation framework follows a linear pipeline from agent execution to reporting. The core components involved are:

    1. TestRunner: Orchestrates the overall test process.
    2. TestExecutor: Handles the execution of individual test cases.
    3. Agent Execution: The actual running of the AI agent.
    4. Session Data: Captured output from the agent.
    5. SessionReader: Retrieves session data from storage.
    6. TimelineBuilder: Constructs event timelines from the session data.
    7. EvaluatorRunner: Executes multiple evaluators (e.g., ApprovalGate, ContextLoading, ToolUsage) and aggregates their results.
    8. Aggregated Results: Final pass/fail determination and score calculation.
    9. Report Generation: Produces text reports or batch summaries.

  5. Analyze Content Creator UX Requirements in OAC

    main

    This document outlines the user experience (UX) analysis for non-technical content creators (bloggers, marketers, technical writers) using OpenAgents Control (OAC). It identifies critical barriers to entry for these users, such as the intimidating CLI interface, technical installation processes, and developer-centric error messages.

    Key areas for improvement identified include:

    • Providing visual feedback for writing workflows.
    • Simplifying context management (e.g., brand guidelines, style guides).
    • Improving error messaging to avoid developer jargon.
    • Implementing easier 'undo' mechanisms for draft iterations.

  6. Understand OpenCode Directory Structures

    main

    OpenCode uses two distinct directory structures depending on whether you are working within a local repository or using a global installation. Understanding these is critical for correct path resolution of agents, commands, and context files.

    Local Repository Structure

    When working within a specific git repository, all OpenCode-related files are stored in a .opencode/ directory at the repository root.

    • Location: {repo-root}/.opencode/
    • Subdirectories: agent/, command/, context/, plugin/, tool/

    Global Installation Structure

    Global configurations and shared assets are stored in the user's home directory.

    • Global Configuration Location: ~/.config/opencode/ (contains opencode.json, config.json, plugins, providers)
    • Authentication & Data Location: ~/.local/share/opencode/ (contains auth.json, bin, log, project, snapshot, storage)

  7. Understand Tool Blocking and Enforcement

    main

    When an ability is running a script step, the plugin enforces strict control by blocking most tools to prevent improvisation.

    Blocked Tools: Most tools (e.g., bash, python, etc.) are BLOCKED while a step is active.

    Allowed Tools (Exceptions):

    • ability.list
    • ability.status
    • ability.cancel
    • Read-only tools: read, glob, grep

    Context Injection: Every chat message automatically includes the ability status, progress, and a warning that enforcement is active.

  8. Understand the OAC Agent Configuration Architecture

    main

    OpenAgents Control (OAC) uses a single source of truth for agent management located in the .opencode/ directory. This architecture separates agent metadata (JSON) from human-readable instructions (Markdown) to ensure type safety and multi-IDE compatibility.

    Directory Structure:

    • .opencode/agents/core/ : Contains primary agents (e.g., openagent/).
    • .opencode/agents/subagents/ : Contains specialized agents (e.g., code-reviewer/).
    • .opencode/agents/manifest.json : A registry of all agents.
    • Each agent directory contains:
      • agent.json: Configuration (metadata, permissions, tools).
      • prompt.md: The main prompt content.
      • system.md (optional): System instructions.
      • examples.md (optional): Few-shot examples.

    The OAC CLI converts these universal formats for use in different IDEs like OpenCode (native), Claude Code (converted), Cursor (flattened), and Windsurf (flattened).

  9. Understand OpenCode Context Construction

    main

    Every message sent to OpenCode builds a context (a brief for the AI) consisting of several components. This total token count determines the cost and performance of your requests.

    Context Components:

    1. Header: Model identity (e.g., "You are Claude").
    2. Base Prompt: Large instruction set (varies by model, e.g., anthropic.txt, beast.txt, codex.txt).
    3. Environment: Current working directory, project tree, date, and platform info.
    4. Custom Instructions: Local files like AGENTS.md or CLAUDE.md, or global ~/.claude/CLAUDE.md.
    5. Tools: Definitions for enabled tools (e.g., 16 tools totaling ~6,600 tokens).
    6. Your Message: The actual prompt you send.

  10. Review OAC Core Features

    main

    The OpenAgents Control system provides several critical capabilities for managing AI agents:

    • User Approval System: Interactive approval for file operations, with a YOLO mode for automated/power-user workflows, including backup and rollback support.
    • Multi-IDE Support: Optimized support for OpenCode and Claude Code, with optimized/partial support for Cursor and Windsurf.
    • Agent Customization: Support for personal presets, safe editing workflows, and preset sharing.
    • Discovery & Browse: An interactive TUI (Terminal User Interface) browser for searching and previewing components.
    • Security & Verification: Component signing, checksum verification, malware scanning, and secret detection.
    • Lockfile & Reproducibility: Version locking and frozen installs to ensure reproducible environments.
    • Component Creation: Interactive wizards and template systems for auto-scaffolding new components.

  11. Understand the OAC Context Discovery Protocol

    main
    The OAC Context Discovery Protocol is the single source of truth for locating the context root in a project. It is used by the context-scout agent and the context-discovery skill to find documentation and standards. The protocol follows a tiered approach: first checking for an existing .oac.json file (the fast path), and if not found, executing a discovery chain to locate a navigation.md file in specific directories.

  12. Understand the Evaluation Framework directory structure

    main

    The framework is organized as follows:

    • evals/framework/: Core framework source code (evaluators, SDK, types).
    • evals/agents/: Agent-specific test suites (e.g., openagent, opencoder).
    • evals/results/: Test outputs, including latest.json and the HTML dashboard (index.html).
    • evals/test_tmp/: Temporary files generated during test execution.