Web Agent

Browser-native AI agent with isolated workspaces, persistent memory, and zero setup friction.

Live demo · GitHub · Personal Helper Playbook · Support on Ko-fi · Contributing · Security

Languages: English · 简体中文 · Español · العربية

Web Agent is an open-source AI agent that runs directly in the browser on top of WebContainers. There is nothing to install to use it: no Docker, no VPS, no VM, no Mac mini, no Hostinger box, no local Python stack. Open the app, launch a profile, and start working.

It is designed to feel simple for end users and capable for power users: isolated profiles, browser-local persistence, 50 built-in tools, 19 bundled skills, sessions, reflections, learnings, cron jobs, planning mode (/plan), a PARA + Obsidian-style knowledge vault (wiki_* tools and /wiki_* slash commands), and a self-improving runtime that stays on the user’s machine. For copy-paste scenarios mapped to skills and tools, start with the Personal Helper Playbook.

Contents

• Why Web Agent
• Highlights
• Capability Surface
• Slash Commands
• Settings And Providers
• Tooling
• Skills
• Workspace Features
• How Persistence Works
• Get Started Presets
• Personal Helper Playbook
• Quick Start
• Development
• Architecture At A Glance
• Privacy And Security
• Open Source
• Support And Sponsorship
• Contributing
• License

Why Web Agent

• Click and run. Launch from the browser with no install step for end users.
• Isolated by default. Every profile gets its own workspace, memory, and runtime state.
• Self-learning. Skills, reflections, learnings, facts, and session memory improve over time; Hermes-style post-turn background review can auto-create or patch skills after complex work; a curator consolidates agent-created skills on heartbeat while the tab is open — all browser-local.
• Local-first persistence. Workspaces, memory, sessions, and skills live in browser storage and can be exported or re-imported later.
• Hosted without server-side user state. The hosted demo serves the app, while user files and agent state stay in the browser.
• Open source. Free to use, fork, modify, and distribute under the MIT License.

Highlights

• Browser-native Node.js runtime powered by WebContainers
• Isolated profiles with separate workspaces and memories
• Built-in tools for files, shell, search, fetch, memory, sessions, cron, skills, and knowledge vault (wiki_setup, wiki_sync, wiki_search)
• /plan planning mode: research the workspace, save a dated markdown plan under plans/, present it with artifact_present, then execute on a follow-up message
• /wiki_setup · /wiki_sync · /wiki_search: deterministic shortcuts that route to the wiki tools (default vault root: .webagent/knowledge-vault/)
• Persistent fact store, rolling session memory, reflections, and learnings
• Hermes-style self-improvement: post-turn background review (skill + memory capture on complex turns), skill provenance (.webagent/skills/.usage.json), and periodic curator consolidation while the app tab is open
• Uploads into the live workspace with image handoff to vision tools
• Encrypted API keys stored locally in the browser
• Export and import flows for long-lived browser-local workspaces
• Hosted demo for zero-friction trial usage
• Tool loop guardrails (default on): Hermes-style deterministic detection of repeated tool failures and idempotent no-progress reads per turn; configure via VITE_WEBAGENT_TOOL_LOOP_* (see docs/agent-notes.md)
• Personal Helper Playbook: docs/use-cases-playbook.md — 25 copy-paste scenarios with bundled skills and typical tools

Capability Surface

Web Agent is not just a chat box. It is a browser-native agent runtime with three layers working together:

• ⌨️ Slash commands for fast operator control
• 🛠️ Tools for concrete actions in the workspace and on the web
• 📚 Skills for reusable procedures and higher-level behavior

At a glance

Layer	Count	Notes
Built-in tools	49	Eight groups below; skill CRUD consolidated into skill (action=manage) (plus list, view, bulk import)
Bundled skills	19	Hub skills route related workflows; workflow skills cover research, planning, delivery, and ops
Playbook scenarios	25	Full prompts in docs/use-cases-playbook.md

flowchart TB
  subgraph input ["👤 You"]
    U["👤 Operator"]
  end
  subgraph steer ["🎯 How you steer"]
    C["⌨️ Slash commands"]
    P["💬 Natural language"]
  end
  subgraph runtime ["⚙️ Agent runtime"]
    S["📚 Skills"]
    T["🛠️ Tools"]
  end
  subgraph sinks ["📦 Where work lands"]
    W["📁 Workspace files"]
    M["🧠 Memory layers"]
    A["⏱️ Cron & automation"]
    R["🌐 Web & vision"]
  end
  U --> C
  U --> P
  C --> S
  P --> S
  S --> T
  T --> W
  T --> M
  T --> A
  T --> R

Loading

Planning, wiki vault, and self-learning

These three loops sit beside the main capability diagram: planning produces reviewable specs before implementation; the wiki mirrors runtime memory into browseable markdown (Obsidian-friendly); self-learning ties facts, session notes, skills, reflections, and autonomous post-turn review together over time.

Planning (/plan)

flowchart TB
  subgraph plan ["📋 Planning mode · /plan"]
    direction TB
    P["📋 /plan + goal"] --> R["🔍 Read-only workspace research"]
    R --> W["✍️ write_file → plans/*.md"]
    W --> A["📄 artifact_present · view / download"]
    A --> N["⏸️ Stop — next turn: execute or revise"]
  end

Loading

Knowledge vault (wiki_* / /wiki_*)

flowchart TB
  subgraph scaffold ["🏗️ Scaffold once"]
    U["🧭 wiki_setup"] --> V["📂 PARA + KnowledgeVault"]
  end
  subgraph project ["🔄 Project runtime → vault"]
    M["🧠 memory_* · session_* · learnings"] --> S["🔁 wiki_sync"]
    V --> S
    S --> I["📑 index · log · ops"]
  end
  subgraph browse ["🔎 Browse & search"]
    Q["🔍 wiki_search"] --> V
  end

Loading

Self-learning loop

flowchart TB
  subgraph run ["🤖 Every turn"]
    X["🤖 Tools & conversation"]
    BR["💾 Post-turn background review"]
  end
  subgraph store ["🧠 What gets remembered"]
    F["💾 memory_* · durable facts"]
    SM["📝 session_memory_* · rolling notes"]
    SK["📚 skill_* · reusable SKILL.md"]
    RF["💡 reflections · promotable learnings"]
    U["📊 .usage.json · skill provenance"]
  end
  subgraph maintain ["🧹 Periodic maintenance"]
    C["🧹 Curator · consolidate & archive"]
  end
  subgraph mirror ["📓 Optional human mirror"]
    W2["📓 wiki_sync projection"]
  end
  X --> F
  X --> SM
  X --> SK
  X --> RF
  X -->|complex turn| BR
  BR --> SK
  BR --> F
  SK --> U
  U --> C
  C --> SK
  RF -.->|💡 hints| F
  RF -.->|💡 hints| SK
  F --> W2
  SM --> W2

Loading

Every turn: tool results feed facts, session notes, reflections, and learnings. Reflections and learnings surface as hints in later prompts (not automatic promotion).

After enough tool iterations (default 10 without a foreground skill write, WEBAGENT_SKILL_REVIEW_INTERVAL), a post-turn background review may run — non-blocking, after the user-visible reply — with restricted skill_* and memory_* tools. Memory review defaults to every 10 user turns (WEBAGENT_MEMORY_REVIEW_INTERVAL). Terminal summary example: Self-improvement review: Skill 'deploy-checklist' updated · Memory updated.

Skill provenance: skills created in background review are tagged created_by: agent in .webagent/skills/.usage.json (usage counters, lifecycle state). Curator runs on heartbeat (~weekly while the tab is open): stale/archive idle agent-created skills, consolidate overlaps; pinned skills opt out; archives go to .webagent/skills/.archive/ (no hard delete). Tune with WEBAGENT_CURATOR_INTERVAL_MS, WEBAGENT_CURATOR_STALE_AFTER_DAYS, WEBAGENT_CURATOR_ARCHIVE_AFTER_DAYS.

Inspect in UI: Files → Memory → Self-improve shows the live session feed (background review + curator summaries), curator state/reports, and agent-created skill provenance.

Semantic memory: memory_search blends substring matching with a persisted local embedding index (memory/fact-embeddings.json). Turn context also pulls semantically relevant facts for the active user goal alongside recent facts and high-signal learnings.

For choosing facts vs session vs skills vs vault, use the bundled /memory-layers skill.

Quick Capability Map

Area	What lives there	What it enables
⌨️ Commands	Session controls like /help, /compact, /plan, /checkpoint, /wiki_*	Faster navigation, recovery, planning, vault ops, and operator control
🛠️ Workspace tools	Read, write, edit, diff, move, search, shell	Real work inside an isolated project workspace
🧠 Memory tools	Facts, session notes, conversation recall	Persistent context that improves continuity
📓 Wiki tools	wiki_setup, wiki_sync, wiki_search	PARA-shaped markdown vault and search when memory tools are not enough
📋 Planning	/plan + write_file into plans/ + artifact_present	Spec-first workflows: plan now, implement on the next turn
⏱️ Automation tools	Heartbeat cron jobs and todos	Recurring tasks while the app is open
🌐 Remote tools	Search, fetch, email, Composio, vision, YouTube transcript	Web-aware, app-integrated, and multimodal task execution
📚 Skills	Reusable SKILL.md procedures	Higher-level workflows; background review and curator maintain agent-created skills

Slash Commands

These commands make the terminal experience feel like an operator console rather than a plain chatbot. They cover help, interruption, context compaction, planning mode, wiki vault shortcuts, checkpoint-based recovery, and direct skill invocation.

Command	What it does
/help	Show built-in commands and available tools.
/clear	Clear conversation history for a fresh thread; keeps agent and user identity.
/compact	Summarize older context and keep the current thread going.
/plan [goal]	Planning mode: research the workspace with read-only tools, write the full plan markdown under plans/, present it via artifact_present, then stop — reply on the next turn with “execute the plan” (or edits) to implement.
/find_skills [query]	Find-skills mode: search online skill registries (skills.sh, SkillsMP, Cursor Marketplace, etc.) and return the top 5 skills by installs, stars, or votes.
/clarify [topic]	Clarify mode: emit one structured clarification block when intent is ambiguous — no tools; UI shows choice buttons.
/checkpoint [name]	Save a named snapshot of current history for rollback.
/rollback [name]	List checkpoints or restore a named checkpoint.
/skills [search]	List installed skills, or search skills by query.
/wiki_setup [path]	Initialize the PARA + wiki scaffold (Projects/, Areas/, Resources/KnowledgeVault/…, Archives/). Optional workspace-relative root; default .webagent/knowledge-vault. Workspaces that still use the old default vault folder knowledge-vault/ are relocated automatically on the next wiki operation that omits root_path.
/wiki_sync [scope] [path]	Push runtime projections into the vault: facts, session, or all (includes learnings). Optional path after scope. Requires wiki_setup first.
/wiki_search <query>	Search markdown under the wiki vault (ranked hits + snippets).
/<skill> [task]	Invoke an installed skill for a task.
/stop	Interrupt the current run.
/exit	Exit the active terminal agent session.

📌 Tip: Use /find_skills pdf (or any topic) to discover popular skills online, then install with /skills install <url>.

📌 Tip: Use /skills to discover capabilities, then jump straight into a workflow with /<skill-slug> [task].

📌 Tip: Natural-language asks like “set up my knowledge vault” or “sync facts to the wiki” map to the same wiki_* tools as the /wiki_* slash commands.

Settings And Providers

Web Agent exposes provider configuration in two places: the profile editor for the active chat/model provider, and the Settings sidebar for browser-routed web tools and email delivery.

Model Providers

Each profile can choose its own provider, optional model override, API key, and personality. Current built-in profile providers are:

Provider	Type	Notes
OpenRouter	Hosted model router	Default provider with broad model access through one key.
Ollama (cloud)	Hosted OpenAI-compatible provider	Uses Ollama's cloud API rather than a local daemon.
Custom (OpenAI-compatible)	Bring-your-own endpoint	Supports a custom base URL and API key for compatible /v1 providers.

Browser Tool Providers

These power built-in web actions from the Settings panel:

Provider	Powers	Notes
TinyFish	web_search, web_fetch	Default browser-tool provider configured in Settings.
Resend	email	Used for outbound email with a verified sender address.
Composio	composio_status, composio_connect, composio_action	Curated marketing app bridge for Gmail, Sheets, HubSpot, Notion, Slack, LinkedIn, X/Twitter, and YouTube.

What You Can Configure

• 🧠 Per-profile model provider: choose the model backend for each agent profile.
• 🔧 Model override: set a specific model instead of the provider default.
• 🔐 Per-profile API key: store credentials separately from other profiles.
• 🌐 Custom base URL: point the custom provider at any OpenAI-compatible endpoint.
• ✉️ Email delivery: add Resend credentials for digest or outbound mail flows.
• 🔌 Composio: add a Composio key for approval-gated marketing app actions.

Tooling

Web Agent ships with 50 native built-in tools in eight groups. The surface was consolidated to one skill tool (action: list | view | manage | bulk) and one browse entry point browse_workspace (action: list | tree | find). Hidden aliases (list_dir, find_files, tree) remain for wire compatibility via tool_activate.

Tool Groups

Group	Includes	Best for
📁 Files & Workspace	read_file, write_file, edit_file, multi_edit, move_file, delete_file, browse_workspace, grep, file_diff, make_dir	Building, editing, inspecting, and organizing project files
🧠 Memory & Recall	memory_save, memory_forget, memory_recall, memory_search, session_memory_append, session_memory_list, session_search	Long-lived facts, stale fact cleanup, rolling notes, and recovering prior context
📓 Knowledge wiki	wiki_setup, wiki_sync, wiki_search	PARA + Obsidian-friendly vault under the workspace; project facts/session/learnings into markdown; full-text vault search
📚 Skills	skill (list / view / manage / bulk via action)	Discovering, reading, creating, importing, and maintaining skills
⏱️ Automation	cron_register, cron_list, todo_write	Recurring jobs, heartbeat-driven workflows, and checklists
🔌 App Integrations	composio_status, composio_connect, composio_action	Connecting marketing apps and running allowlisted external actions through Composio
🌐 Remote & Multimodal	web_search, web_fetch, web_post, vision_analyze, youtube_transcribe, email	Research, fetching live content, authenticated POST/GraphQL, image analysis, transcripts, and outbound delivery
🖥️ System & Output	run_shell, run_python, system_info, artifact_present, apply_patch	Browser-safe Node scripts, Pyodide-backed Python, environment state, artifacts, and surgical patching

🛠️ Full tool catalog

Tool	What it does
🩹 apply_patch	Apply unified patch operations for surgical file changes.
🪄 artifact_present	Present markdown to the browser host with view or download affordances.
📁 browse_workspace	List, tree, or find workspace paths (action: list
🧩 composio_action	Execute one curated, approval-gated Composio marketing action.
🔐 composio_connect	Create a hosted Composio auth link for an app.
🔌 composio_status	Check Composio setup, connected accounts, and the curated action allowlist.
📋 cron_list	List heartbeat cron jobs from .webagent/cronjobs.json.
⏱️ cron_register	Register recurring heartbeat jobs that run while the app tab is open.
🗑️ delete_file	Delete a file from the workspace.
🛠️ edit_file	Replace a matching snippet or fully replace file contents.
✉️ email	Send outbound email through Resend-configured delivery.
🧾 file_diff	Show a line-oriented diff between two UTF-8 workspace files.
🔍 grep	Search file contents by text or regex.
📂 make_dir	Create directories recursively inside the workspace.
🧹 memory_forget	Delete a stale or wrong saved memory fact by exact key.
💭 memory_recall	Recall a saved memory fact by exact key.
💾 memory_save	Save a durable memory fact under a stable key, with optional scope.
🔮 memory_search	Search saved memory facts by substring.
📦 move_file	Move or rename a workspace path.
🛠️ multi_edit	Apply multiple find-and-replace edits in one file.
📄 read_file	Read a UTF-8 file from the workspace.
🐍 run_python	Run stdlib/Pyodide-compatible Python in browser-only Nodebox with optional args, env, packages, and workspace file sync.
🖥️ run_shell	Run browser-safe node ..., python3 ..., and simple read-only probes in the workspace runtime.
📝 session_memory_append	Append a lightweight note to rolling session memory.
🗂️ session_memory_list	Read the newest entries from rolling session memory.
📇 session_search	Search archived workspace conversations by keywords.
🧩 skill	List, view, manage, or bulk-import skills (action: list
📟 system_info	Return a safe system snapshot including time, timezone, uptime, and memory.
✅ todo_write	Create or update checklist-style todos.
🖼️ vision_analyze	Analyze an image with the configured vision model.
🌐 web_fetch	GET http(s) URL(s), optional auth headers for REST reads.
📮 web_post	POST http(s) with headers and body (GraphQL, REST writes).
🌍 web_search	Search the web and return ranked results.
🔖 wiki_search	Search markdown files under the wiki vault root; ranked snippets when memory_search is not enough.
📓 wiki_setup	Create the PARA + Resources/KnowledgeVault/ scaffold (idempotent).
🔁 wiki_sync	Update vault index.md / log.md and write ops/wiki-sync-*.md from facts, session tail, and/or learnings.
🎙️ audio_analyze	Transcribe workspace audio via the browser STT worker (Telegram voice notes, uploaded audio).
✍️ write_file	Write text to a file and create parent folders as needed.
📹 youtube_transcribe	Fetch a full YouTube transcript with timestamps.

Skills

Skills are reusable procedures stored as SKILL.md files. They let Web Agent switch from raw tool usage to structured workflows that can be invoked on demand.

Bundled Skills (19)

Hub skills — route related workflows and cross-skill tables:

Slash command	Hub for
/memory-layers	Facts, session notes, wiki mirror, session_search
/browser-runtime-map	WebContainer limits, shell failures, file layout
/http-api	REST GET (web_fetch) and POST/GraphQL (web_post) — auth, query shapes, CMS patterns
/imported-skill-compat	Imported skills from other hosts → Web Agent tools, including run_python
/artifact-delivery	Reports, email, charts, presentation patterns
/web-agent-skill	Evolving Web Agent itself (runtime, skills, cron, repo truth)

Workflow skills — focused procedures (invoke with /<slug> [task] or pick from /skills):

Slash command	What it is for
/open-web-research	Fan-out web discovery with verified fetches
/research-pack	Scholarly / citation-heavy research
/structured-extraction	Tables or JSON from live pages
/find_skills	Search online skill registries (top 5 matches)
/task-execution	In-session plan (todo_write) then execute
/knowledge-vault	Wiki-backed project knowledge and searchable markdown context
/heartbeat-cron	Recurring jobs while the tab is open
/project-scaffold	Isolated folder before generating files
/workspace-safety	Checkpoints, bulk ops, safe reorganize
/systematic-debugging	Hypothesis-and-experiment debug loop
/multimodal-ingest	Vision, YouTube transcripts, audio paths
/chart	Mermaid flowcharts via artifact_present
/clarify	One structured clarification block (no tools)

📌 Tip: /plan is a slash mode (spec under plans/, execute on the next turn), not a bundled skill. Pair it with /task-execution when you want todos inside the same session.

See docs/use-cases-playbook.md for all 25 scenarios mapped to these skills.

Why Skills Matter

• 🧩 Reusable: a good workflow only needs to be written once.
• 🛡️ Safer: skills encode preferred patterns before the agent starts changing files.
• ⚡ Faster: /skill-slug [task] is quicker than re-explaining a workflow every session.
• 🧠 Teachable: users can grow the agent by saving new procedures directly into the workspace.
• 🔄 Self-improving: after complex turns, background review can patch or create skills automatically; curator keeps the library consolidated over time.

Wiki vs memory (short)

• memory_* / session_* hold the canonical structured context the runtime uses.
• wiki_sync projects summaries and sync markers into markdown for humans (or Obsidian); treat the vault as a browseable mirror, not a second source of truth, unless you intentionally archive prose there.

Workspace Features

Every profile gets its own isolated workspace rooted in browser storage. The workspace layer is designed to feel like a lightweight project environment, not just an attachment bucket.

Feature	What it means
📁 Isolated per profile	Each agent profile gets its own workspace and runtime state.
💾 Persistent snapshots	Files survive reloads using browser-side persistence.
📤 Export / Import	The Workspaces tab can export a profile snapshot to JSON and import it later.
🖼️ Upload handoff	Uploaded files land in the live workspace, including image paths for vision tools.
🧰 File operations	Read, write, edit, diff, move, delete, list, grep, and tree tools all operate inside the workspace.
🖥️ Live shell access	The runtime can execute supported workspace commands in the browser-native Node environment.
📋 Saved plans	/plan writes timestamped markdown under plans/ (workspace-relative; legacy .webagent/plans/ still readable).
📓 Knowledge vault	Default .webagent/knowledge-vault/ PARA tree with Resources/KnowledgeVault/ for wikilinks, logs, and ops detail files after wiki_sync. Older knowledge-vault/ trees migrate automatically when you use default wiki paths.
🧹 Clean reset	Destroy a single profile workspace or nuke all local agent state from the sidebar.
📊 Storage visibility	The Workspaces tab shows browser storage usage and quota.

Workspace UX

• Workspaces tab: export, import, destroy, and inspect browser storage usage for the active profile.
• Files popup: browse the live /workspace, preview files, and interact with the working tree.
• uploads/: user-uploaded assets are normalized under uploads/ for safe tool access.

How Persistence Works

Web Agent keeps user state in browser storage on the user’s machine. That includes workspaces, sessions, memory, facts, learnings, skills (including .webagent/skills/.usage.json provenance and .archive/ for curator moves), todos, cron metadata, curator state under .webagent/skills/.curator_state, saved /plan markdown under plans/ (legacy .webagent/plans/ paths remain readable), wiki vault files under .webagent/knowledge-vault/ by default (legacy knowledge-vault/ at the workspace root is automatically moved there when wiki tools run without an explicit root_path), and local credentials. Nothing in that persistent agent state is meant to live on the server.

As long as the browser keeps its local storage and OPFS data, the agent keeps its history and workspace. When you want portability, export the workspace or browser-local state and import it later on the same machine or another one.

For hosted deployments, the safest framing is:

• The app can be hosted anywhere
• The agent state lives in the browser
• The server should only deliver the app and relay allowed upstream requests when needed

Self-hosting (Railpack / Dokploy): Use the repo railpack.json for deploy.startCommand (scripts/start-with-proxy.sh) and deploy.aptPackages (extends defaults with caddy). Do not add a start script in package.json for this: Railpack treats it as a custom start command, skips the built-in static+Caddy image path, and the sidecar setup breaks. The checked-in Caddyfile matches Debian’s apt Caddy (~2.6) (no persist_config or global trusted_proxies block). web_fetch / web_search without TinyFish rely on the small Node listener in scripts/cors-proxy-server.mjs (default 127.0.0.1:8799).

Get Started Presets

Copy-paste starting points. Adjust paths and keys for your machine.

Hosted trial

1. Open webagent.aratech.ae.
2. Create or select a profile → add an API key from OpenRouter or Ollama.
3. Click Launch → send a short task (e.g. “list files in the workspace”).

Recommended model on OpenRouter: Gemma 4 (good speed, price, and tool calling). Any compatible model works.

Local development

git clone https://github.com/nikola66/web-agent.git
cd web-agent
npm install
cp .env.example .env.local   # optional: tool guardrails, debug log, launch mode
npm run dev

Open http://localhost:5173. Tool guardrail env vars are documented in .env.example.

Operator workflows

Planning — spec first, implement on the next turn:

/plan Add a /health route and document it in README

Review the plan under plans/, then on the next message:

Execute the plan you just wrote.

Knowledge vault — PARA markdown mirror of memory:

/wiki_setup
/wiki_sync all
/wiki_search deployment

Default vault root: .webagent/knowledge-vault/. Legacy knowledge-vault/ at workspace root migrates automatically.

Personal Helper Playbook

Twenty-five personal-helper scenarios with copy-paste prompts, bundled skills, and the tools that typically fire. Full cards with example prompts live in docs/use-cases-playbook.md. Prompts are in English — paste as-is into chat.

Filter by category: Research · Memory · Planning · Automation · Workspace · Debug · Multimodal · Delivery · UX · Safety · Meta

Category	Use case	Bundled skill(s)	Key tools
Research	Find niche creators / competitors	/open-web-research	web_search, web_fetch, write_file, artifact_present
Research	Academic paper / citation dig	/research-pack	web_search, web_fetch, write_file, artifact_present
Research	Extract a table or JSON from a page	/structured-extraction	web_fetch, write_file, artifact_present
Meta	Discover installable skills online	/find_skills	web_search, web_fetch, skill (action=manage)
Memory	Save a durable preference	/memory-layers	memory_save, memory_recall
Memory	Capture rolling session context	/memory-layers	session_memory_append, session_memory_list
Memory	Mirror memory into Obsidian-style vault	/memory-layers	wiki_setup, wiki_sync, wiki_search
Memory	Find something from an old chat	/memory-layers	session_search
Planning	Spec-first feature plan (no execution yet)	/plan	read_file, grep, write_file, artifact_present
Planning	Plan and execute multi-step work	/task-execution	todo_write, write_file, artifact_present
Automation	Daily digest while tab is open	/heartbeat-cron	cron_register, cron_list, web_search, web_fetch
Workspace	Bootstrap a new side project folder	/project-scaffold	make_dir, write_file, browse_workspace
Workspace	Reorganize files safely	/workspace-safety, /browser-runtime-map	browse_workspace, move_file
Debug	Hypothesis-first bug hunt	/systematic-debugging	read_file, grep, file_diff, run_shell
Debug	Shell / npx failed in WebContainer	/browser-runtime-map	read_file, web_fetch, grep
Multimodal	Read a screenshot or diagram	/multimodal-ingest	vision_analyze, write_file
Multimodal	Summarize a YouTube tutorial	/multimodal-ingest	youtube_transcribe, write_file, artifact_present
Delivery	Present a finished report in-app	/artifact-delivery	write_file, artifact_present
Delivery	Email a deliverable	/artifact-delivery	write_file, email, artifact_present
Delivery	Flowchart for a plan or report	/chart	artifact_present
UX	Disambiguate a vague ask	/clarify	(none)
Safety	Checkpoint before bulk delete	/workspace-safety	browse_workspace, delete_file
Safety	Pasted API key by mistake	/artifact-delivery	Redact in replies; save to memory only when user asks
Meta	Improve Web Agent itself	/web-agent-skill	read_file, grep, skill (action=manage), memory_save

Quick Start

Use the hosted demo

Open webagent.aratech.ae, create or select a profile, add a free key from OpenRouter.ai or Ollama, click Launch, and start chatting.

For Web Agent, Gemma4 is the recommended chat model because it strikes a strong balance between speed, price, and tool-calling support, including images and vision. Voice input is transcribed locally in the browser via whisper-tiny.en (English). You can choose any chat model you prefer.

Run locally

git clone https://github.com/nikola66/web-agent.git
cd web-agent
npm install
npm run dev

Open http://localhost:5173.

Development

npm run dev
npm run build
npm run test
npm run test:browser

Contributor-facing docs:

• docs/README.md — docs hub (English + translations)
• docs/use-cases-playbook.md — 25 personal-helper scenarios (prompts, skills, tools)
• CONTRIBUTING.md
• AGENTS.md — rules for AI coding agents
• CAPABILITIES.md
• docs/ARCHITECTURE.md — system map, IPC protocol, storage layers
• docs/agent-notes.md — tool guardrails, WebContainer, persistence
• docs/testing-checklist.md
• docs/GLOSSARY.md · docs/TRANSLATING.md

Architecture At A Glance

• Frontend: React + Vite + xterm.js
• Runtime: Node.js inside WebContainers
• Persistence: IndexedDB + OPFS in the browser
• Isolation: profile-scoped workspaces and runtime state
• Model access: OpenRouter or OpenAI-compatible providers
• Plans & vault: timestamped plans under plans/ (legacy .webagent/plans/ readable); optional PARA wiki tree (default .webagent/knowledge-vault/) synchronized via wiki_* tools
• Tool loop guardrails: per-turn deterministic detection of repeated tool failures and idempotent no-progress reads; thresholds in .env.example
• Self-improvement loop: post-turn background review + skill provenance + heartbeat curator (Hermes-inspired; see Self-learning loop)

The agent runtime is embedded into the browser app, mounted into a live workspace, and launched inside a terminal-backed Node environment. Profiles keep personalities, settings, workspace state, and memory separated.

Privacy And Security

• Workspace files, sessions, memory, skills, and local credentials stay browser-side.
• API keys are stored locally and encrypted before persistence.
• Profiles are isolated from each other.
• Hosted mode should remain transit-only for upstream requests, not a persistence backend for user state.

See SECURITY.md for reporting and security posture details.

Open Source

Web Agent is an open-source project. You are free to use it, fork it, modify it, and distribute it under the MIT License.

Inspired by OpenClaw, Hermes Agent, and OpenCrabs.

Special thanks to the Nodebox used technology and the open source project behind it. It is beautiful software and made Web Agent possible.

Support And Sponsorship

If Web Agent saves you time or helps your work, support ongoing development on Ko-fi. Sponsorship helps fund continued maintenance, new capabilities, UI polish, and long-term improvements.

Support on Ko-fi

Star on GitHub

Sponsor This Project

Sponsor project Place logo here

Sponsor project Place logo here

Sponsor project Place logo here

Contributing

Issues and pull requests are welcome. Start with CONTRIBUTING.md, keep changes surgical, and prefer fixes that preserve the project’s browser-native and local-first design.

License

MIT. See LICENSE.