add developer docs

2026-03-31 16:04:03 +05:00
parent 35408dd369
commit 51fa1eeca5
17 changed files with 468 additions and 46 deletions
--- a/docs-site/docs/guides/building-an-agentic-cli-overview.md
+++ b/docs-site/docs/guides/building-an-agentic-cli-overview.md
@@ -0,0 +1,39 @@
+# Building your own agentic coding CLI (greenfield)
+
+!!! danger "Do not clone proprietary code"
+This page describes how to build **new** tooling from **public** APIs and OSS patterns. It is **not** instructions to copy or redistribute the leaked `src/` tree as “open-source Claude Code.” Anthropic’s Claude Code remains **proprietary**.
+
+## What “agentic CLI” means
+
+A minimal agent loop:
+
+1. **Context** — project files, git status, user prompt.
+2. **Model** — calls a capable LLM API with tools/functions defined in schema form.
+3. **Tools** — read/write files, grep, run shell (with guardrails), call HTTP, etc.
+4. **Loop** — model requests tools → host executes → results appended → model continues until done.
+
+Claude Code implements this pattern in TypeScript with extra product layers (trust, compaction, MCP, IDE bridge). Your project can be far smaller.
+
+## Stack options (all legitimate OSS / vendor SDKs)
+
+| Piece             | Common choices                                                                                                       |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------- |
+| **Runtime**       | Node.js, Bun, Deno, Go, Python                                                                                       |
+| **Terminal UI**   | None (pure stdin/stdout), [Ink](https://github.com/vadimdemedes/ink) (React), blessed, bubbletea                     |
+| **CLI parsing**   | Commander, yargs, clap (Rust), Typer (Python)                                                                        |
+| **Anthropic API** | Official [Anthropic SDK](https://docs.anthropic.com/) and [Messages API](https://docs.anthropic.com/en/api/messages) |
+| **MCP**           | [Model Context Protocol](https://modelcontextprotocol.io) SDKs and server examples                                   |
+| **Sandboxes**     | Containers, `firejail`, allow-listed commands, separate VMs (depends on threat model)                                |
+
+## OSS / public projects to study (examples, not endorsements)
+
+Look for **actively maintained** agent or coding assistants under licenses you accept. Examples people often cite in the ecosystem include **Aider**, terminal agents built on **Continue** or **Codex-style** CLIs, and **MCP servers** in the official registry. **Compare licenses and security posture yourself**—do not assume parity with Claude Code.
+
+## Relationship to this repository
+
+Use the `src/` mirror to **learn patterns** (how compaction, MCP, or permissions _can_ be structured). Re-implement ideas in **your own codebase** with your own naming and design; do not paste Anthropic’s source into a public repo.
+
+## Next
+
+- [MCP and tool-loop patterns](mcp-and-tool-loop-patterns.md) — abstract loop without copying this tree.
+- [Documentation and CI](documentation-and-ci-for-docs.md) — ship docs like this site.
--- a/docs-site/docs/guides/documentation-and-ci-for-docs.md
+++ b/docs-site/docs/guides/documentation-and-ci-for-docs.md
@@ -0,0 +1,29 @@
+# Documentation and CI (pattern from this repo)
+
+You can reuse the **same mechanics** this project uses for **any** open-source or internal project docs—not Claude Code itself.
+
+## Ingredients
+
+| Piece           | Location here                                                                                                         |
+| --------------- | --------------------------------------------------------------------------------------------------------------------- |
+| **Static site** | [MkDocs](https://www.mkdocs.org/) + [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)               |
+| **Sources**     | `docs-site/docs/**/*.md`, `docs-site/mkdocs.yml`                                                                      |
+| **Build**       | `mkdocs build -f docs-site/mkdocs.yml`                                                                                |
+| **Deploy**      | GitHub Actions → `gh-pages` branch (e.g. [peaceiris/actions-gh-pages](https://github.com/peaceiris/actions-gh-pages)) |
+
+## Checklist for a new repo
+
+1. Add `docs-site/` with `mkdocs.yml`, `requirements.txt`, and Markdown under `docs/`.
+2. Set `site_url` when GitHub Pages URL is known.
+3. Add workflow: Python setup → `pip install -r docs-site/requirements.txt` → `mkdocs build` → deploy `docs-site/site`.
+4. Enable **GitHub Pages** from `gh-pages` / root (or switch to GitHub’s native Pages Actions upload).
+5. Use `enable_jekyll: false` (or commit `.nojekyll`) so Jekyll does not skip underscore paths.
+
+## This fork’s live site
+
+Configured `site_url`: [https://mehmoodosman.github.io/claude-code-source-code/](https://mehmoodosman.github.io/claude-code-source-code/)
+
+## See also
+
+- [Installation](../installation.md) — local preview commands
+- [Editing documentation](../developer/editing-documentation.md)
--- a/docs-site/docs/guides/mcp-and-tool-loop-patterns.md
+++ b/docs-site/docs/guides/mcp-and-tool-loop-patterns.md
@@ -0,0 +1,31 @@
+# MCP and tool-loop patterns (abstract)
+
+!!! note "Conceptual only"
+This page describes **common agent architectures**. It references `src/` modules only as **illustrations** of where similar ideas appear in Claude Code—not as code to copy.
+
+## Tool loop (functions / tools)
+
+1. Define tools with **names, descriptions, and JSON Schema** (or equivalent) for arguments.
+2. Send user + conversation + tool definitions to the model.
+3. If the model returns a **tool call**, validate arguments, **execute** on the host, append a **tool_result** message (or provider-specific equivalent).
+4. Repeat until the model finishes without further tool calls or a cap is hit.
+
+In this reconstruction, much of that orchestration lives in `query.ts` and adjacent helpers, while tool implementations live under `tools/*` and `services/tools/`.
+
+## MCP (Model Context Protocol)
+
+**MCP** standardizes how tools and resources are exposed by **servers** the host spawns and talks to over stdio or other transports. Claude Code’s `services/mcp/` implements configuration, transports, OAuth, and channel-style push—see **[MCP reference](../reference/mcp.md)** for file-level mapping.
+
+For **your** project:
+
+- Start from [MCP documentation](https://modelcontextprotocol.io) and official SDKs.
+- Implement **one** small MCP server (e.g. filesystem or git) before designing a full IDE-quality integration.
+
+## Parallel: skills and plugins
+
+Claude Code layers **skills** (project-scoped instructions + commands) and **plugins** on top of the core loop. Greenfield designs might use: simple slash-commands, `SKILL.md` conventions, or dynamic imports—without reproducing this product’s plugin manifest.
+
+## See also
+
+- [Building an agentic CLI overview](building-an-agentic-cli-overview.md)
+- [Official: MCP](https://code.claude.com/docs/en/mcp)