Claude CLI

UseClaude(...) selects the locally installed Claude Code CLI. Set the model explicitly in the agent definition, just as with Codex. Authentication continues to use the host account's existing CLI configuration; no agent API key is required.

Define the Claude agent

The configuration callback and Model are required. Calling UseClaude() without arguments does not compile with this API; leaving the model blank fails validation when creating the agent.

This callback API is introduced in the Claude agent options source branch. Use a framework build containing this change. Earlier package versions expose only the parameterless method; this documentation update does not publish a new NuGet package.

Create Agents/ClaudeAgent.cs in your .NET 10 ASP.NET Core project:

using Runiq.AI.Agents;
using Runiq.AI.Agents.Configuration;

namespace MyApp.Agents;

/// <summary>Defines a project assistant backed by the local Claude Code CLI.</summary>
public static class ClaudeAgent
{
    /// <summary>Creates the assistant with explicit model and reasoning settings.</summary>
    /// <returns>The configured Claude agent using existing CLI authentication.</returns>
    public static Agent Create() => new Agent(
        id: "claude-analyst",
        name: "Claude Analyst",
        instructions: """
        Answer the user's actual request in their language.
        For greetings, reply briefly without inspecting files or running commands.
        For code questions, inspect only relevant files and cite paths and line numbers.
        Explain behavior, suggest test cases, or propose changes in your answer.
        Ask for missing context; do not assume history from earlier requests.
        Do not claim to have performed checks that you have not run.
        Never modify files, run destructive commands, commit, or push.
        Keep the answer concise and focused on the request.
        """)
        .UseClaude(options =>
        {
            options.Model = "sonnet";
            options.ReasoningEffort = ClaudeReasoningEffort.High;
        });
}

Register the agent

Create the definition through its factory in Program.cs:

using MyApp.Agents;
using Runiq.AI.Core;

var builder = WebApplication.CreateBuilder(args);

var agent = ClaudeAgent.Create();

builder.Services.AddRuniqServer(options => options.AddAgent(agent));

var app = builder.Build();
app.Run();

AddRuniqServer automatically registers the Claude executor. Execution requires Claude Code CLI installed and authenticated under the host account.

Definition and registration do not launch or authenticate the CLI. Follow Running agents with claude-analyst as the agent id, or enable Studio.

Choose model settings

Runiq copies the validated settings into agent.Executor!.Claude and sends --model and --effort on every invocation, including resumed turns. The selected CLI/account determines model availability and supported reasoning levels; account policy can limit effective effort. Studio displays the configured model and requested reasoning effort.

Claude has no Runiq ServiceTier option. Use ClaudeReasoningEffort for Claude and CodexReasoningEffort for Codex. Both require an explicit model. See the Claude CLI reference for the underlying flags.

Understand permissions

Runiq invokes Claude in non-interactive dontAsk mode. Actions requiring approval are denied, while existing CLI permission allow rules still apply. This does not guarantee a read-only filesystem; configure permissions under the trusted host account and project. Runiq does not enable permission bypass.

Runiq preserves the account's CLI authentication. It removes CLAUDE_CODE_EFFORT_LEVEL from the child environment so that inherited effort cannot override the agent's selection. Agent instructions and the user message are passed through standard input.

Attach Runiq tools

Attach a typed tool to the definition before registration:

using Runiq.AI.Agents.Tools;

// Use TextStatsTool from the Defining tools guide.
agent.AddTool<TextStatsTool>();

See Defining tools for the complete TextStatsTool definition. Runiq creates an authenticated per-run HTTP MCP bridge and allows the agent's exact tool names. Use a Claude Code installation with HTTP MCP support. No additional MCP registration is required; a failed bridge connection returns ClaudeToolBridgeFailed.

Tools run in the host process with host permissions and must validate business input and honor cancellation. Their start, completion and failure events appear in Studio. Native Claude tool activity is not republished as Runiq tool events. Active Runiq RAG bindings are unsupported and return ClaudeCapabilityNotSupported.

Execute and continue a conversation

Resolve AgentExecutionRuntime through dependency injection for completed responses or streaming. Claude text deltas become AssistantDelta events. To continue persisted CLI history, pass the confirmed ProviderSessionId from a previous result; see CLI conversation continuation.

Missing installation returns ClaudeNotInstalled; authentication failure returns ClaudeAuthenticationFailed. Timeout returns ClaudeTimeout. Failures do not fall back to Codex or a model provider.

Next: Run the registered agent →