Understanding the OpenClaude Repo Map: Architecture and Navigation

The OpenClaude repo map is a directory-level blueprint documented in AGENTS.md that organizes the codebase into self-contained modules—including commands, components, services, and utilities—to streamline CLI development and maintenance.

The OpenClaude repository follows a strict architectural map that makes the codebase navigable and extensible. This guide explains how the OpenClaude repo map structures the CLI application and guides contributors through the source code according to the official AGENTS.md specification referenced at lines 36-48.

What Is the OpenClaude Repo Map?

The OpenClaude repo map is a documented directory structure defined in AGENTS.md that serves as the guiding blueprint for developers. It groups related functionality into logical boundaries, ensuring that every feature—from slash commands to API integrations—has a designated location. This architecture prevents code duplication and establishes predictable import conventions across the TypeScript codebase.

Directory Structure and Responsibilities

The repository organizes functionality into ten primary directories. Each folder encapsulates a single concern and exposes a public interface used by other modules.

• src/commands/ – Implements slash commands and CLI entry-points. All user-triggered actions such as /provider and /onboard-github live here, with the central registry located at src/commands/index.ts.

• src/components/ – React and Ink UI components that render the terminal interface. This includes the buddy avatar, prompts, and task lists as seen in src/components/Buddy.tsx.

• src/services/ – Core service integrations including API callers, MCP, OAuth, wiki, and voice services. The file src/services/api.ts demonstrates how external LLM APIs are consumed.

• src/tools/ – Concrete tool implementations such as file tools, grep, glob, and git operations. These are the executable units the CLI invokes, exemplified by src/tools/git.ts.

• src/utils/ – Shared utility functions including Zod-to-JSON schema conversion, YAML/XML helpers, and work-tree handling. The worktree utility in src/utils/worktree.ts is imported across multiple modules.

• src/integrations/ – Metadata describing each provider and model integration. This directory handles configuration, discovery, and bootstrapping as defined in src/integrations/providers.ts.

• src/entrypoints/ – The actual binaries that start the application. The CLI bootstraps via src/entrypoints/cli.ts, while other entry points handle MCP server or SDK exports.

• src/tasks/ – Logic for handling local and remote tasks, workflows, and monitor jobs. Workflow orchestration lives here in files like src/tasks/workflow.ts.

• docs/integrations/ – Human-readable integration guides and how-to articles. The overview at docs/integrations/overview.md ties provider documentation back to the map.

• web/ – The documentation website that powers openclaude.dev. The React application root resides at web/src/App.tsx.

How the OpenClaude Repo Map Works

The map operates through four fundamental mechanisms that govern code organization and execution flow.

Modular Boundaries

Each top-level folder encapsulates a self-contained concern. For example, adding a new provider requires only creating files under src/integrations/ and optionally extending src/services/ for custom API logic. This isolation prevents side effects and keeps the cognitive load low when modifying specific features.

Import Conventions

Code in one area imports shared helpers from src/utils/, maintaining consistency and reducing duplication. Services and commands reference utilities through relative imports such as import { worktree } from '../utils/worktree', creating a clear dependency graph that the map enforces.

Command Flow Execution

The execution pipeline follows a strict path through the map. The CLI entry point at src/entrypoints/cli.ts parses arguments and dispatches to a command module under src/commands/. These commands may trigger tools in src/tools/ or services in src/services/, with results rendered via UI components in src/components/.

Extensibility Patterns

Adding a feature requires following the map's logical layout: create a command or tool in its designated folder, reuse utilities from src/utils/, and update documentation under docs/. This predictable structure lets contributors locate the correct place quickly and ensures the codebase remains maintainable as it scales.

Practical Implementation: Adding a New Feature

When extending OpenClaude, developers follow the import path flow dictated by the repository map. Below are examples showing how commands import utilities and how services leverage shared helpers.

Creating a Slash Command

To add a new /hello command, implement the logic in the commands directory and import shared utilities:

import { Command } from 'commander';
import { print } from '../utils/withResolvers';

// src/commands/hello.ts
export const helloCmd = new Command('hello')
  .description('Print a friendly greeting')
  .action(() => {
    print('👋 Hello from OpenClaude!');
  });

Using Shared Utilities in Services

Services leverage the worktree utility from src/utils/ to handle repository operations consistently:

import { worktree } from '../utils/worktree';

// src/services/exampleService.ts
export async function listWorktreeRoots() {
  const roots = await worktree.listRoots();
  return roots;
}

Both snippets demonstrate the unidirectional import pattern: commands and services import utilities, while the entry point wires everything together according to the map's specifications.

Summary

The OpenClaude repo map provides a deterministic architecture for CLI development. Key takeaways include:

• Documentation source: The canonical map lives in AGENTS.md at the repository root, defining directory responsibilities.
• Separation of concerns: src/commands/ handles user input, src/services/ manages external APIs, and src/tools/ executes operations.
• Shared utilities: The src/utils/ directory supplies common functionality like worktree management and schema conversion to all modules.
• Clear import paths: Relative imports follow the map's hierarchy, ensuring ../utils/ is the standard path for shared helpers.
• Entry point unification: src/entrypoints/cli.ts serves as the single bootstrap location that dispatches to the broader system.

Frequently Asked Questions

Where is the OpenClaude repo map documented?

The OpenClaude repo map is officially documented in the AGENTS.md file at the repository root, specifically between lines 36-48. This file serves as the authoritative blueprint that describes each directory's purpose and the import conventions contributors must follow.

How do I add a new provider to OpenClaude?

To add a new provider, create configuration files under src/integrations/ to define the provider metadata and discovery logic. If the provider requires custom API handling, extend src/services/ with the specific integration logic, following the modular boundaries established by the repo map.

What is the difference between src/services/ and src/tools/?

The src/services/ directory contains high-level integrations with external systems—such as API callers, OAuth handlers, and MCP clients—while src/tools/ houses concrete, executable implementations like file operations, git commands, and search utilities that the CLI directly invokes during task execution.

How does the CLI entry point interact with other modules?

The CLI entry point at src/entrypoints/cli.ts parses command-line arguments and dispatches execution to the appropriate module in src/commands/. These commands then orchestrate calls to src/tools/ for operations or src/services/ for external data, with output rendered through src/components/ before returning control to the entry point.

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