Usda Code

Open-source AI coding agent with a terminal-first experience, multi-model support, and full tool execution.

Write code, run commands, manage files — all from your terminal with any LLM provider.

✨ Features

• Terminal-First UI — Full-screen interactive interface with animated feedback, keyboard shortcuts, and word-by-word response streaming
• Multi-Model Support — Works with OpenAI, Anthropic, Google, NVIDIA, OpenRouter, Ollama, vLLM, or any OpenAI-compatible API
• Dual Agent Modes — Full execution mode for active coding, planning mode for safe analysis
• Tool System — Filesystem operations, shell commands, and git integration with structured validation
• Session Persistence — Resume conversations across restarts with usda -r <sessionId>
• Plugin Architecture — Extend with custom tools and providers
• Human-in-the-Loop — Approval system for destructive operations; toggle with -a for auto-approve
• Cross-Platform — macOS, Windows, Linux

📦 Installation

npm i -g usda-code

Requires Node.js 18+.

🚀 Quick Start

# Interactive mode — opens the full terminal UI
usda

# Run a single task directly
usda "create a REST API with Express"

# Auto-approve all tool actions (no y/n prompts)
usda -a

# Resume a previous session
usda -r <sessionId>

On first run, usda will walk you through selecting a provider, model, and API key. Configuration is saved to usda.config.yaml in the current directory.

⌨️ Keyboard Shortcuts

| Key | Action | |-----|--------| | Tab | Autocomplete /commands | | Ctrl+O | Expand/collapse latest thinking | | Ctrl+E | Expand/collapse latest prompt | | Ctrl+J | Toggle all collapsed/expanded items | | Ctrl+C ×2 | Exit (double-press within 2s) |

🔧 Configuration

Create usda.config.yaml in your project root (or let usda generate it on first run):

provider:
  provider: openrouter
  model: anthropic/claude-sonnet-4-20250514
  apiKey: sk-or-...
  baseUrl: https://openrouter.ai/api/v1
  temperature: 0.7
  maxTokens: 4096

agent:
  mode: full            # full | planning
  maxSteps: 50
  requireApproval: false
  blockedCommands:
    - rm -rf
    - format
    - shutdown
  commandTimeout: 30000

🔌 Supported Providers

| Provider | Base URL | Example Models | |----------|----------|----------------| | OpenAI | https://api.openai.com/v1 | gpt-4o, gpt-4o-mini | | Anthropic | https://api.anthropic.com | claude-sonnet-4-20250514, claude-3-haiku | | Google | https://generativelanguage.googleapis.com/v1beta/openai | gemini-2.0-flash | | NVIDIA | https://integrate.api.nvidia.com/v1 | meta/llama3-70b-instruct | | OpenRouter | https://openrouter.ai/api/v1 | Any model on OpenRouter | | Ollama | http://localhost:11434/v1 | llama3.1, mistral, deepseek-coder | | vLLM | http://localhost:8000/v1 | Any locally hosted model | | Custom | User-defined | Any OpenAI-compatible endpoint |

📝 Slash Commands

Type these during interactive mode:

| Command | Description | |---------|-------------| | /help | Show all commands | | /model | Change the current model | | /provider | Switch provider | | /key | Update API key | | /mode | Toggle between full and planning mode | | /auto | Toggle auto-approve | | /status | Show session stats (steps, tokens) | | /clear | Clear the screen | | /new | Start a new session | | /q | Quit |

🛠️ What Usda Code Can Do

• Read, write, create, and edit files in your project
• Run shell commands — install deps, run builds, execute tests
• Search and refactor codebases — grep, analyze, restructure
• Git operations — stage, commit, diff, log
• Debug issues — trace errors, inspect logs, fix code
• Multi-step tasks — break down complex work into logical steps

🏗️ Architecture

src/
├── agents/        # Full & Planning agent implementations
├── approval/      # Human-in-the-loop approval system
├── cli/           # Terminal UI (renderer, input handling)
├── config/        # YAML config loader & types
├── plugins/       # Plugin system (extensible tools)
├── providers/     # LLM provider adapters (OpenAI, Anthropic, etc.)
├── session/       # Session persistence & memory
├── tools/         # Built-in tools (filesystem, shell, git)
└── utils/         # Logger, helpers, env

📄 License

MIT