Cude Code - Professional AI Development CLI

A provider-agnostic, safety-first AI coding agent for the terminal.

Current release: v0.2.0 · Changelog · Security policy

Cude Claw

Cude Claw is Cude Code's autonomous workflow mode: it plans a task, uses the built-in tools, verifies its work, and reports a truthful completion or failure status.

cude run "inspect the project, fix the failing tests, and summarize the changes"

For automation, use --json --yes to emit one machine-readable result:

cude run "run the tests and report failures" --yes --json

Create a read-only implementation plan before making changes:

cude plan "Add authentication to the API and cover it with tests"

Review local changes and inspect optional code-intelligence integrations:

cude review
cude doctor
cude doctor --json

Real language-server diagnostics and isolated parallel workers are available when the corresponding tools are installed:

cude lsp diagnostics src/index.ts
cude task --task "Review the API" --task "Review the tests"

Each worker receives its own detached Git worktree under .cude/worktrees/; changes are never merged automatically. This keeps parallel agent work reviewable and prevents workers from silently overwriting one another.

Project memory is explicit and local. Save durable decisions or workflow notes with cude memory add; entries are stored as JSONL in .cude/memory.jsonl and included in the agent context on the next run. Use cude memory list to inspect them or pass a search term to filter. Nothing is captured automatically:

cude memory add "Use npm test for verification" --tags testing,workflow
cude memory list testing

# Slogan-driven workflow
cude write "Add request validation to the API"
cude understand src/index.ts
cude produce "Implement the feature and leave it tested and reviewed"
cude subagent list
cude subagent run code-reviewer "Check the authentication changes" --json
cude mcp list

The slogan is executable workflow, not decoration: write makes a focused change, understand gives a read-only architecture/risk summary, and produce implements the request, verifies it, then reviews the resulting diff.

Hooks and subagents

Hooks are configured in .cude/hooks.json and run at session_start, pre_tool_use, post_tool_use, or session_end. A failing pre_tool_use hook blocks the tool call unless allowFailure is set. Hook commands receive CUDE_HOOK_EVENT, CUDE_TASK, CUDE_TOOL_NAME, CUDE_TOOL_ARGS, CUDE_TOOL_SUCCESS, and CUDE_TOOL_OUTPUT environment variables.

{
  "hooks": {
    "pre_tool_use": [
      { "command": "node scripts/check-tool.js", "timeoutMs": 10000 }
    ],
    "post_tool_use": [
      { "command": "npm run lint", "allowFailure": true }
    ]
  }
}

Named subagents are Markdown files under .cude/agents/. Their frontmatter supports name and description; the Markdown body is the specialist prompt and is run in its own agent context.

MCP servers are configured in .cude/mcp.json using the standard stdio transport. Discovered MCP tools are added to the agent automatically with names like mcp__github__search. Use cude mcp list to verify discovery and cude mcp call <tool> '{"query":"..."}' for a direct JSON call.

doctor detects installed LSP servers, debuggers, and optional omp/pi bridges. Cude Code does not silently claim LSP or DAP support when the required server is absent.

Before an autonomous run, Cude Code automatically loads project instructions from AGENTS.md, CLAUDE.md, or .cude-context.md in the current directory and its parents. The closest AGENTS.override.md replaces the matching file. Use cude context to audit the active files. Context is capped and truncated safely so a large instruction file cannot consume the whole model window. Project skills can be placed at .cude/skills/<name>/SKILL.md or .agents/skills/<name>/SKILL.md.

Mutating file tools are confined to the workspace root, destructive commands require confirmation, and failed or budget-exhausted runs exit with status 1. See docs/CUDE-CLAW.md for the workflow and extension guide.

The professional, multi-provider AI development CLI for your terminal

Cude Code is a feature-rich CLI tool for AI-assisted development. It ships with 19 built-in providers, dynamic custom OpenAI-compatible endpoints, 22 built-in agent tools plus MCP tools, browser automation, native RAG, durable CudeClaw jobs, and brings professional capabilities to your terminal.

Long-running work and custom models

Queue durable work for CudeClaw and keep the worker running in a separate terminal or service:

cude claw add "inspect the repository, implement the fix, and run the tests" --provider ollama --model llama3.1
cude claw worker
cude claw list

Jobs are persisted under ~/.cude/claw-jobs.json, so a restart does not lose queued work. The worker is intentionally foreground and service-friendly: on Windows use Task Scheduler, and on Linux/macOS use systemd/launchd. It cannot execute while the computer is powered off.

Any OpenAI-compatible endpoint can be registered, including LM Studio, llama.cpp, vLLM, LiteLLM, Ollama-compatible gateways, or a private gateway:

cude providers add my-local --base-url http://localhost:1234/v1 --model my-model --local
cude providers add my-gateway --base-url https://llm.example.com/v1 --model coder --api-key-env MY_GATEWAY_KEY
cude providers custom-list

Custom providers receive the same agent loop and tool schema as built-ins. Use --api-key-env for secrets; provider definitions are stored in the Cude config directory.

Conversation visibility is available both inside chat (/history 20, /summary, /activity) and without reopening a session:

cude sessions show <id-or-name>
cude sessions export <id-or-name>

The activity panel reports observable model calls, tool calls, approvals, warnings, errors, cost, and tokens. It never claims to expose private chain-of-thought.

git clone https://github.com/Emrevrg/Cude-Code.git
cd Cude-Code && npm install && npm run build && npm link
cude chat

Why Cude Code?

Free & Open Source: MIT licensed, no hidden costs
19 AI Providers: OpenAI, Anthropic, Gemini, DeepSeek, Groq, Ollama, and more
22 Agent Tools: File ops, git, npm, diff, patch, search, browser, RAG
Browser Automation: Navigate, screenshot, and extract web content via Playwright
Native RAG: Index local codebases and search with keyword matching
Autonomous Agent: Solve complex tasks with tool-use
Cost Tracking: Monitor spending, set budgets, get alerts
Session Management: Save and restore conversations
Project Context: Compatible AGENTS.md/CLAUDE.md instructions with a cude context audit command
Privacy First: Everything stays on your machine
Pure CLI: No Electron, lightweight and fast

Quick Start

One-line install

npm install -g github:Emrevrg/Cude-Code
cude setup

The setup wizard configures a provider, model, workspace rules, and optional local integrations. Verify the installation with cude doctor and inspect the available providers with cude providers list.

From source

1. Install

Not on npm yet. Install from source — this builds the CLI and puts cude on your PATH:

git clone https://github.com/Emrevrg/Cude-Code.git
cd Cude-Code
npm install
npm run build
npm link

Optional — only needed for the three browser tools:

npx playwright install chromium

2. Setup

cude setup

3. Start Coding

# Free chat with no API costs
cude chat --free

# Chat with GPT-4
cude chat -p openai -m gpt-4

# Run an autonomous task
cude run "Create a REST API in TypeScript"

Usage Examples

Interactive Chat

# Start a conversation
cude chat

# Use specific provider and model
cude chat -p anthropic -m claude-opus-5

# Continue a previous session
cude chat -s my-project

# Use only free providers
cude chat --free

Autonomous Tasks

# Code generation
cude run "Write a React component for data table"

# Code review
cude run "Review src/api and suggest improvements"

# Bug fixing
cude run "Fix the error in main.ts"

# Documentation
cude run "Generate API docs for src/"

Configuration

# Interactive setup
cude setup

# Set API keys
cude config set-key openai sk-...
cude config set-key anthropic sk-ant-...

# List configured keys
cude config list-keys

# Set defaults
cude config set default-provider openai
cude config set default-model gpt-4o

Provider Management

# List all providers
cude providers list

# Test connectivity
cude providers test

# View available models
cude providers models openai

Budget Management

# Set spending limit
cude budget set 10          # $10 total
cude budget set 5 --monthly # $5/month

# Check spending
cude budget status

# Set alert
cude budget alert 5

Session Management

# List sessions
cude sessions list

# Export session to markdown
cude sessions export <id> conversation.md

# Delete session
cude sessions delete <id>

Create an independent branch of a saved conversation with:

cude sessions fork <id> experiment

Project Context

# Show the instruction files the agent will load
cude context

During a chat, use /summary for a compact audit of observable turns, model calls, tools, approvals, errors, token usage, and cost. Use /activity for the latest event list. The audit records what the application observed; it does not expose private model chain-of-thought or API credentials.

Upstream design influences

Cude Code keeps its TypeScript, provider-agnostic core while adopting useful workflow ideas from oh-my-pi and Pi coding-agent: explicit project context, safe tool boundaries, resumable sessions, and an extensible terminal-first workflow. Their native Rust/monorepo internals are not copied into this repository, so Cude Code remains installable with Node.js and keeps its existing provider and tool compatibility.

Supported Providers

Free & Fast

Groq: Free tier, fastest responses
Gemini Flash: Free tier, best quality for free
Ollama: Local only, completely free

Production Quality

OpenAI: GPT-4 family, most capable
Anthropic: Claude 5 family (Opus 5, Sonnet 5), best reasoning
Google Gemini: Latest models, large context
DeepSeek: Affordable, excellent for code

Self-Hosted

Ollama: Local models, no setup needed
vLLM: High-performance serving
llama.cpp: Minimal requirements

Complete List

OpenAI, Anthropic, Google Gemini, Groq, DeepSeek, Mistral, xAI, Cohere, Together AI, Perplexity, NVIDIA, OpenRouter, Azure OpenAI, LiteLLM, HuggingFace, vLLM, Replicate, Local GGUF, Ollama

Available Tools

Cude Code's agent can use 22 built-in tools:

File Operations

read_file, write_file, replace_in_file (multi-occurrence via replace_all), delete_file, copy_file, move_file (rename), get_file_info

Directory Management

create_directory, list_directory

Search

search_files (pattern), grep_search (content)

Shell & Build

run_command, npm_command, git_command

Patch & Diff

apply_patch (multi-hunk unified diff), diff_files (file comparison)

Browser Automation

browser_navigate (fetch page content), browser_screenshot (capture pages), browser_extract (CSS selector extraction)

Native RAG

rag_index (index local files), rag_search (keyword search across indexed files), rag_summary (index overview)

Destructive commands (e.g. rm -rf, mkfs., shutdown) trigger an interactive confirmation before execution.

Cost Tracking

Built-in budget management:

# Set $10 spending limit
cude budget set 10

# Get real-time spending report
cude budget status

# Set $5 per-month limit
cude budget set 5 --monthly

# Get alerts at $8
cude budget alert 8

Supported cost tracking for:

OpenAI, Anthropic, Google, Groq, and all cloud providers
Per-token pricing for accuracy
Historical tracking and reports

Documentation

Changelog - Release notes
Contributing - Development setup and project layout
Security - Reporting vulnerabilities, and what the agent can reach

Configuration

Environment Variables

export CUDE_OPENAI_KEY="sk-..."
export CUDE_ANTHROPIC_KEY="sk-ant-..."

Keys are looked up in this order, per provider:

CUDE_<PROVIDER>_KEY
CUDE_<PROVIDER>_API_KEY
the provider's conventional name — OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, GROQ_API_KEY, REPLICATE_API_TOKEN and so on, so keys already in your shell are picked up without renaming them
~/.cude/config.json, written by cude config set-key

Environment variables are read at startup and take precedence over the stored config, which is handy for CI runs and ephemeral shells.

Defaults are not environment variables — set them with:

cude config set default-provider openai
cude config set default-model gpt-4o

Config Files

Linux/macOS: ~/.cude/config.json
Windows: %USERPROFILE%\.cude\config.json

Sessions are stored under ~/.cude/sessions/ and spending records under ~/.cude/budget.json.

Security

All data stored locally
No cloud sync (unless enabled)
API keys never logged
Destructive commands require confirmation
Safe command execution
Open source for transparency

Release validation

Cude Code v0.2.0 is accompanied by a reproducible local verification record, not a marketing score or a vendor comparison.

The latest verification run recorded 94 passing tests, 0 failures, successful TypeScript compilation, and 0 lint errors. See the full release validation record, including the remaining non-blocking lint advisories and how the result was measured.

Contributing

We welcome contributions! Areas we need help with:

License

Free for personal and commercial use.

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: zgremre@gmail.com
In-app help: run cude --help or cude <command> --help

Roadmap

Current (v0.2)

19 AI providers
Chat & autonomous agent modes
22 agent tools (file ops, git, npm, diff, patch, search, browser, RAG)
Browser automation via Playwright
Native RAG with local file indexing
Session management
Cost tracking with budgets & alerts
Environment-variable key fallback
Automatic legacy data migration
MCP tools, hooks, named subagents and project skills
Durable CudeClaw job queue and worker
Custom OpenAI-compatible local or hosted providers
Conversation transcripts and observable activity summaries

Planned (v0.3)

VS Code extension
Advanced analytics & spend reports

Future (v1.0)

Web UI dashboard
Plugin system
Team collaboration features

Made with care by developers, for developers

Cude Code - Where AI meets your terminal

Name		Name	Last commit message	Last commit date
.github		.github
assets		assets
docs		docs
src		src
test		test
tools		tools
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

Cude Code - Professional AI Development CLI

Cude Claw

Hooks and subagents

Long-running work and custom models

Why Cude Code?

Quick Start

One-line install

From source

1. Install

2. Setup

3. Start Coding

Usage Examples

Interactive Chat

Autonomous Tasks

Configuration

Provider Management

Budget Management

Session Management

Project Context

Upstream design influences

Supported Providers

Free & Fast

Production Quality

Self-Hosted

Complete List

Available Tools

File Operations

Directory Management

Search

Shell & Build

Patch & Diff

Browser Automation

Native RAG

Cost Tracking

Documentation

Configuration

Environment Variables

Config Files

Security

Release validation

Contributing

License

Support

Roadmap

Current (v0.2)

Planned (v0.3)

Future (v1.0)

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages