Helpline
Helpline is a B2B helpdesk and customer-support platform — an internal monorepo
where five services (api, auth, billing, notifications, search) talk
over HTTP and share two internal packages (core, db). It's the kind of
mid-sized, multi-service codebase where an AI coding agent either pays for
itself or quietly makes a mess: shared packages that everything imports, money
rules that must never silently regress, a request gateway with its own
conventions, and tests scattered across services.
Quick start
What this repo actually is. Helpline is a demonstration codebase, built for the YouTube video "The AI Layer: How to Make Claude Code Work in Large Codebases." It is a deliberately realistic — but compact — complex codebase, used to show concretely how to build an AI Layer — our name for the harness of configuration and tooling that Anthropic's article describes in How Claude Code works in large codebases. (The article describes the harness and its components; "AI Layer" is our term for it, not Anthropic's.) That article is the what and the why, and it is excellent — but it stays high-level. Helpline is the how: every component from the article, built and validated on a real codebase. The rest of this repo is written as if Helpline were a live product, because that is exactly how you should treat your own codebase when you give it an AI Layer.
Run it:
git clone https://github.com/coleam00/helpline.git
cd helpline
uv sync --extra dev
uv run pytest # the application's own test suiteSee the AI Layer: read AI-LAYER.md — it maps every
component to the article and to where it lives in this repo. Then run the
validator, which proves every piece works end to end:
uv run --extra dev python tooling/validate/validate_all.py # 13/13The AI Layer, concretely
Every codebase you ship with an AI agent has three parts: code, tests, and — the new one — the AI Layer: the configuration, context, and reusable workflows that make an agent productive in your codebase. Helpline builds every component the article names:
| Component (from the article) | Built here | Where |
|---|---|---|
| CLAUDE.md hierarchy | lean root CLAUDE.md + one per service/package, loaded additively | CLAUDE.md, */CLAUDE.md |
| Hooks | a SessionStart orientation hook + a self-improving Stop hook that reflects on the session and proposes concrete CLAUDE.md edits | .claude/hooks/ |
| Skills | billing-money-rules, api-add-route, scoped-tests — glob-scoped with the paths: field, progressive disclosure into references/ | .claude/skills/ |
| Subagent | a genuinely read-only explorer (no write tools) that maps a subsystem and reports back | .claude/agents/explorer.md |
| LSP | pyright + pyright-langserver for symbol-level navigation | docs/lsp-setup.md |
| MCP | codebase-search — AST-based where_is / find_references / outline | tooling/mcp/ |
| Plugin | helpline-ai-layer — bundles the portable pieces for one-command install | tooling/helpline-ai-layer/ |
The git history is the before/after, on purpose: commit 1 is Helpline with no AI Layer; commit 2 adds the entire layer.
Take this to your own codebase
Helpline is not just something to read — it is something to reuse. There are two ways, and both matter more than the codebase itself.
1. Install the plugin — the fastest path
The portable, repo-agnostic pieces of the AI Layer are bundled as a Claude Code
plugin at tooling/helpline-ai-layer/. From your own project:
/plugin marketplace add /path/to/helpline/tooling
/plugin install helpline-ai-layer@helpline-tooling
That one install gives your repo:
- the self-improving Stop hook — reflects on each session and proposes
CLAUDE.mdupdates, so your layer never silently rots; - the read-only
explorersubagent — maps a subsystem without burning your main session's context; - the
codebase-searchMCP — AST-based structured search; - a generic
scoped-testsskill.
These are deliberately layout-agnostic: the hooks follow your CLAUDE.md
hierarchy, and the MCP discovers your source by walking the repo. Nothing is
tied to Helpline's directory names.
2. Point your coding agent at this repo
You don't have to copy anything by hand. Clone Helpline, open it alongside your project, and tell your agent something like:
Read
AI-LAYER.mdand the.claude/folder in the Helpline repo. It is a worked example of the AI Layer from Anthropic's large-codebases article. Build a comparable AI Layer for this codebase — a CLAUDE.md hierarchy, hooks, skills, an MCP, a subagent — adapted to our structure and conventions.
AI-LAYER.md exists for exactly this. It is an agent-readable map from each
article concept to the artifact that implements it, plus the proof that it
works. The repo is a reference implementation your agent can learn the pattern
from — not boilerplate to clone blindly.
What travels, and what you rebuild
| Generalizable — works in any repo | Repo-specific — rebuild for yours |
|---|---|
the Stop / SessionStart hooks (CLAUDE.md-hierarchy based) | the CLAUDE.md files (your conventions) |
the explorer subagent | billing-money-rules, api-add-route (your domain skills) |
the codebase-search MCP | — |
the generic scoped-tests skill | — |
The repo-specific pieces aren't reusable content — but they are reusable templates. Copy the shape, change the substance.
Layout
services/
api/ HTTP gateway — routes, request handling
auth/ authentication — tokens, password hashing
billing/ subscriptions + invoicing
notifications/ outbound email + templating
search/ ticket search indexing + queries
packages/
core/ shared domain models + error types
db/ database connection + repositories
infra/ docker-compose for local dev
scripts/ one-off operational scripts
tests/ cross-service integration tests
tooling/ the AI Layer's MCP server, the plugin, and the validators
Each service owns its own area. packages/core and packages/db are imported
by every service — change them carefully.
Dev
uv sync --extra dev # install
uv run pytest # full test suite
uv run pyright # type-check