goatcode-sh

GoatCode is a professional agent harness for OpenCode. It provides a modular plugin architecture where every agent, tool, and hook is an independent plugin. This system allows for deep customization and reliable multi-agent orchestration.

Overview

GoatCode reimplements core agent capabilities with a focus on engineering quality and modularity. It uses a TypeScript-native configuration system and a micro-plugin registry to compose features.

Key features:

• 7 specialized agents for different task categories.
• 26 built-in tools including LSP integration and hash-anchored editing.
• 27 lifecycle hooks for context injection, error recovery, and quality control.
• Background agent parallelism for non-blocking work.
• TypeScript-native configuration with full type safety.

Installation

Install GoatCode via npm:

npm install goatcode-sh

GoatCode requires Bun to run.

Quick Start

Initialize GoatCode in your project:

goatcode install

This command sets up the initial configuration and verifies your environment.

Configuration

GoatCode uses a goatcode.config.ts file in your project root. Use the defineConfig helper for full type support.

import { defineConfig } from "goatcode-sh"

export default defineConfig({
  agents: {
    orchestrator: {
      model: "anthropic/claude-3-5-sonnet",
      temperature: 0
    }
  },
  plugins: [
    // Add external plugins here
  ]
})

You can also configure GoatCode at the user level by creating ~/.config/opencode/goatcode.ts. User-level configuration is merged with project-level configuration, allowing for persistent preferences across projects.

Agents

GoatCode includes 7 specialized agents.

Agent	Description
orchestrator	Main coordinator that plans and delegates tasks.
deepworker	Autonomous worker for end-to-end execution.
planbuilder	Strategic planner that interviews the user to define scope.
advisor	Read-only consultant for architecture and code review.
researcher	Specialist for documentation and code search.
explorer	Fast codebase search and pattern matching.
worker	General purpose executor for standard tasks.

Tools

GoatCode provides 26 tools for agents to interact with your codebase.

Category	Tools
LSP	goto_definition, find_references, symbols, diagnostics, prepare_rename, rename
Search	ast_grep_search, ast_grep_replace, grep, glob
Editing	hashline_edit
Delegation	task_delegate
Background	background_output, background_cancel
Session	session_list, session_read, session_search, session_info
Skills	skill_load, skill_mcp_invoke
System	interactive_bash, look_at
Tasks	task_create, task_list, task_get, task_update

Hooks

GoatCode uses 27 hooks to manage the agent lifecycle and improve output quality.

Category	Hooks
Context	context-injector, compaction-context, phase-reminder
Recovery	edit-error, json-error, session-recovery, context-window-limit
Models	model-fallback, runtime-fallback, preemptive-compaction
Quality	comment-checker, write-file-guard, thinking-block-validator
Productivity	keyword-detector, think-mode, anthropic-effort
Output	tool-output-truncator, hashline-read-enhancer, hashline-diff-enhancer
Continuation	todo-enforcer, compaction-todo-preserver, stop-guard, foreground-fallback
Tasks	delegate-retry, empty-response-detector, task-resume-info, todowrite-disabler
Nudges	post-read-nudge

CLI Commands

Command	Description
goatcode install	Install and configure GoatCode in the current directory.
goatcode update	Check for and install updates.

Contributing

We welcome contributions. Please see CONTRIBUTING.md for setup instructions and architectural overview.