Based on repository activity, growth velocity and community engagement.
25
Growth1/30
Activity7/25
Popularity8/25
Trust9/20
85
Stars
High
Sentiment
Votes
85
README.md
SharpClaw Code
SharpClaw Code is a C# and .NET-native coding agent runtime for teams building AI developer tools, agentic CLIs, and MCP-enabled workflows.
It combines durable sessions, permission-aware tool execution, provider abstraction, structured telemetry, and an automation-friendly command-line surface in a runtime shaped for real .NET systems: explicit, testable, and operationally legible.
The repository now ships both a terminal-first agent runtime and an embeddable host SDK through SharpClaw.Code, which makes it viable for standalone CLIs, local editor backends, and tenant-aware embedded services.
What It Is
SharpClaw Code is an open-source runtime for building and operating coding-agent experiences in the .NET ecosystem. think claude code meets opencode in C#
It is designed for:
teams that want a C# coding agent runtime instead of stitching together ad hoc scripts
developers building AI-powered CLI tools with strong machine-readable output
products that need MCP integration, plugin discovery, and permission-aware tool execution
workflows that need durable session state, append-only history, and replayable runtime events
cross-platform environments, with deliberate attention to Windows-safe behavior
Why It Stands Out
.NET-native architecture: built around .NET 10, C# 13, idiomatic DI, System.Text.Json, System.CommandLine, and Spectre.Console
Optional: GitHub CLI for release and repo automation
Build and test
git clone https://github.com/clawdotnet/SharpClawCode.git
cd SharpClawCode
dotnet build SharpClawCode.sln
dotnet test SharpClawCode.sln
Run the CLI
dotnet run --project src/SharpClaw.Code.Cli -- [arguments]
Common CLI Flows
# Start the interactive REPL
dotnet run --project src/SharpClaw.Code.Cli
dotnet run --project src/SharpClaw.Code.Cli -- repl
# Run a one-shot prompt
dotnet run --project src/SharpClaw.Code.Cli -- prompt "Summarize this workspace"
dotnet run --project src/SharpClaw.Code.Cli -- --auto-approve shell --auto-approve-budget 2 prompt "Check git status and summarize"
# Inspect runtime health and status
dotnet run --project src/SharpClaw.Code.Cli -- doctor
dotnet run --project src/SharpClaw.Code.Cli -- status
# Refresh and query the workspace knowledge index
dotnet run --project src/SharpClaw.Code.Cli -- index refresh
dotnet run --project src/SharpClaw.Code.Cli -- index query WidgetService
# Save and inspect durable memory
dotnet run --project src/SharpClaw.Code.Cli -- memory save --scope project "Keep prompts concise"
dotnet run --project src/SharpClaw.Code.Cli -- memory list --scope project
# Inspect metering summaries and details
dotnet run --project src/SharpClaw.Code.Cli -- usage summary
dotnet run --project src/SharpClaw.Code.Cli -- usage detail --limit 25
# Manage packaged tool bundles
dotnet run --project src/SharpClaw.Code.Cli -- tool-packages list
# Emit machine-readable output
dotnet run --project src/SharpClaw.Code.Cli -- --output-format json doctor
Built-in REPL slash commands include /help, /status, /doctor, /session, /commands, /mode, /editor, /export, /undo, /redo, and /version. Use /help to see the active command set, including discovered workspace custom commands.
Parity-oriented commands now include:
index / /index
memory / /memory
models / /models
usage / /usage
cost / /cost
stats / /stats
connect / /connect
hooks / /hooks
skills / /skills
agents / /agents
todo / /todo
share / /share
unshare / /unshare
compact / /compact
serve / /serve
worktree / /worktree
/sessions as a friendlier alias over /session list
Primary workflow modes:
build: normal coding-agent execution
plan: structured deep planning that blocks mutating tools and syncs planning-owned session todos
spec: generates Kiro-style spec artifacts under docs/superpowers/specs/<date>-<slug>/
Core Capabilities
| Capability | Why it matters |
|---|---|
| Durable sessions | Persist conversation state, turn history, checkpoints, and recovery metadata for longer-running agent work |
| Permission-aware tools | Route file, shell, and plugin-backed actions through explicit policy and approval decisions |
| Provider abstraction | Run against Anthropic and OpenAI-compatible backends through a typed runtime surface |
| Local runtime catalog | Surface Ollama, llama.cpp, and other OpenAI-compatible profiles with health, model discovery, and embedding defaults |
| MCP support | Register, supervise, and integrate MCP servers with explicit lifecycle state |
| Plugins and skills | Extend the runtime with trusted plugin manifests and discoverable workspace skills |
| Workspace knowledge | Build a durable local index for lexical, symbol, and semantic workspace search |
| Cross-session memory | Persist project and user memory so later sessions can recall repo-specific guidance and user preferences |
| Structured telemetry | Emit runtime events and usage signals that support diagnostics, replay, and automation |
| Enterprise host controls | Add tenant-aware storage, authenticated approvals, admin APIs, and usage metering for embedded deployments |
| JSON-friendly CLI | Use the same runtime through human-readable terminal flows or machine-readable command output |
| Spec workflow mode | Turn prompts into structured requirements, technical design, and task documents for feature proposals |
| Embedded SDK + server | Host the runtime via SharpClaw.Code or expose prompt, session, admin, and SSE endpoints for editor or automation clients |
| Config + agent catalog | Layer user/workspace JSONC config with typed agent defaults, tool allowlists, and runtime hooks |
| Session sharing | Create self-hosted share links and durable sanitized share snapshots under .sharpclaw/ |
| Diagnostics context | Surface configured diagnostics sources into prompt context, status, and machine-readable output |
Good Fit For
building a C# AI coding assistant
running a local or hosted coding-agent CLI
creating a .NET MCP client/runtime
adding session persistence and auditability to agent workflows
building on Microsoft Agent Framework without pushing your application core into framework-specific code
The solution includes embeddable host samples under examples/:
MinimalConsoleAgent for direct SDK prompt execution
WebApiAgent for an HTTP-hosted runtime surface
WorkerServiceHost for lifecycle-managed background hosting
McpToolAgent for MCP-aware host composition
Testing
# Run all tests
dotnet test SharpClawCode.sln
# Build example hosts as part of local validation
dotnet build examples/WebApiAgent/WebApiAgent.csproj
dotnet build examples/MinimalConsoleAgent/MinimalConsoleAgent.csproj
dotnet build examples/WorkerServiceHost/WorkerServiceHost.csproj
dotnet build examples/McpToolAgent/McpToolAgent.csproj
# 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"
| Project | Purpose |
|---|---|
| SharpClaw.Code.UnitTests | Fast unit tests covering tools, permissions, sessions, providers, state machine, telemetry, and serialization |
| SharpClaw.Code.IntegrationTests | Runtime and provider flows with full DI composition |
| SharpClaw.Code.ParityHarness | End-to-end scenarios using a deterministic mock LLM provider |
| SharpClaw.Code.MockProvider | DeterministicMockModelProvider with named scenarios for reproducible testing |
| SharpClaw.Code.Mcp.FixtureServer | MCP fixture server for integration testing |
Global CLI Options
| Option | Description |
|---|---|
| --cwd <path> | Working directory; defaults to the current directory |
| --model <id> | Model id or alias; provider/model forms are supported where configured |
| --permission-mode <mode> | readOnly, workspaceWrite, or dangerFullAccess; see docs/permissions.md |
| --auto-approve <scopes> | Auto-approve specific elevated scopes such as shell, network, or promptRead |
| --auto-approve-budget <n> | Cap how many elevated operations may be auto-approved in the session |
| --output-format text\|json | Human-readable or structured output |
| --primary-mode <mode> | Workflow bias for prompts: build, plan, or spec |
| --session <id> | Reuse a specific SharpClaw session id for prompt execution |
| --agent <id> | Select the active agent for prompt execution |
| --host-id <id> | Stable embedded-host identifier for metering, admin, and event envelopes |
| --tenant-id <id> | Tenant identifier used by host-aware storage, approvals, and metering |
| --storage-root <path> | External root for host-managed durable runtime state |
| --session-store fileSystem\|sqlite | Select the embedded session/event storage backend |
SharpClaw Code uses both the standard .NET configuration stack (appsettings.json, environment variables, CLI args) and layered SharpClaw JSONC config files:
user config: ~/.config/sharpclaw/config.jsonc on Unix-like systems
Windows user config: %AppData%\\SharpClaw\\config.jsonc
| Section | Purpose |
|---|---|
| SharpClaw:Providers:Catalog | Default provider, model aliases |
| SharpClaw:Providers:Anthropic | Anthropic API key, base URL, default model |
| SharpClaw:Providers:OpenAiCompatible | OpenAI-compatible base settings plus local runtime profiles, auth mode, and default embedding model |
| SharpClaw:Web | Web search provider name, endpoint template, user agent |
| SharpClaw:Telemetry | Runtime event ring buffer capacity plus webhook event export behavior |
Key sharpclaw.jsonc capabilities:
shareMode: manual, auto, or disabled
server: host, port, and optional public base URL for share links
defaultAgentId: default prompt agent
agents: typed agent catalog entries with model defaults, tool allowlists, and instruction appendices
lspServers: configured diagnostics sources
hooks: lifecycle hooks for turn/tool/share/server events
connectLinks: browser entry points for provider or external auth flows
All options are validated at startup via IValidateOptions implementations.
Current Scope
The shared tooling layer is permission-aware across the runtime.
The current runtime includes multi-turn provider-backed tool execution, session-backed prompt replay, and durable conversation history.
Agent-driven tool calls flow through the same approval and allowlist enforcement path used by direct tool execution, including caller-aware interactive approval behavior.
Workspace indexing, symbol search, and durable memory are available through both CLI commands and built-in tools.
ACP now carries editor context, approval round-trips, model catalog queries, workspace search/index actions, and memory actions, which is enough for a real VS Code client over a single transport.
OpenAI-compatible local runtime profiles can surface Ollama, llama.cpp, and similar endpoints with profile-aware auth and model discovery.
Embedded hosts can opt into trusted-header or OIDC-backed approval identity, tenant-aware usage metering, webhook/SSE event streaming, and admin APIs for provider catalog, index status, search, memory inspection, and tool package management.
The CLI mirrors those enterprise surfaces with usage summary, usage detail, and tool-packages commands while preserving the existing workspace-local usage, cost, and stats flows.
Operational commands support stable JSON output via --output-format json, which makes them suitable for scripts, editors, and automation.
The embedded server exposes local JSON and SSE endpoints for prompts, sessions, admin control, metering, and event streaming.
Contributing
Use .NET 10 and C# 13. Follow AGENTS.md for project boundaries, serialization conventions, logging expectations, and cross-platform rules.
