Documentation

Overview

wardayacode is an AI-powered coding agent that lives in your terminal. It understands natural language requests and can read, write, and edit files, run shell commands, manage git, and more — all through a conversation-based interface.

Built on a ReAct (Reasoning + Acting) loop using the Vercel AI SDK, wardayacode supports multiple LLM providers out of the box and includes a flexible permission system that puts you in control.

Key highlights:

Multi-provider — Claude (Anthropic), GPT-4 (OpenAI), Gemini (Google)
Permission modes — 5 modes from full-auto to read-only
Slash commands — built-in command palette for common operations
Session management — conversations persist as JSONL, resume across restarts
Undo & checkpoints — revert changes and restore git checkpoints
Open source — MIT licensed, contributions welcome

Installation

Prerequisites

Node.js 20 or newer. Check your version:

node --version

Install globally

Recommended for daily use:

npm install -g wardayacode

After installation, you can use either the full name or the short alias:

wardayacode    # full command
wdc            # short alias

Run with npx

Try it without installing:

npx wardayacode

Set up API keys

wardayacode needs at least one API key to operate. Set them as environment variables:

# Anthropic (Claude)
export ANTHROPIC_API_KEY=sk-ant-...

# OpenAI
export OPENAI_API_KEY=sk-...

# Google (Gemini)
export GOOGLE_GENERATIVE_AI_API_KEY=AIza...

Or save them permanently:

wardayacode auth login anthropic
wardayacode auth login openai
wardayacode auth login google

Running from source

Clone the repo and run without building:

git clone https://github.com/fawwazmw/wardayacode
cd wardayacode
npm install
npm run dev

Configuration

Config files

wardayacode loads configuration from multiple sources, merged in order (highest priority wins):

CLI flags — --model, --provider, --mode, etc.
Project config — .wardayacode.json in your project root
User config — ~/.config/wardayacode/config.json
Default values — built-in sensible defaults

Example config

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "permissionMode": "default",
  "maxTokens": 8192,
  "temperature": 0,
  "maxRetries": 3,
  "theme": "dark",
  "apiKeys": {
    "anthropic": "sk-ant-...",
    "openai": "sk-...",
    "google": "AIza..."
  }
}

Environment variables

API key environment variables are read at runtime, not during config load. Supported vars:

ANTHROPIC_API_KEY
OPENAI_API_KEY
GOOGLE_GENERATIVE_AI_API_KEY

Env vars are checked after config file merging, so they override any key in the config file.

Permission Modes

wardayacode asks before making changes. You control how much it can do automatically:

Mode	File reads	File writes	Bash / Git	Use when
`default`	✅ Auto	❓ Prompt	❓ Prompt	Daily use
`plan`	✅ Auto	❌ Blocked	❌ Blocked	Review-only
`acceptEdits`	✅ Auto	✅ Auto	❓ Prompt	Trusted edits
`auto`	✅ Auto	✅ Auto	✅ Auto	Scripting / CI
`internal`	✅ Auto	✅ Auto	✅ Auto	Fully trusted

Switch mode mid-session with /mode <name> or choose "Always allow" when prompted. Dangerous operations (force push, rm -rf, dd) are permanently blocked regardless of mode.

Slash Commands

Type / in the TUI to open the command palette, or type any of these directly:

Command	Description
`/help`	Show all available commands
`/clear`	Clear the conversation
`/compact`	Manually compact context to free up token budget
`/mode <mode>`	Switch permission mode
`/model`	Show current model
`/session`	Show session info
`/tokens`	Show real token usage (from provider)
`/undo`	Revert the last file change
`/diff`	Show uncommitted git changes
`/checkpoint`	Create a git stash checkpoint
`/rollback`	Restore last checkpoint
`/login <provider> <key>`	Save an API key
`/logout <provider>`	Remove a saved API key
`/auth`	Show provider auth status
`/exit`	Exit wardayacode

Tools

The agent has access to these tools for interacting with your codebase:

Tool	What it does
`read_file`	Read a file with optional line range
`write_file`	Create or overwrite a file
`edit_file`	Surgical string-replacement edits
`bash`	Run shell commands
`git`	Run git commands
`glob`	Find files by pattern (*/.ts)
`grep`	Search file contents with regex
`list_files`	List a directory

Tools are permission-gated. Read-only tools are allowed by default; destructive operations are blocked or require confirmation depending on the active permission mode.

Sessions

Conversations are saved automatically as JSONL files in .wardayacode/ in your project directory. This lets you continue where you left off across terminal restarts.

Session commands

wardayacode sessions list          # list all sessions
wardayacode sessions delete <id>   # delete a session
wardayacode --resume <id>          # resume a session

Sessions include every message, tool call, and result. The /compact command can manually reduce context to free up token budget when conversations grow long.

Development

wardayacode is open source under the MIT license. Contributions are welcome.

Setup

git clone https://github.com/fawwazmw/wardayacode
cd wardayacode
npm install
npm run dev            # run from source (no build)
npm run build          # bundle to dist/
npm run type-check     # TypeScript strict check
npm run lint           # ESLint
npm test               # Vitest watch mode
npm run test:run       # single CI run

Branch strategy

The project uses Git Flow with two permanent branches:

main — production, matches the latest npm release
develop — integration branch, default for PRs

Branch naming: feature/xxx, fix/xxx, release/x.x.x, hotfix/x.x.x. Both main and develop are protected — CI must pass before merging.

Release process

Create a GitHub release on main to trigger automated npm publishing (never run npm publish manually). The .github/workflows/publish.yml workflow builds, type-checks, tests, and publishes with provenance.

Troubleshooting

`command not found: wardayacode`

Ensure npm global binaries are in your PATH:

npm config get prefix   # add <prefix>/bin to PATH

API key errors

wardayacode auth list    # check which providers are configured
wardayacode auth login anthropic   # re-enter the key

Agent makes too many changes

Use /mode plan to switch to read-only mode mid-session, or start with --mode plan.

Long conversations lose context

wardayacode automatically compacts context when it nears the token limit. You'll see a system message. Use /clear to start fresh, or /compact to manually compact.

Something went wrong and files were changed

/undo          # revert the last file edit
/rollback      # restore to last git checkpoint
/diff          # see what changed