Skip to content

CLAUDE.md

Latest commit

 

History

History
85 lines (62 loc) · 4.33 KB

CLAUDE.md

File metadata and controls

85 lines (62 loc) · 4.33 KB

CLAUDE.md

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

Project

SharpClaw Code is a C#-native coding-agent runtime (.NET 10 / C# 13) inspired by the Rust claw-code surface. It provides durable sessions, permission-aware tool execution, provider abstraction (Anthropic & OpenAI-compatible), MCP integration, and plugin/skill extensibility.

Build & Test Commands

# Build
dotnet build SharpClawCode.sln

# Run all tests
dotnet test SharpClawCode.sln

# Run a single test by name
dotnet test SharpClawCode.sln --filter "FullyQualifiedName~YourTestName"

# Run parity harness scenarios only
dotnet test SharpClawCode.sln --filter "FullyQualifiedName~ParityScenarioTests"

# Run the CLI
dotnet run --project src/SharpClaw.Code.Cli -- [arguments]

Architecture

Entry point: src/SharpClaw.Code.Cli/Program.cs builds a host via CliHostBuilder, resolves CliCommandFactory, and invokes System.CommandLine.

Core execution flow:

  1. ConversationRuntime.RunPromptAsync resolves/creates a session
  2. DefaultTurnRunner builds prompt context via IPromptContextAssembler
  3. PrimaryCodingAgent delegates to AgentFrameworkBridge -> ProviderBackedAgentKernel -> IModelProvider
  4. Tools execute through IToolRegistry -> PermissionPolicyEngine -> ISharpClawTool.ExecuteAsync
  5. Events published via IRuntimeEventPublisher, sessions persisted as snapshots + NDJSON append logs

DI composition roots: RuntimeServiceCollectionExtensions.AddSharpClawRuntime() and CliServiceCollectionExtensions.AddSharpClawCli().

Key project boundaries:

  • Protocol is the dependency-light center: DTOs, enums, events, ProtocolJsonContext (source-gen JSON)
  • Runtime owns orchestration and lifecycle, not the CLI
  • Cli and Commands are thin; business logic lives in Runtime/Agents/Tools
  • Tools must route through Permissions -- never bypass permission checks
  • Sessions supports both durable snapshots and append-only event logs
  • Agents wraps the Microsoft Agent Framework without leaking provider/transport details

Engineering Rules (from AGENTS.md)

  • System.Text.Json only -- never Newtonsoft.Json. Use ProtocolJsonContext for source-generated serialization.
  • Async/await end-to-end for all I/O. Pass CancellationToken through async call paths.
  • Constructor injection over service location.
  • File-scoped namespaces, records for immutable contracts, interfaces for infrastructure seams.
  • Cross-platform with Windows-safe path/process handling. No hardcoded secrets or machine-specific paths.
  • XML docs for all public APIs and major internal services.
  • Permission policy enforcement for shell execution and file mutation.
  • Typed contracts over ad hoc dictionaries. Keep JSON outputs stable unless explicitly breaking.
  • Prefer incremental vertical slices over broad placeholder scaffolding.

Test Projects

Project Role
SharpClaw.Code.UnitTests Fast unit tests (tools, permissions, serialization, MCP)
SharpClaw.Code.IntegrationTests Runtime + provider flows with real composition
SharpClaw.Code.MockProvider DeterministicMockModelProvider with named scenarios
SharpClaw.Code.ParityHarness End-to-end scenarios via ParityTestHost with mock LLM
SharpClaw.Code.Mcp.FixtureServer MCP fixture server for testing

Mock provider scenarios: streaming_text, stream_failure, stream_slow, read_file_roundtrip, write_file_allowed, write_file_denied, grep_chunk_assembly, bash_stdout_roundtrip, permission_prompt_approved, permission_prompt_denied, plugin_tool_roundtrip, mcp_partial_startup, recovery_after_timeout.

CLI Modes

  • build -- normal coding-agent execution (default)
  • plan -- analysis-first, blocks mutating tools
  • spec -- generates Kiro-style spec artifacts under docs/superpowers/specs/

Known Backlog (ARCHITECTURE-NOTES.md)

  • Commands project directly references Mcp/Plugins (should go through abstractions)
  • McpDoctorService uses anonymous objects instead of typed DTOs for JSON
  • Plugin manifest parsing uses JsonSerializerDefaults.Web instead of ProtocolJsonContext
  • Telemetry sinks not yet wired for production (OpenTelemetry, file traces)
  • Runtime directly references Agents (acceptable for now, seam needed if multiple backends appear)