A hands-on introduction to Claude Code — Anthropic's AI-powered CLI for software engineering. This repo covers the essential building blocks: the CLI itself, MCP server integration, and LLM observability with Langfuse.
Claude Code is an agentic coding assistant that runs in your terminal. It can read and edit files, run shell commands, search your codebase, and orchestrate multi-step engineering tasks — all within your local environment.
Key capabilities:
- Agentic file editing, refactoring, and code generation
- Shell command execution with user-controlled permissions
- MCP (Model Context Protocol) server integration for extending context
- Hooks for automating workflows around tool calls
- Custom skills (slash commands) for repeatable tasks
claude-code-101/
├── langfuse/ # Self-hosted Langfuse stack (Docker Compose)
│ ├── docker-compose.yml
│ ├── .env.example
│ └── README.md # Detailed Langfuse setup guide
├── .claude/
│ ├── CLAUDE.md # Project-level instructions for Claude Code
│ ├── settings.local.json # Local permissions and MCP server toggles
│ └── skills/
│ └── langfuse/ # Custom Claude Code skill for Langfuse
├── .mcp.json # MCP server configuration (project-level)
├── .env # Local secrets (git-ignored)
└── README.md # This file
| Tool | Purpose |
|---|---|
| Claude Code CLI | The main CLI (claude) |
| Docker with Compose v2 | Running the Langfuse stack |
openssl |
Generating secrets (built into macOS/Linux) |
npm install -g @anthropic-ai/claude-code
claude --versionLangfuse gives you full visibility into every LLM call — traces, token usage, costs, prompt versions, and evaluations.
cd langfuse/
cp .env.example .env
# Fill in secrets — see langfuse/README.md for step-by-step instructions
docker compose up -dOpen the UI at http://localhost:3000, create a project, and copy your API keys from Project Settings → API Keys.
The .mcp.json at the project root connects Claude Code to Langfuse's MCP endpoint, giving Claude direct access to your prompts, traces, and datasets.
{
"mcpServers": {
"langfuse": {
"type": "http",
"url": "http://localhost:3000/api/public/mcp",
"headers": {
"Authorization": "Basic <base64(publicKey:secretKey)>"
}
}
}
}Generate the token:
echo -n "pk-lf-<your-public-key>:sk-lf-<your-secret-key>" | base64Paste the result as the Basic token in .mcp.json.
claudeClaude Code automatically picks up .mcp.json and .claude/settings.local.json from the project root.
MCP (Model Context Protocol) lets Claude connect to external services as first-class tools. With the Langfuse MCP server connected, Claude can:
- List and retrieve prompt versions
- Create and update prompts
- Query traces and datasets
MCP config lives at .mcp.json (project-level, shared with the team) or ~/.claude/mcp.json (global, personal).
The .claude/skills/langfuse/ directory contains a custom Claude Code skill that teaches Claude how to work with Langfuse effectively — instrumenting applications, migrating prompts, capturing user feedback, and querying data via the CLI.
Skills are invoked as slash commands inside a Claude Code session:
/langfuse