CSAgent is a cross-platform autonomous coding agent that runs on Windows, Linux, and macOS. It uses an OpenAI-compatible API (e.g., Albert API) to understand natural-language instructions and autonomously perform coding tasks by reading, writing, and listing files, as well as executing shell commands.
It ships with three presentation modes — a terminal UI (TUI), a web UI, and a lean UI.
# Set your API key
set ALBERT_API_KEY=your-api-key-here
# Run the web server
csagent --ui
Then open your browser to http://localhost:5050 (or the port you chose with --port).
set ALBERT_API_KEY=your-api-key-here
dotnet run
In CLI mode, CSAgent presents a text-based interactive session. You type instructions, and the agent autonomously works through them step by step.
> User: Create a new C# console project that prints "Hello, World!"
The agent will:
Type exit to quit the session.
In Web UI mode (--ui flag), CSAgent starts a local web server with a modern, dark-themed interface featuring:
The web UI is served at http://localhost:5050 by default. Use --port <n> (or -p <n>) to change the port.
Lean UI mode (--leanui flag) is a lightweight duplicate of the Web UI. It serves the same embedded assets and SSE-based chat endpoints, launched via the --leanui command-line argument. It is served at http://localhost:5050 by default (use --port <n> to change it).
CSAgent uses different LLM models depending on the mode of operation. This is intentional — each model is chosen for its strengths in the specific context.
| Mode | Default Model | Rationale |
|---|---|---|
| CLI | deepseek-v4-flash |
Fast, lightweight, ideal for interactive terminal sessions where quick turnarounds matter |
| Web UI | Qwen/Qwen3-Coder-30B-A3B-Instruct |
More capable for complex multi-step coding tasks; the Web UI is designed for longer, more involved sessions |
You can override the default model in any mode using the --model argument (see Command-Line Arguments).
# CLI mode with a different model
csagent --model gpt-4o
# Web UI mode with a different model
csagent --ui --model deepseek-v4-flash
The following capabilities are planned for future releases:
| Variable | Required | Description |
|---|---|---|
ALBERT_API_KEY |
Yes | Your API key for the OpenAI-compatible endpoint |
| Argument | Description |
|---|---|
--ui |
Start in Web UI mode (starts a web server) |
--leanui |
Start in Lean UI mode (lightweight duplicate of the Web UI) |
--mem <file> |
Specify a custom memory/conversation file (default: agent_memory.json) |
--model <model> |
Override the default LLM model for the current mode |
--port, -p <n> |
Web UI port number (default: 5050) |
--dry-run |
Simulate tool execution without making changes |
--max-retries <n> |
Max attempts for HTTP 429 (rate limit) retries (default: 3) |
--retry-delay <ms> |
Base backoff delay in ms before the first retry (default: 1000) |
--help, -h, /? |
Display help and exit |
--version |
Display the current version of CSAgent and exit |
--doc |
Display this documentation in a nicely formatted terminal view and exit |
<file> |
Positional argument: specify a memory file without --mem flag |
# Web UI with custom memory file
csagent --ui --mem my_project_memory.json
# Lean UI mode
csagent --leanui
# Web UI on a custom port
csagent --ui --port 8080
# CLI mode with a specific memory file
dotnet run my_memory.json
# Dry run mode
csagent --dry-run
# Display version
csagent --version
# Display documentation in terminal
csagent --doc
# Override the LLM model in CLI mode
csagent --model gpt-4o-mini
# Override the LLM model in Web UI mode
csagent --ui --model deepseek-v4-flash
# Tune rate-limit retry behavior
csagent --max-retries 5 --retry-delay 2000
CSAgent includes multiple layers of safety to prevent accidental damage to your system:
The write_file tool is classified as destructive because it modifies files on disk. Before executing, the agent will prompt for confirmation:
[?] Allow destructive action 'write_file'? [Y/n]
Shell commands (sh) are not classified as destructive by default, but they are still filtered for dangerous operations (see below).
File operations (write_file, read_file, list_dir) are restricted to the current working directory and its subdirectories. Attempts to access files outside this scope are blocked:
Error: write_file - Path 'C:\Windows\System32\config' is not allowed for writing.
Shell commands are scanned for potentially dangerous patterns before execution. The filter is platform-aware:
Blocked patterns include:
format — Format drivesdel /f / del /s — Force/recursive deletionrd /s / rmdir /s — Recursive directory removalreg delete / reg add / reg import — Registry manipulationnet user / net localgroup / net share — System administrationtakeown / icacls / cacls — Permission/ownership changesbcdedit / diskpart — Boot/disk configurationrunas / powershell start-process -verb runas — Privilege escalationshutdown / reboot — System control\windows\system32\ / \windows\system\ — System directory access\program files\ — Protected directory accessBlocked patterns include:
sudo — Privilege escalationchmod — Permission changesshutdown / reboot — System controldd — Low-level disk operationsmkfs — File system creation/etc/ / /usr/bin/ / /bin/ — System directory accessAll shell commands have a 60-second timeout. If a command takes longer, it is automatically killed:
Error: command timed out (60s).
Reading files larger than 500 KB is blocked to prevent memory issues:
Error: file too large (1024 KB). Use sh to grep/head.
The agent has access to four built-in tools:
write_fileWrite (or overwrite) a text file. Parent directories are created automatically.
Parameters:
path (string, required) — File pathcontent (string, required) — UTF-8 content to writeread_fileRead a text file and return its content.
Parameters:
path (string, required) — File pathlist_dirList files and subdirectories in a directory.
Parameters:
path (string, optional, default: .) — Directory to listrecursive (boolean, optional, default: false) — Whether to list recursivelyshExecute a shell command. Uses cmd.exe on Windows, /bin/sh elsewhere.
Parameters:
cmd (string, required) — Shell command to runCSAgent saves the conversation history to a JSON file (default: agent_memory.json). This allows the agent to maintain context across sessions.
--mem <file> or as a positional argumentdotnet build
# CLI mode
set ALBERT_API_KEY=your-key
csagent
# Web UI mode
set ALBERT_API_KEY=your-key
csagent --ui
CSAgent supports Ahead-of-Time (AOT) compilation for fast startup and single-file deployment:
# Publish as a single-file AOT binary
dotnet publish -c Release -r win-x64 # Windows
dotnet publish -c Release -r linux-x64 # Linux
dotnet publish -c Release -r osx-x64 # macOS
The AOT build produces a self-contained executable with no runtime dependencies.
Ensure the ALBERT_API_KEY environment variable is set before running.
Your API key is invalid or expired. Check your credentials.
You’ve hit the rate limit. CSAgent now retries automatically with exponential
backoff (honoring the server’s Retry-After header when present). If the error
persists after all retries, the API is still rate-limiting you — wait a moment
and try again. You can tune the retry behavior with --max-retries and
--retry-delay (see Command-Line Arguments).
The shell command took longer than 60 seconds. Try breaking the task into smaller steps.
The file exceeds the 500 KB read limit. Use sh with tools like grep, head, or find to inspect specific parts.
File operations are restricted to the current working directory. Change to the target directory before running the agent, or use shell commands to copy files into the workspace.
Navigate manually to http://localhost:5050 in your browser (or the port you chose with --port).
This project is provided as-is. It is built entirely on the .NET base class library with zero NuGet dependencies.
CSAgent — Maximum autonomy, minimal dependencies.