Multi-Agent System

Gokin uses a multi-agent architecture with 5 built-in agent types, task delegation, and inter-agent communication.

Agent Types#

Type	Purpose	Tools
explore	Codebase exploration	read, glob, grep, tree, list_dir, tools_list, request_tool, ask_agent
bash	Command execution	bash, read, glob, tools_list, request_tool, ask_agent
general	Full access	All tools (unrestricted)
plan	Task planning	read, glob, grep, tree, list_dir, diff, todo, web_fetch, web_search, ask_user, env, tools_list, request_tool, ask_agent, enter_plan_mode, exit_plan_mode, update_plan_progress, get_plan_status
claude-code-guide	Documentation & guides	glob, grep, read, web_fetch, web_search, tools_list, request_tool, ask_agent

Agent Lifecycle#

pending → running → completed | failed | cancelled

Custom Agent Types#

Create a new type via slash command:

/register-agent-type reviewer "Code review agent" --tools read,glob,grep,diff --prompt "You are a code reviewer"
/list-agent-types
/unregister-agent-type reviewer

Task Delegation#

Delegation Strategy#

The system uses 6 delegation rules with adaptive weights:

#	Condition	Action	Reason
1	explore agent tries to run bash	→ bash agent	explore has no bash access
2	bash agent: compilation error	→ explore agent	Needs code analysis to fix
3	general agent stuck ≥5 turns	→ plan agent	Task too complex, needs decomposition
4	plan agent: glob/grep empty result	→ explore agent	Needs deep codebase exploration
5	Any agent: file not found	→ explore agent	Find the correct path
6	Specialized agent stuck ≥7 turns	→ general agent	Escalate to full-access agent

Delegation Scoring#

Delegation decisions are based on multi-factor scoring:

score = (baseRate × 0.4 + historicalRate × 0.6) × weight + trendBonus × 0.1

baseRate — success rate from StrategyOptimizer
historicalRate — historical success rate from DelegationMetrics
weight — adaptive weight (EMA, range 0.5–2.0)
trendBonus — trend of recent results (-1.0 to +1.0)

Limits#

Maximum delegation depth: 5 levels
Adaptive turns: baseTurns - (depth × 3), minimum 5
Rule suppression: unsuccessful rules are temporarily blocked
Max parallel agents: 5

Delegation Metrics#

Stored in ~/.config/gokin/memory/delegation_metrics.json:

Path: "from:to:context_type" (e.g., "explore:bash:tool_needed")
Success/Failure counts
Execution time
Last 20 results
LRU eviction at >200 paths

Tree Planning#

Gokin supports 3 search algorithms for task decomposition:

Algorithms#

Algorithm	Description	When to Use
Beam Search	Top-K paths at each level	Fast, good heuristics
MCTS	Monte Carlo Tree Search with UCB1	Balance exploration vs exploitation
A*	Cost-aware search (f = g + h)	Optimal for good heuristics

Tree Planner Configuration#

plan:
  algorithm: beam         # beam, mcts, astar
  beam_width: 5
  mcts_iterations: 100
  max_tree_depth: 10
  max_tree_nodes: 1000
  replan_on_failure: true
  max_replans: 3
  planning_timeout: 60s

Scoring Weights#

score = (successProb × 0.4) + (costEstimate × 0.3) + (goalProgress × 0.3)

Tree Action Types#

Type	Description
ToolCall	Call a specific tool
Delegate	Delegate to another agent
Decompose	Decompose into subtasks
Verify	Verify the result

Action Generation Patterns#

Implementation (implement, create, build): Explore → Plan → Execute → Verify
Fixing (fix, bug, debug): Explore → Fix → Test
Refactoring (refactor, optimize): Explore → Plan → Execute → Test
Testing (test): Explore → Write tests → Run tests

Inter-Agent Communication#

Shared Memory#

Inter-agent shared memory with typed entries:

Entry Type	Purpose
Fact	Discovered facts
Insight	Analytical conclusions
FileState	File states
Decision	Architectural decisions
ContextSnapshot	Context snapshots

Operations: Write, WriteWithTTL, Read, ReadByType, ReadAll, Delete, Subscribe

Limits: max 500 entries, LRU eviction, automatic cleanup of expired entries

Context Snapshots#

Saving context between phases (planning → execution):

Key files
Discovered facts
Error patterns and solutions
Critical tool results
User requirements
Decisions made

Agent Messenger#

Direct communication between agents:

SendMessage(type, toRole, content, metadata) → messageID
ReceiveResponse(ctx, messageID) → response

Response wait timeout: 3 minutes.

Self-Reflection#

The reflection system analyzes errors and suggests solutions:

Components#

Error patterns — regex patterns for typical errors
LLM analysis — semantic analysis for unrecognized errors
ErrorStore — persistent error learning
File predictor — path prediction for file_not_found

Reflection Result#

Field	Description
Category	file_not_found, timeout, compilation_error, etc.
Suggestion	What the user needs to know
ShouldRetry	Whether retry is possible
SuggestedFix	Specific fix command
Alternative	Alternative approach
AutoFix	Automatic fix

Feedback Loop#

Reflection identifies error → suggests fix
Agent executes fix
Result recorded in DelegationMetrics
Successful fixes increase rule weight
Unsuccessful ones decrease it