README
¶
Warden
Describe the task. Skip the script.
Warden is an AI agent that lives in your terminal and controls your Windows machine. You tell it what to do in plain English — it figures out the steps, runs them, and shows you what's happening in real time.
It sees your screen, runs shell commands, edits files, drives the browser. No IDE plugin. No Electron wrapper. No cloud account required.
Get it
Unzip anywhere. Two binaries, one folder, zero setup. Run warden.exe and pick your LLM provider on first launch.
# Or build from source (Go 1.25+, Python 3.11+)
just release
What it's for
You have a task that's annoying enough to think about but not worth writing a script for. Warden handles those.
> find the five largest files on my desktop and zip them into archive.zip
> go through my Downloads, delete anything older than 30 days, keep PDFs
> open Chrome, go to GitHub, close any PR that's been sitting for 90 days
> check why the last CI run failed and show me the relevant logs
> rename all the screenshots in this folder to match the date they were taken
It works across your whole machine — shell, browser, file system, running processes — and streams every action back to you as it goes.
How it works
You type a task
│
▼
Screenshot → model reasons over what it sees
│
▼
Runs a command / clicks / types / scrolls
│
▼
Screenshot again → confirm it worked
│
▼
Next step (or done)
Every action is visible in the chat stream. Ask mode pauses before writes and mouse clicks so you stay in control. Auto mode lets the agent run freely when you trust the task.
Toggle between them with Shift+Tab at any time.
Safety
Actions are classified by code — not by the model — before anything runs.
| Level | What | Behaviour |
|---|---|---|
| Safe | Read-only: file reads, screenshots, git status, browser reads |
Runs immediately |
| Confirm | Writes, installs, mouse/keyboard, process kills | Pauses in Ask mode |
| Blocked | Recursive deletes outside workspace, encoded payloads, registry changes | Always rejected |
Fail-safe: slam the mouse into the top-left corner to abort any automated action mid-run.
Memory
Warden remembers facts about your projects and workflow between sessions — stored locally in SQLite, injected into context each turn.
/memory on # enable
/memory off # disable
/memory status # inspect what's stored
/memory clear # wipe everything
Skills
Reusable instruction sets in plain Markdown. Drop a SKILL.md into .warden/skills/<name>/ and invoke it with !:
!<skill-name> # run a skill
!<cmd> # run a PowerShell command directly
! # list all available skills
Skills live in .warden/skills/ (project) or ~/.warden/skills/ (global).
Configuration
Pre-configure with ~/.warden-config.json to skip the setup wizard:
{
"model": "poolside/laguna-m.1:free",
"api_url": "https://openrouter.ai/api/v1",
"api_key": "sk-or-v1-..."
}
The API key is encrypted on disk (DPAPI on Windows). Key and auth token are passed to the backend via stdin — never in environment variables. Every backend request is authenticated with a shared secret generated at startup.
Use WARDEN_MODEL to override the model via environment variable. Works with Ollama (local) or any OpenAI-compatible API.
Controls
| Key | Action |
|---|---|
Enter |
Send message |
Esc |
Interrupt agent |
Esc × 2 |
Force-stop |
Shift+Tab |
Toggle Ask / Auto mode |
Tab |
Complete slash command or skill |
↑ / ↓ |
Navigate input history |
Scroll |
Scroll chat output |
Ctrl+W |
Delete last word |
Ctrl+C |
Exit |
Slash commands
| Command | Action |
|---|---|
/connect |
Set up provider and model |
/models |
Switch model on the fly |
/clear |
Clear chat, reset session |
/compact |
Summarize context to free tokens |
/memory |
Manage memory |
/select |
Enable text selection mode |
/update |
Download and install latest release |
/verbose |
Show tool calls and diffs |
Stack
| Layer | Technology |
|---|---|
| TUI | Go 1.24+, bubbletea, lipgloss, glamour |
| Backend | Python 3.11+, aiohttp |
| LLM | Ollama or any OpenAI-compatible API |
| Screen & input | pyautogui, Pillow |
| Browser | Playwright |
| Search | duckduckgo-search |
Frontend and backend are fully decoupled over HTTP NDJSON. Either can be swapped independently.
Build & test
just build # Go TUI only
just build-backend # Python backend (requires PyInstaller)
just release # Both
just install # Python deps
just test # pytest with coverage
just test --no-cov -q # Quick run
just test-go # Go tests
just lint-go # Go vet
just fmt-go # Go format diff
Troubleshooting
| Symptom | Fix |
|---|---|
port 8765 is busy |
Another instance running — taskkill /F /IM warden.exe |
ollama is not responding |
Install Ollama and start it |
| Backend exits immediately | Check .warden/backend.err.log |
License
MIT
Documentation
¶
Index ¶
- Variables
- func AccentStyle() lipgloss.Style
- func ConfirmNStyle() lipgloss.Style
- func ConfirmYStyle() lipgloss.Style
- func DimStyle() lipgloss.Style
- func ErrorStyle() lipgloss.Style
- func FaintStyle() lipgloss.Style
- func HeaderStyle() lipgloss.Style
- func HoverStyle() lipgloss.Style
- func Run(backend Backend, modelName string, connected bool) error
- func SlashDescStyle(active bool) lipgloss.Style
- func SlashNameStyle(active bool, autoMode bool) lipgloss.Style
- func ToolStyle() lipgloss.Style
- func WardenStyleAuto(autoMode bool) lipgloss.Style
- type Backend
Constants ¶
This section is empty.
Variables ¶
var ( Green = lipgloss.Color("#8AB89A") GreenMid = lipgloss.Color("#2D8A5A") GreenFaint = lipgloss.Color("#1A4D34") Blue = lipgloss.Color("#38BDF8") BlueMid = lipgloss.Color("#0EA5E9") BlueFaint = lipgloss.Color("#0C4A6E") Red = lipgloss.Color("#ff4444") Dim = lipgloss.Color("#666666") DimHover = lipgloss.Color("#999999") Faint = lipgloss.Color("#2a2a2a") White = lipgloss.Color("#ffffff") )
Functions ¶
func AccentStyle ¶
func ConfirmNStyle ¶
func ConfirmYStyle ¶
func ErrorStyle ¶
func FaintStyle ¶
func HeaderStyle ¶
func HoverStyle ¶
func SlashDescStyle ¶
func WardenStyleAuto ¶
Types ¶
type Backend ¶
type Backend interface {
StreamChat(payload map[string]string) <-chan client.Event
Interrupt() error
ResetSession() error
SendQuestion(id string, answers [][]string) error
SendConfirm(id string, ok bool) error
SetMode(auto bool) error
GetStatus() (*client.StatusResult, error)
Compact() (*client.CompactResult, error)
SetMemoryState(enabled bool) error
ClearMemory() (int, error)
GetMemoryState() (*client.MemoryState, error)
ListModels() ([]string, string, error)
SetModel(name string) error
ListSkills() ([]client.Skill, error)
LoadSkill(name string) (string, error)
Connect(provider, apiURL, apiKey, modelName string) error
BaseURL() string
}
Source Files
Directories