Architecture Overview

How Cdoing Agent is structured as a modular monorepo and how all the pieces connect.

Project Structure

cdoing-agent/ ├── package.json # Workspace root (Yarn workspaces) ├── turbo.json # Turbo build orchestration ├── tsconfig.json # Shared TypeScript config │ ├── packages/ │ ├── core/ # @cdoing/core — Foundation layer │ │ ├── src/ │ │ │ ├── tools/ # 21 built-in tools │ │ │ ├── permissions/ # Permission engine │ │ │ ├── sandbox/ # FS & network sandbox │ │ │ ├── context-providers/ # 10 @ mention providers │ │ │ ├── indexing/ # SQLite FTS5 + vectors │ │ │ ├── hooks/ # Pre/post tool hooks │ │ │ ├── rules/ # Glob-scoped project rules │ │ │ ├── plan/ # Read-only plan mode │ │ │ ├── mcp/ # Model Context Protocol │ │ │ ├── effort/ # Effort level control │ │ │ ├── oauth.ts # Shared OAuth (PKCE + keychain) │ │ │ └── utils/ # Path safety, search, etc. │ │ └── package.json │ │ │ ├── ai/ # @cdoing/ai — Intelligence layer │ │ ├── src/ │ │ │ ├── agent-runner.ts # Agentic loop + streaming │ │ │ ├── provider.ts # Multi-LLM factory │ │ │ ├── system-prompt.ts # Prompt builder │ │ │ └── context-manager.ts # Token tracking + cost │ │ └── package.json │ │ │ ├── cli/ # @cdoing/cli — Terminal UI │ │ ├── src/ │ │ │ ├── index.ts # Entry point + args │ │ │ ├── chat.ts # Interactive chat │ │ │ ├── config.ts # Setup wizard │ │ │ ├── tools.ts # Tool registry setup │ │ │ ├── commands.ts # Subcommands │ │ │ ├── oauth.ts # CLI-specific OAuth UI │ │ │ └── ui/ # Ink React components │ │ └── package.json │ │ │ └── vscode-extension/ # cdoing-vscode — VS Code UI │ ├── src/ │ │ ├── extension.ts # Activation + commands │ │ ├── chat-panel-provider.ts # Webview + agent │ │ ├── inline-edit.ts # Cmd+I editing │ │ ├── inline-autocomplete.ts # Ghost text │ │ ├── oauth.ts # Extension-specific OAuth │ │ └── webview/ # React chat UI │ └── package.json │ └── docs/ # This documentation site

Package Dependency Graph

The dependency graph is strictly layered. Core has no internal dependencies. AI depends only on core. Both CLI and VS Code extension depend on AI and core. Dashed lines show direct core imports (for OAuth, tools, etc.).

Full System Map

Every module, tool, and external dependency — and how they connect. Solid lines are runtime calls, dashed lines are shared imports.

Build System

The project uses Turbo for build orchestration across the Yarn workspace monorepo. Key build commands:

Command	Description
yarn build	Build all packages via Turbo (respects dependency order)
yarn dev	Watch mode for all packages (persistent, no cache)
yarn start	Build core + ai, then run CLI
yarn clean	Remove all dist/ directories

Each package compiles TypeScript to CommonJS (ES2022 target) with declaration files. Build outputs go to dist/ in each package. The VS Code extension uses esbuild to bundle everything (including core) into a single dist/extension.js.

Data Flow: The Agentic Loop

The core runtime is an agentic loop that continuously cycles between the LLM and tool execution until the task is complete:

How the loop works

The LLM receives the user message + system prompt, then decides whether to respond with text (returned to user) or invoke tools. Tool calls go through pre-hooks, permission checks, execution, and post-hooks. Results are fed back to the LLM, which can invoke more tools or produce a final text response.

Key Architectural Decisions

1. Shared OAuth in Core

All OAuth logic (PKCE, credential storage, token refresh) lives in @cdoing/core. Both CLI and VS Code extension import from core — zero duplication. Tokens are stored in the OS credential manager and shared between all consumers.

2. Raw JSON Schema for Tool Binding

Tools are bound to the LLM using raw JSON Schema definitions rather than Zod or other schema libraries. This keeps the core package dependency-free from validation libraries and ensures maximum compatibility across providers.

3. SQLite for Indexing (No External DB)

The codebase indexer uses SQLite with FTS5 for full-text search and stores vector embeddings as JSON. No external vector database needed.

4. LangChain for Provider Abstraction

The AI package uses @langchain/core as a thin abstraction layer over multiple LLM providers.

5. Permissions as a First-Class Concern

Every tool execution passes through the permission engine before running. The 3-tier deny/ask/allow rule system ensures security without sacrificing usability.

Technology Stack

Layer	Technology
Language	TypeScript (ES2022, CommonJS output)
Monorepo	Yarn Workspaces + Turbo
LLM Abstraction	LangChain (@langchain/core, @langchain/anthropic, etc.)
Database	SQLite (better-sqlite3) with FTS5
CLI Framework	Commander + Ink (React for terminals)
VS Code UI	React + esbuild (webview)
Auth	OAuth 2.0 PKCE (shared via @cdoing/core)
Diagrams	React Flow + avoid-nodes-edge