Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
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.
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
- .NET-native architecture: built around .NET 10, C# 13, idiomatic DI, System.Text.Json, System.CommandLine, and Spectre.Console
- Durable runtime model: sessions, checkpoints, append-only event logs, export/import flows, and recovery-aware orchestration
- Safety by default: permission modes, approval gates, workspace-boundary enforcement, and mediated tool execution
- Extensible surface: providers, MCP servers, plugins, skills, ACP hosting, and runtime commands integrate through explicit seams
- Automation-ready interface: stable JSON output, operational commands, and a clean CLI-first workflow that works for both humans and scripts
- .NET SDK 10
- Optional: GitHub CLI for release and repo automation
git clone https://github.com/clawdotnet/SharpClawCode.git
cd SharpClawCode
dotnet build SharpClawCode.sln
dotnet test SharpClawCode.slndotnet run --project src/SharpClaw.Code.Cli -- [arguments]# 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 doctorBuilt-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>/
| 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 |
- 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
| Area | Project(s) |
|---|---|
| Embeddable SDK | SharpClaw.Code |
| CLI and command handlers | SharpClaw.Code.Cli, SharpClaw.Code.Commands |
| Core contracts | SharpClaw.Code.Protocol |
| Runtime orchestration | SharpClaw.Code.Runtime |
| Agents | SharpClaw.Code.Agents |
| Tools and permissions | SharpClaw.Code.Tools, SharpClaw.Code.Permissions |
| ACP host | SharpClaw.Code.Acp |
| Providers, MCP, plugins | SharpClaw.Code.Providers, SharpClaw.Code.Mcp, SharpClaw.Code.Plugins |
| Sessions, telemetry, infrastructure | SharpClaw.Code.Sessions, SharpClaw.Code.Telemetry, SharpClaw.Code.Infrastructure |
| Memory, git, web, skills | SharpClaw.Code.Memory, SharpClaw.Code.Git, SharpClaw.Code.Web, SharpClaw.Code.Skills |
For dependency boundaries and project responsibilities, see docs/architecture.md and AGENTS.md.
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
# 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 |
| 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 |
Subcommands include prompt, repl, doctor, status, session, index, memory, models, usage, cost, stats, connect, hooks, skills, agents, todo, share, unshare, compact, serve, commands, worktree, mcp, plugins, tool-packages, acp, bridge, and version.
| Doc | Topic |
|---|---|
| docs/architecture.md | Solution layout, dependencies, and execution flows |
| docs/runtime.md | Turns, ConversationRuntime, and runtime coordinators |
| docs/sessions.md | Session snapshots and append-only event logs |
| docs/providers.md | IModelProvider, configuration, and provider integration |
| docs/tools.md | Tool registry, executor behavior, and built-ins |
| docs/permissions.md | Permission modes, policies, and approvals |
| docs/agents.md | Agent Framework integration |
| docs/external-agents.md | External agent adapters and supervised CLI runs |
| docs/skills.md | Skill packs, built-in workflows, and install/run commands |
| docs/work-items.md | GitHub and generic work-item import/export |
| docs/workbench.md | Static runtime workbench/status surfaces |
| docs/mcp.md | MCP registration, lifecycle, and orchestration |
| docs/acp.md | ACP stdio host and protocol notes |
| docs/plugins.md | Plugin discovery, trust, and CLI flows |
| docs/testing.md | Unit, integration, and parity-harness coverage |
| ARCHITECTURE-NOTES.md | Architectural follow-ups and cleanup ideas |
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
- workspace config: <workspace>/sharpclaw.jsonc
Precedence is:
CLI args > workspace sharpclaw.jsonc > user config.jsonc > appsettings/environment defaults
Key runtime configuration sections:
| 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.
- 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.
Use .NET 10 and C# 13. Follow AGENTS.md for project boundaries, serialization conventions, logging expectations, and cross-platform rules.
Before opening a PR:
dotnet build SharpClawCode.sln
dotnet test SharpClawCode.sln
dotnet build examples/WebApiAgent/WebApiAgent.csproj
dotnet build examples/MinimalConsoleAgent/MinimalConsoleAgent.csproj
dotnet build examples/WorkerServiceHost/WorkerServiceHost.csproj
dotnet build examples/McpToolAgent/McpToolAgent.csprojThis project is licensed under the MIT License.
Repository: github.com/clawdotnet/SharpClawCode