# Understanding the OpenClaude Repo Map: Architecture and Navigation

> Explore the OpenClaude repo map, a directory blueprint in AGENTS.md, organizing commands components services and utilities for streamlined CLI development and maintenance.

- Repository: [Gitlawb/openclaude](https://github.com/Gitlawb/openclaude)
- Tags: architecture
- Published: 2026-09-06

---

**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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/src/components/Buddy.tsx).

- **`src/services/`** – Core service integrations including API callers, MCP, OAuth, wiki, and voice services. The file [`src/services/api.ts`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/src/integrations/providers.ts).

- **`src/entrypoints/`** – The actual binaries that start the application. The CLI bootstraps via [`src/entrypoints/cli.ts`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/src/tasks/workflow.ts).

- **`docs/integrations/`** – Human-readable integration guides and how-to articles. The overview at [`docs/integrations/overview.md`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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:

```typescript
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:

```typescript
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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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.