WrongStack

Ships with a Brain, a Memory, and a full toolbox. Yours to run anywhere.

A free, open-source AI coding agent that gets better at your codebase over time. It reads code, runs tools, and coordinates specialist agents — with durable memory, visible permission boundaries, and no subscription required.

---

macOS / Linux — one self-contained binary, no Node.js needed

curl -fsSL https://wrongstack.com/install.sh | sh

Windows

irm https://wrongstack.com/install.ps1 | iex

---

WrongStack is free, open source, and MIT licensed. Give its leader a task: It can work directly or delegate independent parts to specialist agents. The Brain evaluates policy decisions; SAGE retains project knowledge across sessions; Kanban tracks work and verification; the mailbox links agents across clients; and Chimera reviews their diffs. Autonomous goal loops and parallel workers use these same systems, rather than a separate agent engine. Built-in tools, bundled skill playbooks, managed first-party plugins and a live models.dev provider catalog sit on a compact, swappable kernel.

The coding loop compares completed tool results when detecting repetition. With the LSP plugin and hooks enabled, successful single and bulk file edits include bounded, version-bound diagnostics or an explicit unverified notice. Research briefs preserve API/version evidence and unresolved questions. See agent feedback.

Built from scratch, stands on its own. WrongStack is not a plugin layer or an orchestration kit bolted onto another coding tool — it's a complete agent written top to bottom: its own compact kernel, its own provider transports with real SSE, its own tool executor, permission policy, memory system, and multi-agent runtime. Nothing here wraps a third-party CLI; everything works standalone.

The scale of it

Not a thin wrapper — a real engine. The codebase is first-party, TypeScript-strict source across a full monorepo, guarded by an extensive test suite. Memory, tools, providers, permissions, and the multi-agent runtime are all first-party and work together, on your machine, with no upstream agent to phone home to.

What's new in 1.1.7

• VibeUI, a seventh interface: wstack vibeui (--vibeui, port 3476) opens a focused coding workspace between SimpleUI and the full WebUI: queued chat with Queue / Steer / BTW, provider and account setup, files and diffs, live agents, quotas, SAGE memory with a relationship graph, and next-step suggestions that can submit on their own under YOLO + Auto.
• Text selection in the TUI: a Text mode beside Block copies only the selected visible text; switch it in Settings or the composer footer.
• WebUI refresh and desktop focus: a reworked workbench look with locally served provider logos, and Tab moves between the desktop shell and its WebUI.
• Correctness fixes: ACP turns survive a slow permission decision, an idle project daemon shuts down again, a rejected intake suggestion stays rejected, one corrupt SAGE row no longer breaks unrelated memory operations, and MCP transports, the token store and the OAuth callback are hardened.

Highlights from 1.1.6, the previous release:

• WrongForge leads with its tools: a session started on the wrongforge provider sends its turns to WrongForge with the session's tools, and the calls it makes through them appear as tool cards.
• Confirmable tools behind the token-saving tier: tool_use and mcp_use ask for confirmation like a direct call, so pwsh, exec, fetch, git and MCP tools work with YOLO off on the default tier.
• Plugins cannot pose as built-ins: a plugin may change only the tools it registered itself, and only official plugins may register as core.

1.1.5 added wstack tools for built-in tools without MCP, WrongForge as leader or worker and the WebUI agent tree; 1.1.4 pointed ACP agents at the project's index, memory, mailbox and board and added the mailbox inbox action over MCP; 1.1.3 made an installed ACP agent such as Claude Code a session leader (/model acp/claude-code), added delegated Claude workers and removed the Claude sign-in; 1.1.2 made file edits lossless, kept stores from overwriting files they cannot parse, kept secrets out of history and sync and made safety refusals terminal; 1.1.1 added /browser allow loopback and ChatGPT quota readings; 1.1.0 added request residency, last-request cache readouts and leaner tool-error context; 1.0.37 added Bun-first development, browser setup, codebase-read-symbol and the Skill Companion; 1.0.36 added phase-aware leader effort, per-worker effort routing and audit-driven hardening; 1.0.35 hardened command guards, secret redaction and dependency audits; 1.0.34 added project goals, explicit continuation, YOLO+ and the dead-code workflow.

See the release history for earlier releases.

New here? Jump to Install → Quick start. Already running it? Keep current with wstack update.

---

Table of contents

• Why WrongStack
• How WrongStack compares
• Requirements
• Install
• Staying current
• Quick start
• Surfaces
• Core capabilities
• Configuration
• Architecture
• Status
• Docs
• License

---

Why WrongStack

• It remembers your project. SAGE keeps long-term memory in SQLite/FTS5, anchored to files, symbols, commands and commits and re-verified as they change.
• A fleet that coordinates. A Director splits work across a specialist roster, one project mailbox links every agent, client and worktree, and each role learns the practice that works in this repo.
• Goals that end verified. /goal loops until a locked contract passes, the Brain rules on risky calls, and Kanban cards reach Done only when their criteria pass.
• Seven surfaces, one engine. REPL, TUI, WebUI, SimpleUI, VibeUI, Desktop and the cross-machine HQ share the same sessions and memory.
• Any model, including local ones. API keys or subscription sign-in, a models.dev catalog, Ollama / vLLM / LM Studio presets, and per-role routing with fallback chains.
• Guarded where it counts. Encrypted secrets and a permission policy on every tool call; opt-in project-root containment that neither YOLO nor a repo-committed config can turn off; Chimera reviews your diffs.

The full list is under Core capabilities.

---

How WrongStack compares

Most AI coding tools are either a single-agent CLI or an orchestration kit around someone else's agent CLI. WrongStack is a complete agent written from scratch:

	Wrapper / orchestration-only tools	WrongStack
Core	Coordinates an external agent CLI	Own kernel, provider transports and built-in tools
Memory	Usually none, or bolted-on files	SAGE — code-anchored SQLite/FTS5 memory, recalled every turn
Multi-agent	Orchestrates external processes	Native fleet + Director with isolated budgets and one mailbox
Local-only	Needs the upstream tool and network	Runs on localhost with Ollama / vLLM / LM Studio presets
Surfaces	One terminal	Seven — REPL, TUI, WebUI, SimpleUI, VibeUI, Desktop, HQ
Safety	Depends on the wrapped tool	Per-call permission policy and Chimera review of your diffs

---

Requirements

• Standalone binary: nothing — the executable carries its own runtime (Windows x64/arm64, macOS x64/arm64, Linux x64/arm64 incl. musl)
• Development from source: Bun ≥ 1.4.3; see the Bun workflow

---

Install

Standalone binary (recommended)

One executable per platform with the runtime, every surface and all bundled assets inside — nothing else to install:

# macOS / Linux
curl -fsSL https://wrongstack.com/install.sh | sh

# Windows
irm https://wrongstack.com/install.ps1 | iex

The installers download the build for your OS/CPU (musl is detected on Linux), verify it against the release SHA256SUMS, and install wstack plus a wrongstack alias into ~/.wrongstack/bin. The musl builds need the C++ runtime (apk add libstdc++ libgcc on Alpine). Set WSTACK_VERSION=1.2.3 to pin a release or WSTACK_INSTALL_DIR to install elsewhere. You can also download a wstack-<os>-<arch> file from the releases page and put it on your PATH yourself.

On first run the binary unpacks its assets (prompts, skills, design kits, grammars, the WebUI/HQ/SimpleUI frontends) once into ~/.wrongstack/runtime/<version>/.

Not available in the binary: the WebUI terminal panel (needs the native node-pty addon), the Electron desktop shell, and the browser tool unless Playwright is installed separately. The HQ systemd installer (wstack hq service install) does not support the binary; run wstack hq under your own service manager instead.

The TUI is lazy-loaded behind --tui, so plain-REPL users pay no React/Ink cost at startup. The browser UI, HQ, and Desktop shell are available through their launch flags (see Surfaces).

For standalone CLI users, Desktop is a separate Electron application distributed through GitHub Releases. wstack --desktop opens an installed application; portable/custom locations use WRONGSTACK_DESKTOP_EXECUTABLE. See Desktop distribution for installation and release details.

Then just run:

wrongstack        # or the short alias: wstack

From a source checkout, the same built CLI can run directly on Bun:

bun run build
bun run start:bun

bun run smoke:bun verifies Bun's SQLite-backed SAGE path, heap watchdog, WebUI server module graph, and CLI entry point. Node continues to use node:sqlite; Bun selects bun:sqlite automatically.

To run HQ as a boot-persistent, auto-restarting systemd service with password authentication and an optional IP/CIDR admission list, see HQ service.

---

Staying current

Update the CLI in place from inside the tool:

wstack update                 # download + verify the latest release
wstack update --check-only    # is a newer release available?

wstack update pulls from GitHub Releases and checks the download against the release SHA256SUMS before swapping the executable in place. Re-running the install one-liner does the same thing.

Full flag reference: CLI reference → Updating.

---

Quick start

# First run — interactive auth/setup, then a launch menu on a TTY
wstack

# Add an API key or sign in with a ChatGPT/Codex subscription
wstack auth

# Skip the picker and pin a provider/model
wstack --provider anthropic --model claude-sonnet-4

# TUI with an explicit YOLO override
wstack --tui --yolo

# Director fleet orchestration
wstack --director

# Single-shot query (non-interactive)
wstack -p "explain packages/core/src/kernel"

# Resume a saved session
wstack --resume

First run walks you through authentication and model selection. No config? The interactive provider/model picker launches automatically. Switch providers any time at runtime with /model.

Full flag and subcommand reference: docs/cli-reference.md.

---

Surfaces

Surface	Launch	Best for
REPL	wstack	Fast, dependency-light terminal use
TUI	wstack --tui	Rich full-screen terminal with panels
WebUI	wstack --webui	Browser chat + tool/diff/session panels
SimpleUI	wstack --simpleui	Fast, focused standalone browser chat (see below)
VibeUI	wstack --vibeui	Focused coding workspace between SimpleUI and WebUI (see below)
Desktop	wstack --desktop	Electron shell over a token-gated local WebUI
HQ	wstack --hq	Cross-machine command center for a whole team

Plain wstack on a TTY opens a launch menu; add --no-menu to go straight to the REPL. See WebUI for the browser surface details.

WebUI, SimpleUI and VibeUI keep their host terminal compact: repeated warnings share one row, logs and finished workers disappear after 30 seconds, and live worker rows fit the terminal. Use WEBUI_VERBOSE=1 for full console output.

The WebUI's Story button opens Session Story: a visual timeline of the selected tab and its subagents, with activity charts, team branches, replay, and recorded file, memory, and mail evidence. Its dashboard tabs expose measured tool averages/P95 and file read/edit/write counts, with recorded source and diff line statistics where available. The Models tab compares provider/model reliability, measured latency and spend, and recorded work/quality signals across the leader and its subagents. The secondary sidebar pins Story at the top and switches it to Back to session when open. Chat sidebar sections collapse and reorder by dragging, with keyboard/touch arrow controls and saved browser layout preferences.

SimpleUI is a full, independent chat surface (Vite + React), not a stripped WebUI. It reuses the same WebSocket backend but ships its own bundle, with a sticky composer, @-file picker, streaming markdown + syntax highlighting, vision/image attachments, session switching, and a lazy-loaded Tools/Todo/Task/Plan sidebar — deliberately minimal, fast, and focused.

VibeUI (new in 1.1.7) is a focused coding workspace between SimpleUI and the full WebUI, built with Next.js and Radix UI and served as prebuilt assets by the same host on port 3476. It adds a queued composer with Queue / Steer / BTW, provider and account setup, files and diff modals, a live Agents view, provider quotas, SAGE memory with a relationship graph and Simple / Extended context views. Terminal, browser streams and automation editing stay in the WebUI. See packages/vibeui/README.md.

---

Core capabilities

WrongStack is standalone-sufficient — everything below works with no plugins required. Each row links to its full write-up in Core capabilities; deep reference lives in docs/reference.md.

Capability	What you get
Tools & code intelligence	73 built-in tools, a SQLite/FTS5 codebase index with call-graph navigation, dead-code cleanup with rollback, and ToolFlow for scripted tool batches
Autonomy & goals	Scheduled automation jobs, /goal loops governed by the Brain, project goal tracking, /nextsteps, YOLO/YOLO+ and /solo
Multi-agent fleet + Director	A specialist roster under a Director; each subagent has its own budget and a replayable transcript
Self-improving roster agents	Roles learn project-specific practice per skill and load the useful parts on the next spawn
TypeSafe / Jev decisions	An opt-in typed decision service for skill suggestion, dispatch classification and the jev tool
Inter-agent mailbox	One project-wide message plane across every client, process, session and worktree
SAGE memory	Project-local SQLite memory with code anchors, a knowledge graph, review and per-turn recall
Tasks & Kanban	todo, plan, task and durable boards with lease fencing and verified completion
Spec-Driven Development	Spec → acceptance criteria → linked tasks → validation against the spec
Plugin ecosystem	Managed first-party plugins, each auditable and individually disableable
Providers & sign-in	API-key providers, subscription sign-in, live account catalogs, local and custom endpoints
Model routing & fallbacks	Per-role and per-phase models with automatic fallback chains
HQ	A cross-machine dashboard that can steer connected clients through their guardrails
CodeMap & visual views	Dependency graph, fleet topology, Office view and attributed per-file history
Chimera	Post-session review of changed files with severity-ranked findings
WrongTrace guardrails	An optional daemon for file locks and provider rerouting; a no-op when absent
Security & privacy	Encrypted secrets, a permission policy on every tool call, project-root containment
Token-saving mode	Tiered trimming of the described tool surface and prompt

---

Configuration

Scope	Location	Purpose
Environment	env vars	Overrides and secrets injection
User config	~/.wrongstack/config.json	Providers, defaults, feature toggles
Project conventions	<project>/.wrongstack/AGENTS.md	Shared, committed repo conventions
Project instructions	<project>/AGENTS.md (or CLAUDE.md)	Loaded into the system prompt
Directory instructions	<dir>/AGENTS.md (or CLAUDE.md)	Sent once, when the agent first touches a path under <dir>
Project identity	<project>/.wrongstack/project.json	Repository-stable proj_<ULID>

apiKey-like fields are auto-encrypted on first contact; plaintext keys in older configs migrate transparently on boot. Full details: docs/configuration.md.

---

Architecture

CLI       → REPL, renderer, slash commands, subcommands
TUI       → Ink frontend (lazy-loaded behind --tui)
WebUI     → Browser UI + WS bridge (standalone or --webui)
Desktop   → Electron shell hosting a token-gated local WebUI
Runtime   → Default host assembly + WrongStackPack extension composition
Kernel    → Container · Pipeline · EventBus · RunController (the 4 primitives)
Provider  → Multiple wire families, factories built from ModelsRegistry, real SSE
Models    → models.dev/api.json fetched + cached + classified
Services  → deterministic local IPC → one owner each → SQLite-backed project state

Four contracts hold the design together:

1. Minimal kernel — the four primitives stay small enough to read end to end.
2. Zero non-overridable behavior — services bound through Container, pipelines as middleware, all extension points in registries.
3. Standalone sufficiency — works with the built-in tools and no plugins.
4. Layered, not monolithic — every feature composes over the kernel through registries; nothing above it is load-bearing.

Full walk-through: docs/architecture.md.

---

Status

• v1.1.7 — current repository version; semver from 1.0.0 onward
• Full release verification: bun run release:check before publishing
• Coverage thresholds (root Vitest): ≥76% lines / ≥75% functions / ≥66% branches / ≥75% statements
• Packages and apps use TypeScript strict + noUncheckedIndexedAccess
• CI, dependency audit and Pages deployment are manually dispatched; pushes do not run them
• Threat model: SECURITY.md

---

Docs

Doc	What it covers
Getting started	First session and everyday workflow
Documentation index	Maintained guides and dated archives
CLI reference	Launch flags, subcommands, and wstack update
Core capabilities	Tools, autonomy, fleet, memory, boards, providers, HQ and review in depth
Reference	Tools, providers, slash commands, modes, skills at a glance
Project Kit	Reusable project tools with schemas, verification, revisions, and execution history
Slash commands	Every built-in slash command
Subcommands	Every wstack <subcommand>
Configuration	Config files, env vars, project conventions
Architecture	Kernel primitives, pipelines, agent lifecycle
Project goals	Goal ownership, checkouts, progress and verification
Tool workflows	Language tools, dead-code cleanup, codebase context and web evidence
Typed client API	Integrating with the WebUI protocol and client
SAGE memory	Long-term memory: storage, anchors, knowledge graph, retrieval
SAGE feedback lifecycle	Memory Companion, validity conditions, evidence-based feedback
OAuth sign-in	Subscription authentication
HQ service	Always-on HQ under systemd
Plugin author guide	Building a plugin
Director architecture	Fleet orchestration internals
WrongTrace integration	Optional daemon: guardrail hooks, file locks, proxy routing
Troubleshooting	Common issues

---

License

MIT © WrongStack contributors.

Contributor setup and migration dry-runs: Bun workflow.