# ClaudeClient

The Anthropic Messages API client that the Claude harness uses, and the `ClaudeHarness` that wraps it.

`builder.claude` takes a `ClaudeClient` or a `ClaudeHarness`. The client holds the endpoint, the authentication, and the HTTP stack. `ClaudeHarness` adds harness settings, such as instructions, tools, and a hook that configures each agent's `ClaudeBuilder`.

```rust
use nanocode::{ClaudeClient, Nanocode};

// 1. Make a client from an Anthropic API key
let claude = ClaudeClient::with_api_key(
    "https://api.anthropic.com/v1/messages",
    std::env::var("ANTHROPIC_API_KEY")?,
);

// 2. Install it as the Claude harness
let runtime = Nanocode::builder().claude(claude).build_async().await?;
```

## Constructors

### ClaudeClient::with_api_key

> [!NOTE]
> `ClaudeClient::with_api_key` and `ClaudeClient::default` exist only on native targets.

```rust
// An API key and an endpoint, with a new reqwest client
pub fn with_api_key(
    endpoint: impl Into<String>,
    api_key: impl Into<String>,
) -> ClaudeClient
```

Sends `api_key` to `endpoint`. Use the full Messages URL, such as `https://api.anthropic.com/v1/messages` or a compatible proxy.

```rust
// Points the client at a compatible local endpoint
let claude =
    ClaudeClient::with_api_key("http://127.0.0.1:8080/messages", key);
```

### ClaudeClient::default

```rust
// The Claude subscription login
impl Default for ClaudeClient
```

Uses subscription authentication. It reads the Claude login that `/login claude` stores in the nanocode home, then falls back to the Claude Code login. The requests go to `https://api.anthropic.com/v1/messages?beta=true`.

```rust
// Uses the login that `nc` or Claude Code stores
let runtime = Nanocode::builder()
    .claude(ClaudeClient::default())
    .build_async()
    .await?;
```

### ClaudeClient::new

```rust
// A caller-supplied HTTP client, endpoint, and API key
pub fn new(
    http: reqwest::Client,
    endpoint: impl Into<String>,
    api_key: impl Into<String>,
) -> ClaudeClient
```

Works like `with_api_key` with a `reqwest::Client` that the host configures.

```rust
// Shares one connection pool with the host
let claude = ClaudeClient::new(
    reqwest::Client::new(),
    "https://api.anthropic.com/v1/messages",
    key,
);
```

### ClaudeClient::official

```rust
// The official Messages endpoint
pub fn official(
    http: reqwest::Client,
    api_key: impl Into<String>,
) -> ClaudeClient
```

Equivalent to `ClaudeClient::new` with `https://api.anthropic.com/v1/messages`.

```rust
// Uses the Anthropic API with an API key
let claude = ClaudeClient::official(reqwest::Client::new(), key);
```

### ClaudeClient::with_auth_headers

```rust
// Fixed authentication headers
pub fn with_auth_headers(
    http: reqwest::Client,
    endpoint: impl Into<String>,
    headers: http::HeaderMap,
) -> ClaudeClient
```

Sends `headers` with each request in place of the API key that `new` sends.

```rust
// Authenticates with a fixed header
let mut headers = http::HeaderMap::new();
headers.insert("x-api-key", key.parse()?);
let claude = ClaudeClient::with_auth_headers(
    reqwest::Client::new(),
    endpoint,
    headers,
);
```

### ClaudeClient::with_auth_provider

```rust
// Headers from a provider that can refresh them
pub fn with_auth_provider(
    http: reqwest::Client,
    endpoint: impl Into<String>,
    provider: Arc<dyn ClaudeAuthProvider>,
) -> ClaudeClient
```

Asks `provider` for the authentication headers of each request. `ClaudeClient::subscription` does the same with the subscription endpoint and subscription compatibility.

```rust
use std::sync::Arc;

// Uses a host-owned token source
let claude = ClaudeClient::with_auth_provider(
    reqwest::Client::new(),
    endpoint,
    Arc::new(provider),
);
```

## Methods

### with_http_layer

```rust
// Wraps each HTTP request in a layer
pub fn with_http_layer(self, layer: impl Layer) -> ClaudeClient
```

Adds a layer around the HTTP requests of the client.

```rust
// Adds a layer that signs each request
let claude =
    ClaudeClient::with_api_key(endpoint, key).with_http_layer(signer);
```

### with_transport

```rust
// Replaces the HTTP stack
pub fn with_transport(
    self,
    transport: impl HttpTransport,
) -> ClaudeClient
```

Sends requests through `transport` instead of `reqwest`, for example a host's own `fetch`.

```rust
// Routes requests through the host
let claude = ClaudeClient::with_api_key(endpoint, key)
    .with_transport(host_transport);
```

### uses_subscription

```rust
// Whether the client sends subscription requests
pub const fn uses_subscription(&self) -> bool
```

Returns `true` for `ClaudeClient::default` and `ClaudeClient::subscription`.

```rust
// Prints true for the default client
println!("{}", ClaudeClient::default().uses_subscription());
```

## ClaudeHarness

The Claude harness, at `nanocode::ClaudeHarness`. `ClaudeHarness::new(client)` and `ClaudeHarness::from(client)` make one, and `ClaudeHarness::default()` uses `ClaudeClient::default()` on native targets.

```rust
use nanocode::{ClaudeClient, ClaudeHarness, Nanocode};

// Gives every Claude agent its own instructions
let harness = ClaudeHarness::new(ClaudeClient::default())
    .instructions("Prefer small diffs.");
let runtime = Nanocode::builder().claude(harness).build_async().await?;
```

### headless

* **Type:** `bool`
* **Default:** `false`

Runs root agents like Claude Code's headless sessions. A background command's notification is only steered into a running turn and never starts a new turn. Background commands stop when the turn ends.

```rust
// Matches `nc exec` behavior
let harness =
    ClaudeHarness::new(ClaudeClient::default()).headless(true);
```

### instructions

* **Type:** `impl Into<Arc<str>>`

Sets instructions for agents of this harness.

```rust
// Adds a rule for Claude agents only
let harness =
    ClaudeHarness::default().instructions("Answer in one paragraph.");
```

### tools

* **Type:** `Tools`

Sets the tools of agents of this harness. `tools_factory` builds them per agent from its `AgentHandle`, as [`builder.tools_factory`](/docs/api/rust/Nanocode#buildertools_factory) does.

```rust
// Gives Claude agents a smaller catalog
let harness = ClaudeHarness::default()
    .tools(Tools::builder().without_defaults().build()?);
```

### configure

* **Type:** `Fn(ClaudeBuilder) -> Result<ClaudeBuilder, NanocodeError>`

Runs a hook on the `ClaudeBuilder` of each agent before the agent starts, for example to add lifecycle or tool hooks.

```rust
// Leaves each builder unchanged, as a starting point for hooks
let harness = ClaudeHarness::default().configure(|builder| Ok(builder));
```