Where to Find Maka's Agent Catalog and Built-In Agent Definitions

Maka's complete agent catalog and built-in agent definitions live in packages/runtime/src/agent-catalog.ts, which exports the BUILTIN_AGENT_DEFINITIONS array and helper functions like listBuiltinAgentDefinitions() and requireBuiltinAgentDefinitionByProfile().

The agent catalog is the single source of truth for all built-in agents in the Apache Maka framework. Whether you need to introspect available agents, spawn sub-agents programmatically, or understand the capabilities of the Implementation agent versus Local Read, the definitions are centralized in one runtime module. This article maps exactly where to find these definitions and how to use them.

The Core File: agent-catalog.ts

All built-in agent definitions reside in packages/runtime/src/agent-catalog.ts. This module declares three canonical agent types and exposes them through a clean programmatic API.

Built-In Agent Definitions

According to the Apache Maka source code, the file defines these symbol exports:

Symbol	Purpose	Line Range
BUILTIN_AGENT_DEFINITIONS	Array containing all three AgentDefinition objects	L22-L26
LOCAL_READ_AGENT_DEFINITION	Read-only agent (no write tools)	L37-L60
WEB_RESEARCH_AGENT_DEFINITION	WebSearch-only agent for research tasks	L61-L84
IMPLEMENTATION_AGENT_DEFINITION	Full toolset agent with worktree workspace and patch write-back	L86-L120
Helper functions (listBuiltinAgentDefinitions, getBuiltinAgentDefinition, requireBuiltinAgentDefinition)	Runtime API for catalog access	L122-L158

The IMPLEMENTATION_AGENT_DEFINITION represents Maka's most capable agent, configured with an isolated context, worktree workspace, and patch as its default write-back mechanism. The LOCAL_READ_AGENT_DEFINITION provides a safer, read-only alternative for scenarios requiring minimal side effects.

How the Runtime Consumes the Catalog

The sub-agent tooling layer imports directly from this catalog. In packages/runtime/src/subagent-tools.ts, lines 26-35 show the dependency chain:

import {
  BUILTIN_AGENT_DEFINITIONS,
  agentProfilesForDefinitions,
  buildToolsForAgentDefinition,
  requireAgentDefinitionByProfile,
  type AgentDefinition,
} from './agent-catalog.js';

This import pattern demonstrates how Maka's agent catalog propagates through the runtime: the catalog module provides definitions, and subagent-tools.ts transforms them into invocable tool implementations like agent_spawn, agent_list, and agent_output.

Programmatic Access to Agent Definitions

List All Built-In Agents

Use listBuiltinAgentDefinitions() to enumerate available agents at runtime:

import { listBuiltinAgentDefinitions } from '@maka/runtime/agent-catalog';

const agents = listBuiltinAgentDefinitions();
console.log(agents.map(a => `${a.name} (${a.profile})`));

Output:

Local Read (local_read)
Web Research (web_research)
Implementation (implementation)

Retrieve a Specific Agent by Profile

For type-safe access with error throwing, use requireBuiltinAgentDefinitionByProfile():

import { requireBuiltinAgentDefinitionByProfile } from '@maka/runtime/agent-catalog';

const implDef = requireBuiltinAgentDefinitionByProfile('implementation');
console.log(implDef.contract);

Output:

{
  "capability": "implementation",
  "invocation": "foreground",
  "context": "isolated",
  "workspace": "worktree",
  "defaultWriteBack": "patch",
  "supportedWriteBack": ["patch"]
}

The contract property reveals critical runtime behavior: the implementation agent runs in foreground invocation with isolated context and worktree workspace semantics.

Access the Raw Definition Array

For direct manipulation or custom tooling, import BUILTIN_AGENT_DEFINITIONS:

import { BUILTIN_AGENT_DEFINITIONS } from '@maka/runtime/agent-catalog';

function printAgentTools() {
  for (const def of BUILTIN_AGENT_DEFINITIONS) {
    console.log(`${def.name}: ${def.tools.join(', ')}`);
  }
}
printAgentTools();

Output:

Local Read: Read, Glob, Grep
Web Research: WebSearch
Implementation: Read, Glob, Grep, Write, Edit, apply_patch, Bash, WriteStdin, StopBackgroundTask

This reveals the capability gradient across Maka's built-in agents: from 3 read-only tools (Local Read) to 9 tools including apply_patch and Bash (Implementation).

Key Files for Agent Catalog Reference

File	Role	Direct Link
packages/runtime/src/agent-catalog.ts	Canonical definitions and catalog API	View source
packages/runtime/src/subagent-tools.ts	Catalog consumer—builds spawn/list/output tools	View source
packages/runtime/src/tool-runtime.ts	Runtime plumbing for tool registration	View source
packages/runtime/src/__tests__/configured-subagent-catalog.test.ts	Test verification of catalog behavior	View source

Summary

• Agent catalog location: packages/runtime/src/agent-catalog.ts contains all built-in agent definitions in Apache Maka.
• Primary export: BUILTIN_AGENT_DEFINITIONS array holds AgentDefinition objects for Local Read, Web Research, and Implementation.
• Runtime access: Use listBuiltinAgentDefinitions(), getBuiltinAgentDefinition(), or requireBuiltinAgentDefinitionByProfile() for programmatic access.
• Downstream consumption: subagent-tools.ts imports these definitions to construct the agent_spawn, agent_list, and agent_output tools.
• Capability inspection: Each definition includes tools, contract, and metadata fields describing invocation mode, workspace type, and write-back support.

Frequently Asked Questions

What is the difference between getBuiltinAgentDefinition and requireBuiltinAgentDefinitionByProfile?

getBuiltinAgentDefinition returns undefined when an agent profile is not found, making it suitable for conditional checks. requireBuiltinAgentDefinitionByProfile throws an error on missing profiles, enforcing runtime contracts. Both functions resolve against the same BUILTIN_AGENT_DEFINITIONS array in agent-catalog.ts.

Can I extend Maka with custom agents through the agent catalog?

The built-in catalog is immutable at runtime—the BUILTIN_AGENT_DEFINITIONS array is frozen to the three canonical agents. Custom agents require separate registration through Maka's agent configuration system, not modification of the core catalog module.

Why does the Implementation agent use patch as its default write-back?

The IMPLEMENTATION_AGENT_DEFINITION specifies defaultWriteBack: "patch" and supportedWriteBack: ["patch"] in its contract (lines 86-120 of agent-catalog.ts). This design isolates changes to discrete patch files in the worktree workspace, enabling atomic application and review before modifying the primary workspace.

How do I verify which tools a built-in agent supports?

Import BUILTIN_AGENT_DEFINITIONS and inspect the tools property of each AgentDefinition. The array contains string identifiers like "Read", "WebSearch", or "apply_patch" that map to tool implementations in the runtime.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}