ASDV (Agile Synthetic Dev Vibe)

A .NET 8 console-based coding agent that operates on local repositories, inspired by Claude Code.
Supports OpenAI, Anthropic, and OpenAI-compatible endpoints with a provider-agnostic architecture.

Features

• Provider-agnostic: Switch between OpenAI, Anthropic, and OpenAI-compatible endpoints
• Streaming: Real-time streaming of model responses via SSE
• Tool system: Extensible tools for file operations, search, git, and command execution
• Policy-based approval: Dangerous operations require user approval
• Session logging: JSONL logs for reproducibility and debugging
• Path safety: Prevents path traversal and symlink escape attacks

Quick Start

Prerequisites

• .NET 8.0 SDK or later
• An API key for OpenAI or Anthropic (not required for local OpenAI-compatible endpoints)

Installation

git clone <repository-url>
cd asdv
dotnet build

Usage

# Set your API key
export ANTHROPIC_API_KEY=your_key_here
# or
export OPENAI_API_KEY=your_key_here

# Run in REPL mode (default - interactive, multi-turn conversations)
dotnet run --project src/Agent.Cli

# Run in REPL mode with an initial prompt
dotnet run --project src/Agent.Cli -- "Fix the bug in Program.cs"

# Run a single prompt and exit (--once mode)
dotnet run --project src/Agent.Cli -- --once "Add unit tests for Calculator.cs"

# Resume a previous session by ID (REPL mode)
dotnet run --project src/Agent.Cli -- --session-id abc123def456

# Start a new session with a specific ID
dotnet run --project src/Agent.Cli -- --session-id my-feature-work "Implement new API endpoint"

# Run with auto-approve (use with caution)
dotnet run --project src/Agent.Cli -- -y "Refactor the authentication module"

# Specify repository path and provider
dotnet run --project src/Agent.Cli -- -r /path/to/repo -p anthropic "Review the codebase"

# Use OpenAI-compatible endpoint via config
dotnet run --project src/Agent.Cli -- -r /path/to/repo -p openai-compatible

CLI Options

Option	Alias	Description	Default
--repo	-r	Repository root path	Current directory
--provider	-p	LLM provider (openai, anthropic, openai-compatible)	openai
--model	-m	Model name	Provider-specific
--config	-c	YAML config path (default: asdv.yaml in repo root)	None
--yes	-y	Auto-approve all tool calls	false
--session	-s	Session log file path	Auto-generated
--session-id	--sid	Session ID for resume/new session	Auto-generated
--once		Run a single prompt and exit	false
--max-iterations		Maximum agent iterations	20
--debug	-d	Enable debug output (stack traces)	false

Architecture

Agent.sln
src/
  Agent.Cli/           # Entry point, CLI parsing
  Agent.Core/          # Orchestrator, events, policies
  Agent.Llm.Anthropic/ # Claude Messages API provider
  Agent.Llm.OpenAI/    # OpenAI Chat Completions API provider
  Agent.Tools/         # Tool implementations
  Agent.Workspace/     # File system safety
  Agent.Logging/       # JSONL session logging
  Agent.Server/        # HTTP API server for agent sessions
tests/
  Agent.Core.Tests/
  Agent.Tools.Tests/
  Agent.Server.Tests/
scripts/
  server-client.mjs    # Node.js client for Agent.Server

Available Tools

Tool	Description	Requires Approval
ReadFile	Read file contents with optional line range	No
ListFiles	List files matching glob patterns	No
SearchText	Search for text patterns (regex)	No
GitStatus	Get repository status	No
GitDiff	View staged/unstaged changes	No
ApplyPatch	Apply unified diff or Begin Patch format patches	Yes
RunCommand	Execute shell commands	Yes

Configuration

Environment Variables

Variable	Description
ANTHROPIC_API_KEY	API key for Anthropic Claude
OPENAI_API_KEY	API key for OpenAI
OPENAI_BASE_URL	Custom base URL for OpenAI (optional)

Default Models

• Anthropic: claude-sonnet-4-20250514
• OpenAI: gpt-5-mini

YAML Config (asdv.yaml)

You can define default settings in asdv.yaml at the repo root and run without extra flags:

provider: openai-compatible
model: gpt-oss-20b
openaiCompatibleEndpoint: http://127.0.0.1:8080

Session Logs

Session logs are saved in JSONL format to .agent/session_<sessionId>.jsonl by default. Each line contains:

• User prompts
• Model streaming events
• Tool calls and results
• Message snapshots (for replay/resume)
• Timestamps

Session Management

• --session-id <id>: Create or resume a session with the specified ID. Sessions are stored as .agent/session_<id>.jsonl
• --session <path>: Specify a custom path for the session log file (mutually exclusive with --session-id)
• Session index: All sessions are tracked in .agent/sessions.jsonl for discovery and debugging
• Resumption: When you resume a session with --session-id, the agent loads all previous messages and continues the conversation

REPL vs. Once Mode

• REPL mode (default): Interactive mode where you can have multi-turn conversations. The agent waits for your input after completing each task. Use /exit to quit.
• Once mode (--once): Non-interactive mode that runs a single prompt and exits. Useful for scripts and automation.

Safety Features

Path Safety

• All file operations are restricted to the repository root
• Path traversal attempts (../) are blocked
• Symlink escape attacks are prevented

Policy-Based Approval

• Dangerous commands (shell, delete, network) require user approval
• Large file changes trigger approval prompts
• Auto-approve mode (--yes) bypasses prompts (use with caution)

Environment Filtering

• Sensitive environment variables (API keys, tokens) are filtered from subprocess environments

Development

Building

dotnet build

Testing

dotnet test

Project Dependencies

Agent.Cli
  └── Agent.Core
  └── Agent.Tools
  └── Agent.Workspace
  └── Agent.Llm.Anthropic
  └── Agent.Llm.OpenAI
  └── Agent.Logging

Agent.Server

Agent.Server is an HTTP API server that exposes agent functionality over REST + Server-Sent Events (SSE).

Running the Server

dotnet run --project src/Agent.Server

By default, the server runs on http://localhost:5000.

Using the Node.js Client

# Install Node.js (v18+)
# Run the interactive client
node scripts/server-client.mjs --workspace /path/to/repo --provider openai

# Resume a session
node scripts/server-client.mjs --session <sessionId> --workspace /path/to/repo

API Endpoints

Endpoint	Method	Description
/api/sessions	POST	Create a new session
/api/sessions/{id}	GET	Get session info
/api/sessions/{id}/chat	POST	Send a message to the agent
/api/sessions/{id}/stream	GET	Stream agent events (SSE)
/api/sessions/{id}/approvals/{callId}	POST	Approve/deny a tool call
/api/sessions/{id}/resume	POST	Resume a session from log file

Features

• Server-Sent Events (SSE): Real-time streaming of agent responses
• Session management: Multiple concurrent agent sessions
• Approval workflow: Interactive approval of dangerous tool calls
• Session resumption: Resume conversations from JSONL logs

Documentation

• DESIGN.md - Design principles and architecture
• IMPLEMENTATION.md - Implementation details
• AGENTS.md - Agent architecture and extension guide
• CLAUDE.md - Instructions for AI assistants working on this codebase

License

Apache 2.0