Swades Agent Logo

XERV: Swades

Autonomous AI software engineering agent for your terminal

Bottom Line Up Front: Swades Agent is an open-source, terminal-native autonomous AI coding agent built on the ReAct (Reasoning + Acting) loop pattern. You give it a coding task in plain text, and it reads your codebase, edits files with surgical precision, and iterations until the task is done — all without leaving your terminal.

GitHub Repository Setup & Installation View Tools

Key Capabilities

ARCHITECTURE:
ReAct loop
COMPATIBILITY:
OpenAI API (OpenRouter, Groq, Ollama)
UI / UX:
Real-time token streaming
EDIT MODE:
Partial file patching
INTELLIGENCE:
Automatic codebase indexing
AUTONOMY:
24/7 Director mode

1. What is Swades Agent?

Swades Agent is an open-source, terminal-native autonomous AI coding agent built on the ReAct (Reasoning + Acting) loop pattern. It works with any OpenAI-compatible API, streams tokens to the terminal in real-time as the model thinks, and runs automatic syntax validation on every file it writes.

No GUI. No cloud lock-in. No build step. ~800 lines of plain Node.js.

  • ReAct agentic loop — Thought → Tool Call → Observation → repeat until task is solved
  • Real-time token streaming — see the model's reasoning and tool arguments token-by-token as they arrive
  • Partial file patching — edits only the exact block that needs changing, not the entire file
  • Automatic codebase indexing — maps your repo structure before starting, so the model never re-scans blindly
  • Built-in syntax checker — validates bracket matching, indentation consistency, and runs node --check on every JS save
  • 24/7 Director mode — a second "Director" model instance reviews progress after each run and writes the next subtask on behalf of the user
  • Workspace isolation — when installed inside a project subdirectory, the agent hides its own files from the model so it only sees your code

2. Setup & Installation

Step 1: Install Node.js

You need Node.js v18 or later (v22 recommended).

node -v

Step 2: Clone & Install Dependencies

git clone https://github.com/Electroiscoding/reactsystemlearning1.git
cd reactsystemlearning1
npm install

Step 3: Configure your Environment

cp .env.example .env

Open .env and fill in your values for your preferred OpenAI-compatible provider.

3. Environment Variables

API_KEY
Required Your LLM provider API key
BASE_URL
Default: https://openrouter.ai/api/v1 Provider base URL
MODEL
Default: openrouter/free Model identifier string
MAX_STEPS
Default: 30 Max tool-call iterations per agent run
MAX_OUTPUT_LENGTH
Default: 10000 Character cap on tool output returned to the model
WORKDIR
Default: process.cwd() Absolute or relative path the agent operates on

4. Agent Tools

The agent has access to 7 core tools it can call during a run. Automatic validation ensures safe execution on every write.

Tool Name Arguments Description
index_codebase (none) Scans workspace, writes .agent_index.json with file paths, sizes, imports, exports, classes, functions
read_file path, start_line?, end_line? Returns file contents with line numbers. Supports partial reads by line range.
write_file path, content Writes a complete new file. Runs syntax + indentation checks on save.
patch_file path, target, replacement Replaces a unique block within an existing file. Fails with clear error if ambiguous.
list_dir path, recursive? Lists directory tree. Skips node_modules, .git, and the agent's own folder.
grep_search pattern, path, include? Runs grep -rnI across the workspace.
run_command command, cwd? Executes a shell command with 30s timeout. Prompts for confirmation on destructive patterns.

5. Architecture & Safety

The Swades Agent relies on several files, including index.js (CLI entry), agent.js (ReAct loop), director.js (Multi-cycle supervision), and llm.js (Streaming SDK Wrapper).

Safety & Guardrails

  • Workspace isolation & self-hiding: The agent filters out its own folder from list_dir and grep_search. The model cannot modify its own source files.
  • Dangerous command blocking: Shell commands matching rm -rf, sudo, and others pause execution and require explicit user confirmation.
  • Step cap: The worker agent stops after MAX_STEPS iterations (default 30) to prevent infinite loops.
  • Session Memory: Persists session history to .agent_memory.json so context is available across multiple distinct runs.