WrongStack

# macOS / Linux — one self-contained binary, no Node.js needed
curl -fsSL https://github.com/WrongStack/WrongStack/releases/latest/download/install.sh | sh

# Windows
irm https://github.com/WrongStack/WrongStack/releases/latest/download/install.ps1 | iex

WrongStack is free, open source, and MIT licensed. It drives autonomous goal loops, parallel subagent fan-out, and Brain-governed policy decisions — with a project-wide SAGE memory that persists knowledge across sessions, active Kanban boards with atomic verification, an inter-agent mailbox that links every client, and Chimera auto-review agents that critique your diffs. It ships with a deep built-in toolbox, bundled skills, managed first-party plugins, and a provider catalog pulled live from models.dev — all on top of a compact, swappable kernel.

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.

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.

Highlights since 1.0.24:

• Choose GPT-6 Sol or Luna with ChatGPT sign-in. Both models appear in the Codex picker with their supported reasoning efforts.
• Set up connected tools more easily. MCP servers report resource updates, OAuth prompts explain next steps, and the CLI can import Claude Code settings.
• Follow active work in the WebUI. Goal and Kanban views make task execution and state easier to inspect; provider profiles and MCP settings have clearer controls.
• Run commands with stronger safeguards. Danger detection handles wrapped shell commands and inline interpreter payloads, and secret redaction covers compound flags.
• Trust dependency findings. npm audit and OSV advisories retain their real package identities and severity in the techstack adapter.

Earlier additions:

• Give agents a typed decision specialist. A configured Jev account exposes jev for validated judgments, while jev_status checks readiness offline.
• Manage Jev where you work. /jev and Settings → Jev configure features and show decision activity in the terminal and browser.
• Keep SAGE triage scoped and complete. Daily dry runs carry the owning session's evidence and protect revived records during cleanup.
• Use fast judgments with safe fallbacks. Optional TypeSafe System One decisions support Brain choices, memory triage and recall, topic shifts, compaction, Kanban verification, model-tier routing and semantic linting.
• Install from one verified release. GitHub Releases provide self-contained CLI binaries and per-platform Desktop packages with checksum manifests and smoke-tested installers; npm remains a legacy compatibility path.
• Operate Kanban through guarded management APIs. Assignment, dependency, decomposition, lifecycle and queue-health actions share the same managed boundary across connected surfaces.
• Inspect Brain and Council outcomes. Replay keys bind exact inputs, policy changes invalidate cached approvals, request identities stay unique, and HQ correlates the latest decision lifecycle state.

See the complete release notes.

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

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

• 🧠 It remembers your project. SAGE keeps long-term memory in SQLite/FTS5, anchored to real files, symbols, commands, and commits — and re-verified as they change. Decisions, conventions, and root causes survive the session that produced them.
• 🤖 A fleet, not a lone agent. A full specialist roster and smart dispatcher fan out under a Director, each subagent isolated with its own budget and JSONL transcript.
• 📈 The roster gets better here. Each role turns useful outcomes into skill-specific practice, ranks what actually works in this repo, and applies it on the next matching task.
• 🛠️ A deep toolbox, no plugins required. Edits, lint/format/typecheck/test, execution, git, web, browser/E2E, and a SQLite codebase index with symbol and call-graph navigation.
• 🖥️ Six surfaces, one brain. A plain readline REPL, an Ink/React TUI (--tui), the full WebUI (--webui), lightweight SimpleUI, Desktop (--desktop), and the cross-machine HQ (--hq) — same engine, same session, same memory underneath.
• 🛰️ HQ for the whole room. Aggregate live sessions, agents, fleets, mailbox state, cost, tools, Brain decisions, and worktrees across machines — then steer, note, queue, or stop connected clients through their own guardrails.
• 📬 Agents that coordinate instead of collide. One project-wide mailbox links every client, session, branch, and linked worktree, with typed messages and live presence.
• ♾️ Set a goal, walk away. /goal locks a contract and the eternal / parallel engines grind until it is verifiably done — with the Brain deciding risky calls by policy, denying them, or escalating to a human.
• 🗂️ Work tracking that resists lying. Durable Kanban boards and typed tasks with dependencies, lifecycle stages, and atomic verification gates that let a card reach Done only when its criteria actually pass.
• 🦂 Your diffs get reviewed. Chimera critiques changed files with severity-ranked file:line findings and a one-line fix each, and fixer agents can follow up.
• 🔌 Providers without lock-in. Anthropic, OpenAI, Google, and a broad range of OpenAI-compatible endpoints, refreshed from models.dev at boot.
• 🏠 Local & custom endpoints. One-command presets for Ollama / vLLM / LM Studio, plus any custom baseUrl or OmniRoute-style gateway; run fully on localhost.
• 🔑 Sign in with a subscription. Authenticate with a ChatGPT (Codex), Claude Pro/Max (for extra usage credits), or GitHub Copilot account over OAuth, alongside API keys.
• 🔀 Per-role model routing. Assign different providers/models per role or phase, with automatic fallback chains when a model is overloaded.
• 🔐 Locked down where it counts. Encrypted secrets and a permission policy on every tool call, both always on. Project-root containment is opt-in (/settings → Filesystem access); once you enable it, neither YOLO nor a repo-committed config can turn it back off.
• 🪶 A kernel you can actually read. Container · Pipeline · EventBus · RunController — small enough to read in one sitting. Everything above it is swappable.

Most "AI coding" tools fall into one of two buckets: a single-agent CLI that edits files in one terminal, or an orchestration kit that shells out to a third-party agent CLI and coordinates it. WrongStack is neither — it's a complete agent written from scratch, so the whole stack is first-party and consistent.

The point isn't "more features" — it's that a from-scratch, standalone design lets memory, tools, providers, permissions, and the multi-agent runtime actually work together instead of being glued across process boundaries.

• Standalone binary: nothing — the executable carries its own runtime (Windows x64, macOS x64/arm64, Linux x64/arm64 incl. musl)
• npm/pnpm install: Node.js ≥ 22.19.0 and pnpm ≥ 12.3.4 (recommended) or npm
• Bun runtime: Bun ≥ 1.3.10

One executable per platform with the runtime, every surface and all bundled assets inside — no Node.js, npm or node_modules:

# macOS / Linux
curl -fsSL https://github.com/WrongStack/WrongStack/releases/latest/download/install.sh | sh

# Windows
irm https://github.com/WrongStack/WrongStack/releases/latest/download/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) manages an npm install; run wstack hq under your own service manager instead.

The npm packages (wrongstack, @wrongstack/cli) are legacy and no longer the way to install WrongStack — GitHub Releases is the only supported channel. If you installed through npm, pnpm, yarn or bun before, just run the installer above: it finds those globals and uninstalls them (asking first on a terminal) so they cannot shadow the binary.

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:

pnpm build
bun run start:bun

pnpm 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.

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.

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

# Sign in with a ChatGPT/Codex or Claude 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.

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.

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.

WrongStack is standalone-sufficient — the highlights below work with no plugins required. Deep reference lives in docs/reference.md.

The built-in toolbox spans filesystem edits, code quality (lint/format/ typecheck/test), execution, web search/fetch, git, packages, browser/E2E controls, and a project-owned Codebase Index. The index combines SQLite/FTS5 substring search, local semantic ranking, content-hash invalidation, symbol and call-graph navigation, and bounded parser workers for large repositories. Full map: reference → tools.

Every tool is registered and callable at every setting. How many are described to the model on each request depends on the token-saving tier: the default trims that to a working set and keeps the rest one tool_search away, so a long session does not pay for every schema on every turn. Set features.tokenSavingMode: "off" to describe them all directly.

/goal locks a verifiable contract and the eternal / parallel engines run until it's done, surfacing a live stage chip (⟳ DECIDE / ⚡ EXECUTE / ◎ REFLECT). The Brain governs risky decisions with deterministic rules, decision traces, quality gates, and circuit breaking.

A specialist roster and smart dispatcher fan out under a Director. Each subagent is isolated with its own budget and JSONL transcript, coordinated over a project-wide mailbox. See Director architecture and agents.

Every roster role has a base definition, but each project can teach it. Under .wrongstack/agents/<role>/, the role keeps its identity, a structured learning buffer, and skill-specific practice at skills/<skill>.md. A run can end with a ## LEARNED [skill: testing] directive (or let WrongStack route it from the wording); the next matching spawn receives that project practice immediately below the bundled skill it refines. /agent-improve <role> capture, optimize, and skills make the loop visible, while automatic optimization distils safely in the background. Useful skills gain affinity from usage and outcomes, can be pinned, and rise into the role's bounded eager-load set — so your bug-hunter, reviewer, and executor improve where it matters without turning every prompt into a dump of old notes.

Manage the decision provider, key and feature switches in Settings → Jev in the WebUI, or /jev in the TUI. The WebUI includes a live activity view with request timing, usage, answers and safe failure categories; /jev logs exposes the same process history. See Jev settings and activity.

Configured accounts also expose the jev decision tool: agents can request yes/no probabilities, choose among alternatives, or score supplied evidence against a rubric. jev_status checks local availability without a network request. Control this independently with /jev feature tool on|off or Settings → Jev → Agent decision tool.

Optional Jev integration suggests a relevant skill before a turn and classifies ambiguous fleet dispatches; those two consumers remain separately opt-in. The bounded judgment features are available when an account is ready and can each be switched off independently. Jev supports a native TypeSafe API key or OpenRouter's Decisions endpoint through wstack typesafe login --route typesafe or --route openrouter; wstack typesafe test checks the selected account. Jev is a typed decision service, not a chat model. See account setup and coverage, skill suggestion, and fleet classification.

One project-wide coordination plane connects every agent, across every client, process, session, branch, and linked Git worktree — CLI, TUI, WebUI, SimpleUI, Desktop, and HQ alike. Agents send typed messages (ask, assign, steer, result, review, status), hand off work, broadcast milestones, and see who is online with live presence — so parallel agents cooperate instead of colliding. HQ can even route mailbox traffic and steer connected clients through their own guardrails. All production callers use a deterministic local IPC endpoint; one elected project owner alone opens _mailbox.sqlite, serializes mutations, and publishes health and presence. Clients never open the mailbox database directly.

SAGE is WrongStack's project-local, structured long-term memory. It lives at .wrongstack/memories/ backed by SQLite/FTS5 (legacy JSONL auto-migrates on first open), and it is indexed by default. The agent uses remember, memory_search, and pin_add to persist and recall knowledge across sessions — and relevant memories are auto-injected into context every turn. The same project-owned service is available to external MCP clients through wstack-sage-mcp; it is read-only by default, while --writable enables the confirm-class mutation tools.

• Typed knowledge — facts, decisions, conventions, preferences, anti-patterns, bug root causes, and file/symbol/command notes, each with importance + confidence.
• Rich anchors — a memory can bind to almost anything concrete: a file, a directory, a symbol (function/class/method), a command, a git commit or blob, a test, or a package. Anchored memories are re-verified as those targets change (file existence, content hash, git blob, symbol presence) and auto-surface when you touch that location — so knowledge stays pinned to the code it describes instead of drifting.
• Knowledge graph — typed edges + BFS traversal relate memories, files, symbols, and commands.
• Audience-scoped — memories can target specific roles/modes so role-specific guidance never clutters general recall.
• Curated, not chaotic — a review queue and hygiene pipeline keep memory trustworthy; deletions are guarded.

See docs/sage/ARCHITECTURE.md.

Work is tracked with real, durable structure — not throwaway checklists:

• todo — session-level step tracking for the task in flight.
• plan — a persistent strategic roadmap that survives turns; promote items into todos or tasks.
• task — structured, cross-session work items with types, priorities, and dependencies.
• kanban — durable project boards with columns, task chains, dependencies, and assignment snapshots. One project IPC owner serializes the authoritative .wrongstack/kanbans/_kanban.sqlite state and broadcasts daemon events; clients do not open the database directly. The @wrongstack/kanban package provides the storage + lifecycle layer (claim, recover stale assignments, verify completion) with lease fencing and cost guardrails for safe multi-agent execution.

Managed cards follow an explicit Backlog → Todo → Running → Review → Done lifecycle, and HQ exposes a shared, project-scoped board that reconciles live across every clone carrying the project identity.

Atomic verification keeps tasks honest. Cards carry success criteria, goal metrics, and checks; the board can assess atomicity and either propose or auto decompose non-atomic work (atomicityMode: off | assess | enforce). Completion isn't a rubber stamp — verify_completion gates a card into Done only when its acceptance criteria and evidence actually pass, so a worker finishing means the card enters Review, not Done.

Turn a spec into acceptance criteria, decompose into dependency-linked tasks, implement one at a time, and validate against the spec before closing.

A collection of managed first-party plugins extends the agent with focused, single-purpose capabilities, each auditable and individually disableable. See plugin management and the plugin author guide.

Providers span several API-key wire families, plus OAuth sign-in with ChatGPT (Codex), Claude Pro/Max (for extra usage credits), and GitHub Copilot accounts — usable alongside API keys. Browse with wstack models. See OAuth sign-in.

Bring your own endpoint. Beyond the catalog, you can point WrongStack at any OpenAI-compatible endpoint: local models via one-command presets for Ollama (no key), vLLM, and LM Studio; custom providers with your own baseUrl and env-var keys; and proxy/router gateways like OmniRoute. Run entirely on localhost if you want — the same tools, fleet, and memory work against a model on your own machine.

Mix providers and models freely, per role and per phase. A model-routing matrix assigns a provider/model — or a named fallback profile — to any agent role, phase, or the fleet-wide default (exact role → phase → * → leader). When a model is overloaded (429/5xx), WrongStack rotates through an ordered fallback chain automatically, and favoriteModelsOnly keeps that rotation on models you trust. So a leader, a reviewer, and a bug-hunter can each run on a different model in the same session, each with its own safety net.

wstack --hq is the control plane for a whole room. It aggregates live sessions, agents, fleets, mailbox state, cost, tools, Brain decisions, and worktrees across multiple machines and clients in one dashboard — running many providers and models simultaneously — and can steer runs, send BTW notes, queue prompts, route mailbox traffic, or stop connected clients through their own guardrails. Browser and client tokens are separate and capability-scoped; in token mode every /api/* route and WS upgrade is gated.

The WebUI turns the SQLite codebase index into code intelligence you can see. CodeMap renders an interactive dependency/symbol graph (server-side cached, with visible-element virtualization for large graphs) so you can navigate the project's structure and hotspots at a glance. Alongside it, live fleet topology and an Office view visualize your running agents spatially — who is active, what each is doing, and how the fleet is wired — turning multi-agent runs into something you can actually watch.

A file's whole story, traceable. CodeMap streams live per-file activity — every read / write / edit / delete / search / index / execute — tagged with the session, agent, tool, trace id, timestamp, and the actual line changes (added / removed, before / after). So from the file explorer you can replay what happened to any file over time: which task, which session, which agent, which tool touched it, and what it did — the full, attributed history of a change and everything it reached.

Chimera is a post-session code guardian. The built-in auto-review plugin detects every git-tracked file you changed during a session and dispatches a review subagent that reads the diffs and reports real, severity-ranked findings (Critical → Low) with file:line references and a one-line fix each — surgical bug-catching, not style nagging. Paired fixer agents can act on the findings, and reviews can fan out in parallel across many changed files. Trigger it on-demand with /chimera.

WrongStack can coordinate with the external WrongTrace daemon when it is running locally (default http://localhost:3444) — and silently does nothing when it is not. Two independent integrations share that origin: the observability guardrails and provider rerouting. Every mutating tool call (edit, write, replace, patch, codebase-ast-replace) passes a fail-open lock gate — a file locked by another owner denies the edit with the owner and TTL in the reason, fragile files get a surgical-edit nudge, and an offline daemon never blocks anything. The same daemon optionally rewrites provider base URLs through /proxy/ when tools.wrongProxy.enabled is set. Full details: docs/wrongtrace.md.

Encrypted secrets at rest, a permission policy on every tool call, project-root containment that YOLO can't weaken, and a typed observability event catalog. Threat model: SECURITY.md.

--token-saving-mode trims the tool surface and prompt to cut cost. The tier resolves once at boot (off | auto | minimal | light | medium | aggressive); set features.tokenSavingMode: "off" to describe every tool on every turn.

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

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.

• v1.0.19 — current release; semver from 1.0.0 onward
• Full release verification: pnpm release:check (18 gates) before publishing
• Coverage thresholds (root Vitest): ≥76% lines / ≥75% functions / ≥66% branches / ≥75% statements
• Every package and app builds clean with TypeScript strict + noUncheckedIndexedAccess
• Node 22.19+ only, ESM-only, no CommonJS bundles
• Threat model: SECURITY.md

MIT © WrongStack contributors.