Usda Code - Open Source AI Coding Agent

A powerful, model-agnostic AI coding agent with a terminal-first experience, designed for developer productivity, extensibility, and full transparency.

Features

• Terminal-First TUI: Keyboard-driven, fast, minimal latency interface
• Multi-Model Support: OpenAI, Anthropic, Google, NVIDIA, OpenRouter, Ollama, vLLM
• Dual Agent Modes: Full execution mode and planning (safe) mode
• Tool System: Filesystem, shell, git operations with structured validation
• Session Memory: Persistent context across conversations
• Plugin Architecture: Extensible via custom tools and providers
• Human-in-the-Loop: Explicit approval system for safe mode
• Cross-Platform: macOS, Windows, Linux support

Installation

npm install -g usda-code
# or
yarn global add usda-code

Quick Start

# Initialize in your project
usda init

# Start in full mode
usda agent

# Start in planning mode
usda agent --mode planning

# Specify model provider
usda agent --provider openai --model gpt-4

Configuration

Create a usda.config.yaml in your project root:

provider: openai
model: gpt-4
apiKey: ${OPENAI_API_KEY}
baseUrl: https://api.openai.com/v1
temperature: 0.7
maxTokens: 4096

# Provider-specific settings
providers:
  anthropic:
    model: claude-3-opus-20240229
    apiKey: ${ANTHROPIC_API_KEY}
  openai:
    model: gpt-4
    apiKey: ${OPENAI_API_KEY}
  ollama:
    model: llama3
    baseUrl: http://localhost:11434/v1

Agent Modes

Full Agent (Execution Mode)

usda agent --mode full

• Full read/write access to filesystem
• Shell command execution
• Can run builds, tests, install dependencies
• Includes safeguards (timeouts, logging)

Planning Agent (Safe Mode)

usda agent --mode planning

• Read-only access to codebase
• Cannot execute commands or modify files
• Produces step-by-step plans and proposed diffs
• Requires explicit user approval for actions

Supported Providers

Architecture

usda-code/
├── src/
│   ├── agents/           # Agent implementations
│   │   ├── base.ts       # Base agent interface
│   │   ├── full.ts       # Execution mode agent
│   │   └── planning.ts   # Planning mode agent
│   ├── providers/        # LLM provider implementations
│   │   ├── base.ts       # Provider interface
│   │   ├── openai.ts     # OpenAI provider
│   │   ├── anthropic.ts  # Anthropic provider
│   │   ├── google.ts     # Google provider
│   │   ├── nvidia.ts     # NVIDIA provider
│   │   ├── openrouter.ts # OpenRouter provider
│   │   └── ollama.ts     # Ollama provider
│   ├── tools/            # Tool implementations
│   │   ├── base.ts       # Tool interface
│   │   ├── filesystem.ts # File read/write operations
│   │   ├── shell.ts      # Shell command execution
│   │   ├── git.ts        # Git operations
│   │   └── registry.ts   # Tool registry
│   ├── tui/              # Terminal UI components
│   │   ├── app.tsx       # Main TUI application
│   │   ├── components/   # UI components
│   │   └── theme.ts      # Styling and theme
│   ├── session/          # Session management
│   │   ├── manager.ts    # Session lifecycle
│   │   └── memory.ts     # Persistent memory
│   ├── plugins/          # Plugin system
│   │   ├── loader.ts     # Plugin loader
│   │   └── registry.ts   # Plugin registry
│   ├── config/           # Configuration system
│   │   └── loader.ts     # Config parsing and validation
│   └── cli/              # CLI entry point
│       └── index.ts      # Command definitions
├── electron/             # Desktop app wrapper
│   ├── main.js           # Electron main process
│   └── preload.js        # Preload script
└── package.json

Example Workflows

Fix Failing Tests

usda run "Fix the failing tests in the project"

Add a Feature

usda run "Add user authentication to the login page"

Code Review

usda run "Review the changes in the current PR" --mode planning

Plugin Development

Create custom tools by extending the base tool interface:

import { BaseTool, ToolResult } from 'usda-code';

export class MyCustomTool extends BaseTool {
  name = 'my_tool';
  description = 'Does something useful';
  
  schema = z.object({
    param: z.string(),
  });

  async execute(input: { param: string }): Promise<ToolResult> {
    // Implementation
    return { success: true, output: 'Result' };
  }
}

License

MIT