CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

pikchr-tools is a Rust workspace providing a complete toolkit for Pikchr diagrams: CLI, MCP server, and LSP server. Uses pikru (pure Rust) for Pikchr rendering.

Repository: https://github.com/claylo/pikchr-tools

Workspace Structure

pikchr-tools/
├── crates/
│   ├── pikchr/                  # CLI: render, fmt, check, lint
│   ├── pikchr-mcp-server/       # MCP server (stdio/SSE)
│   ├── pikchr-lsp-server/       # Language server
│   └── pikchr-core/             # Shared library
│       └── src/
│           ├── tools/           # render, validate, export (PNG)
│           ├── lint/            # code quality rules
│           ├── layout/          # SVG analysis
│           ├── explain/         # error help
│           ├── resources/       # 40 embedded docs
│           ├── prompts/         # workflow templates
│           └── symbols/         # AST symbol extraction
└── xtask/                       # build tooling

Commands

# Build
cargo build

# Run tests
just test                    # All tests (nextest)
cargo test --doc             # Doc tests only

# Linting & formatting
just check                   # Run all checks (fmt, clippy, deny, test)

# Run binaries
cargo run -p pikchr -- render file.pikchr
cargo run -p pikchr-mcp-server
cargo run -p pikchr-mcp-server -- --transport sse --port 8080
cargo run -p pikchr-lsp-server

# Benchmarks
cargo xtask bench

Crates

Key Dependencies

• pikru — Pure Rust Pikchr renderer with full AST
• resvg/usvg/tiny-skia — Pure Rust SVG-to-PNG rendering
• rmcp — MCP SDK (server, transport-io, transport-streamable-http-server)
• tower-lsp — Language Server Protocol implementation
• tokio — Async runtime
• axum — HTTP server for SSE transport
• clap — CLI argument parsing

Key Patterns

• Workspace layout: Shared pikchr-core library used by all binaries
• AST access: pikru::parse::parse() returns full AST for symbol extraction
• Error-as-data: Tools return success with structured JSON errors
• Registry pattern: Resources and prompts use static registries

Conventions

• See .claude/skills/ for detailed development conventions
• See .claude/rules/ for project constitution
• Refer to AGENTS.md (repository root) for dependency, commit, and coding conventions