Spectra

Minimal, ultra-fast, multi-language AI agent framework

---

A construction kit, not a pre-built house — ship only primitives that enable developers to build anything beyond the core without fighting the framework.

Each SDK (TypeScript, Rust) is a complete, independent native implementation — same API surface, same behavior, no shared runtime, no bindings, no FFI.

Why Spectra?

I built Spectra because I lost months debugging framework bugs instead of building my product.

Every agent framework I tried — LangChain, LangGraph, and others — followed the same pattern: endless layers of abstraction for things that are, at their core, just a simple loop. An agent takes input, calls a model, processes the response, dispatches tools, and repeats. That's it. A loop. Everything else — the chains, graphs, runnables, callbacks, tracing hooks, and configurable-everything — is just over-engineering dressed up as architecture.

The cost of this over-engineering is real. I spent weeks tracking down bugs that turned out to be SDK issues, not application logic. Deployment options were limited. And worst of all, these frameworks create vendor lock-in — your entire codebase becomes coupled to abstractions you didn't need in the first place.

Spectra takes the opposite approach. No graphs. No chains. No runtime that owns your application. Just the primitives — a loop, a model call, a tool dispatch, a stream — that you assemble however you need. If you can write a for loop, you can understand the entire framework in 10 minutes.

Built for hackers who just want things to work. Ship what you mean, not what the framework lets you.

"But Spectra has rate limiters, circuit breakers, session stores..."

There's a difference between abstractions you don't need and utilities everyone ends up building anyway. LangChain invents chains, graphs, and runnables you never asked for. Rate limiting, circuit breakers, session persistence, SSE bridging — those aren't architecture opinions. They're infrastructure you'd write by hand in every production app. Spectra ships them as composable primitives so you don't spend 3 weeks building the same boilerplate every time.

Think of Spectra as two layers: a lean core (agent loop + tools + streaming) and a utility belt (rate limiting, session stores, health probes) — use what you need, ignore what you don't. The core never forces the belt on you.

---

Architecture

---

Packages

Core SDK packages are @mohanscodex/spectra-ai, @mohanscodex/spectra-agent, and @mohanscodex/spectra-app. @mohanscodex/spectra-code is the terminal TUI app built on those core packages.

Package	Layer	Description
@mohanscodex/spectra-ai	Provider	LLM abstraction — stream, complete, register providers. Anthropic Messages, OpenAI Chat Completions/Responses, OpenRouter, coding-plan providers, local runtimes, usage metadata, and file content blocks.
@mohanscodex/spectra-agent	Agent	Agent loop with multi-turn tool dispatch. defineTool() with Zod validation, before/after hooks, parallel/sequential execution, steering queues, retry with backoff, abort support, and subagent delegation.
@mohanscodex/spectra-app	Infrastructure (optional)	Production utilities you'd build anyway — SessionEngine, SessionManager, SessionStore, Rate Limiting, CircuitBreaker, SseBridge, HealthProbe, worker pools, and agent registry orchestration.
@mohanscodex/spectra-code	TUI App	Terminal-native AI coding agent built with OpenTUI — full-screen TUI, foreground/background subagents, MCP/ACP, file attachments, todos, memory, 60+ skills, custom tools, and security controls. Docs →
spectra-rs	Rust Core	Rust SDK — core types, agent, tools, events.
spectra-http	Rust HTTP	Rust HTTP clients for Anthropic Messages + OpenAI Chat Completions. OpenRouter-compatible.

Feature Matrix

Feature	TypeScript	Rust
Streaming SSE	✅	✅
Tool Dispatch (Parallel/Sequential)	✅	✅
Before/After Tool Hooks	✅	✅
Extension / Middleware System	✅	✅
Agent Loop (Multi-Turn)	✅	✅
Steering / Follow-up Queues	✅	—
Subagent Delegation	✅	✅
Retry with Exponential Backoff	✅	✅
File Attachments / Multimodal File Content	✅	—
Session Management	✅	—
Session Persistence (FS + SQLite)	✅	✅
Redis Session Store (distributed)	✅	—
Worker Pool	✅	✅
Rate Limiting (in-memory)	✅	✅
Redis Rate Limiting (distributed)	✅	—
Composite Rate Limiting (tenant+user+provider)	✅	—
Circuit Breaker	✅	✅
SSE Bridge (WS-compatible interface)	✅	—
Health Probe (K8s ready)	✅	✅
Agent Registry	✅	✅
Cost / Usage Tracking	✅	✅
Tool Choice / Reasoning Effort	✅	✅
Model Registry	✅	✅
Audit Trail / Provenance	✅	✅
Coding TUI (MCP, ACP, skills, todos, memory)	✅	—

Quick Start

TypeScript

bun add @mohanscodex/spectra-ai @mohanscodex/spectra-agent

import { Agent, defineTool } from "@mohanscodex/spectra-agent";
import { z } from "zod";

const searchTool = defineTool({
  name: "search",
  description: "Search the web",
  parameters: z.object({ query: z.string() }),
  execute: async ({ query }) => ({
    content: [{ type: "text", text: `Results for: ${query}` }],
  }),
});

const agent = new Agent({
  model: {
    id: "claude-sonnet-4-5",
    provider: "anthropic",
    api: "messages",
  },
  systemPrompt: "You are a helpful assistant.",
  tools: [searchTool],
});

for await (const event of agent.run("What is Rust?")) {
  if (event.type === "message_update") {
    console.log(event.message.content);
  }
}

Spectra Code

Terminal-native AI coding agent built on the Spectra SDK and OpenTUI.

Spectra Code is a full-screen OpenTUI app for coding with AI — chat with agents, run tools, manage sessions, and connect to MCP servers, all from your terminal. It does not use the archived @mohanscodex/spectra-tui package.

• Foreground/background subagents — delegate exploration or implementation and switch between child sessions
• File attachments — @ fuzzy file picker, local file reading, MIME detection, and inline attachment badges
• Hierarchical todos — /todo command and todo tool rendering for phased task plans
• 60+ bundled skills — plus skills learned from sessions and custom user skills
• MCP integration — connect stdio and HTTP tool servers
• ACP support — run as an agent server for Zed, Neovim, JetBrains
• Security controls — permissions, path safety, SSRF protection, doom-loop detection

bun add -g @mohanscodex/spectra-code
spectra

→ Full documentation

Deployment

TypeScript — Production

bun add @mohanscodex/spectra-ai @mohanscodex/spectra-agent @mohanscodex/spectra-app ioredis

TypeScript — TUI Coding Agent

bun add -g @mohanscodex/spectra-code

Rust

[dependencies]
spectra-rs = { git = "https://github.com/codex-mohan/spectra" }
spectra-http = { git = "https://github.com/codex-mohan/spectra" }
tokio = { version = "1", features = ["full"] }

Supported APIs

Spectra works with Anthropic's Messages API, OpenAI's Chat Completions/Responses APIs, and OpenAI-compatible endpoints. Set baseUrl on your model or choose a built-in provider.

Protocol	TypeScript	Rust
Anthropic Messages	✅	✅
OpenAI Chat Completions	✅	✅
OpenAI Responses	✅	—
OpenAI-compatible cloud providers	✅	✅
Local OpenAI-compatible runtimes	✅	✅

OpenAI-compatible providers such as Groq, OpenRouter, Together, Fireworks, Ollama, LM Studio, vLLM, LiteLLM, and local models work without framework-specific integrations.

Project Structure

spectra/
├── packages/
│   ├── ai/
│   ├── agent/
│   ├── app/
│   ├── code/
├── apps/
│   └── examples/
├── crates/
│   ├── spectra-rs/
│   └── spectra-http/
└── .github/workflows/

Technology Stack

Component	Technologies
TypeScript SDK	TypeScript 5.x · Bun · Vitest · Zod
Rust SDK	Rust 1.86+ · Tokio · Reqwest (rustls) · serde · thiserror · miette
Tooling	Turborepo · cargo

Rust Constraints

• Zero unsafe
• No OpenSSL
• rustls only
• Edition 2024
• Release profile optimized
• Thin LTO enabled

Development

git clone https://github.com/codex-mohan/spectra.git
cd spectra

bun install

bun run build
bun run test

cargo test --workspace

Credits

Spectra was deeply inspired by pi-mono by Mario Zechner — a beautifully minimal AI stack that proved an agent framework doesn't need layers of abstraction to be powerful.

License

MIT © Mohana Krishna