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.
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.
Install GoatCode via npm:
npm install goatcode-shGoatCode requires Bun to run.
Initialize GoatCode in your project:
goatcode installThis command sets up the initial configuration and verifies your environment.
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.
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. |
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 |
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 |
| Command | Description |
|---|---|
goatcode install |
Install and configure GoatCode in the current directory. |
goatcode update |
Check for and install updates. |
We welcome contributions. Please see CONTRIBUTING.md for setup instructions and architectural overview.