zypher-agent: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Root workspace commands (run from repo root):

• Run CLI: deno task cli - Runs the CLI from packages/cli
• Test all: deno task test - Runs all tests with leak tracing
• Test watch: deno task test:watch - Runs tests in watch mode
• Check all: deno task checkall - Runs format, lint, and type check

Code quality

• Type check: deno check .
• Lint: deno lint
• Format: deno fmt

Architecture Overview

Zypher Agent is a TypeScript SDK for building production-ready AI agents. Published as @zypher/agent on JSR.

Monorepo Structure

packages/
├── agent/          # Core SDK (@zypher/agent)
│   ├── src/        # Source code
│   └── tests/      # Tests
├── cli/            # CLI tool (@zypher/cli)
examples/
└── ptc/            # Programmatic Tool Calling example

Core Components (packages/agent/src/)

• ZypherAgent.ts: Main agent class with reactive task execution loop. Uses RxJS Observable to stream TaskEvents. Manages message history, checkpoints, and coordinates with McpServerManager and LoopInterceptorManager.

• factory.ts: createZypherAgent() - simplified factory that creates context, registers tools, and connects MCP servers in one call.

• llm/: Model provider abstraction (ModelProvider interface) with implementations for Anthropic and OpenAI. Handles streaming chat completions and token usage tracking.

• loopInterceptors/: Chain of responsibility pattern for post-inference processing. Each interceptor can return LoopDecision.CONTINUE to continue the agent loop or LoopDecision.COMPLETE to finish.

  • ToolExecutionInterceptor: Executes tool calls from LLM responses
  • MaxTokensInterceptor: Auto-continues when response hits token limit
  • ErrorDetectionInterceptor: Detects errors and prompts for fixes

• mcp/: Model Context Protocol integration

  • McpServerManager: Manages MCP server lifecycle, tool registration, and tool execution with optional approval handlers
  • McpClient: Individual server connection with status observable
  • Supports CoreSpeed MCP Store registry for server discovery