Crate supercode 

supercode

A lightweight, fully-customizable AI coding-agent SDK in Rust.

supercode is a native agent loop — it talks directly to any model through OpenRouter (or any other OpenAI-compatible endpoint), drives a configurable set of tools, and is designed to be a superset of what tools like Claude Code and Codex can do: every prompt, every tool description, and every tool’s on/off state is yours to control.

Quick start

use supercode::{Agent, Config};

// Reads OPENROUTER_API_KEY from the environment by default.
let config = Config::builder()
    .model("anthropic/claude-opus-4-8")
    .system_prompt("You are a terse, expert pair programmer.")
    .build();

let mut agent = Agent::new(config)?;
let reply = agent.send("List the files in the current directory.").await?;
println!("{reply}");

Design

• Config — the single knob box: model, endpoint, credentials, sampling, the system prompt, and per-tool overrides (enable/disable + custom descriptions).
• Provider — the model transport. OpenAiProvider speaks the OpenAI chat-completions wire format and defaults to OpenRouter, so it reaches Claude, GPT, Gemini, Llama, and anything else OpenRouter exposes.
• Tool / ToolRegistry — the capability surface. Built-ins cover file read/write/edit, directory listing, glob, content search, and shell execution. Register your own to extend it.
• Agent — the loop that ties it together: it streams a turn, runs any tool calls the model requests, feeds results back, and repeats until the model produces a final answer.

Re-exports

pub use session::Session;

pub use session::SessionFormat;

pub use session::SessionMeta;

pub use session::SessionSource;

pub use store::SessionInfo;

pub use store::SessionStore;

pub use tools::SandboxPolicy;

pub use tools::Tool;

pub use tools::ToolContext;

pub use tools::ToolRegistry;

Modules

audit

Corpus coverage audit.

mcp

Minimal Model Context Protocol support — both directions, over the stdio transport (newline-delimited JSON-RPC 2.0):

schema

Typed schemas for the on-disk session formats.

session

Natively load — and continue — real Claude Code and Codex sessions.

store

A directory-backed store for supercode’s own sessions — naming, titles, listing, archiving, and deletion. The analog of claude --name / the Codex resume/archive/delete session lifecycle.

tools

Tools the agent can call.

Structs

Agent

A stateful agent: configuration, a model transport, a tool set, and the running conversation. Drive it with Agent::send.

ChatMessage

A single message in a conversation.

ChatRequest

A single completion request.

Config

Everything that shapes an crate::Agent: the model and endpoint, the credentials, sampling parameters, the system prompt, and per-tool overrides.

ConfigBuilder

Fluent builder for Config.

ConfigFile

A config file: a set of named profiles (the analog of Codex -p/--profile).

ConfigProfile

The serializable subset of a Config that can live in a config file. (Callbacks/handlers are code-only and are not represented here.)

FunctionCall

The function payload of a ToolCall.

OpenAiProvider

An OpenAI-compatible HTTP provider. Defaults to OpenRouter via crate::Config.

ToolCall

A request from the model to invoke a tool.

ToolOverride

Per-tool customization: enable/disable a tool and/or override the description the model sees for it.

ToolSchema

A tool advertised to the model: name, description, and JSON-Schema parameters.

Usage

Token accounting returned with a completion.

Enums

AgentEvent

Streaming events emitted by an crate::Agent as a turn unfolds.

ApprovalPolicy

When the agent must seek approval before running a tool — the analog of Codex’s -a untrusted|on-request|never and Claude’s permission modes.

Error

Errors that can arise while configuring or running an crate::Agent.

Role

Who authored a ChatMessage.

Traits

Provider

The transport abstraction. Implement this to back the agent with something other than an OpenAI-compatible HTTP endpoint (a local model, a mock, etc.).

Functions

format_reply

Format an agent’s final reply for output. json wraps it as {"result": "..."}; otherwise the reply is returned as-is. The stream-json form is the live AgentEvent stream via an EventSink.

Type Aliases

EventSink

A sink for AgentEvents.

Result

Result alias used throughout the crate.