Wake

Autonomous software engineering control plane

Wake is a control plane for autonomous software engineering. It watches the channels your team already uses, coordinates agent activity and involves humans when needed, and keeps the durable record attached to the work instead of the terminal session that happened to run it.

Create an issue, assign Wake, and keep doing your own work. Wake investigates, asks for input when human judgment matters, proposes a plan, launches local coding-agent CLIs to implement changes, opens pull requests, and carries the conversation forward wherever the work is already happening.

Table of Contents

• The Problem
• Vision
• Feature Overview
• Where the Work Happens
• Supported Agent CLIs
• Getting Started
• Documentation
• Issues & Feature Requests
• License

The Problem

Modern coding agents are powerful, but sustained development work still needs a lot of manual orchestration. Agents are usually started by hand, tied to one CLI surface, and optimized for interactive sessions instead of managed execution over time.

That leaves hard operational gaps: deciding what should happen next, choosing the right tool and model for each step, preserving state across interruptions, running deterministic housekeeping outside the LLM path, and letting a human resume the exact local session when direct intervention is fastest.

Wake exists to close that gap. It wraps existing agent CLIs in a local control plane that can apply scripted routing rules, move work through explicit lifecycle steps, resume or hand off sessions, and keep deterministic processes out of the token-burning path wherever possible.

Vision

Wake should make reliable, resumable, token-aware autonomous engineering practical. The default operating model is asynchronous and channel-driven: work enters through durable external systems, Wake keeps humans in the loop at useful decision points, and execution happens locally in an inspectable workspace or sandbox.

Wake is not trying to replace coding agents, issue trackers, or source control. It coordinates across them. Over time it should become the layer that picks work, decides the next step, invokes the right local tool or deterministic process, persists state, and resumes later without losing context.

For more detail, see docs/vision.md and docs/architecture.md.

Feature Overview

• Wake decides, the agent runs. Choosing the CLI, model, and lifecycle transition is a control-plane decision; agents do the work and report an outcome.
• Issue-driven by default. Wake currently integrates with GitHub Issues and reports questions, approvals, progress, and results back through the ticket.
• Explicit lifecycle stages. Work can move through configurable stages such as refinement and implementation instead of disappearing into one opaque session.
• Event-sourced and restart-safe. The durable record is an append-only event log; projections can be rebuilt, and the loop can crash and resume without losing its place.
• Reusable eventing packages. @atolis-hq/eventing supplies persistence-neutral event contracts and runtime services; the separate @atolis-hq/eventing-filesystem package supplies Node filesystem adapters. Wake's Bootstrap composition selects those adapters, so domain modules never depend on the filesystem package.
• Canonical work discussion. GitHub comments and Wake agent reports are recorded in one immutable conversation per work item, preserving origin and context independently of the surface where they appeared.
• Local and inspectable. Everything lives in a plain-file Wake home directory: config.yaml, config.workflows.yaml, prompts/, SETUP.md, and workspaces/ at the top level for what you edit or browse day-to-day, with durable/internal state (events, projections, runs, logs, sandbox auth) nested under a hidden .wake/.
• Durable handoffs. Agent stages can publish work-item artifacts outside Git workspaces. Wake passes only a scoped manifest to later agents, which fetch content on demand through a run-bound MCP capability. The web work item Artifacts tab offers inline viewing for .md files (case insensitive), with raw HTML disabled, a download link, and Back to artifacts navigation.
• Sandbox-oriented execution. Wake can run from a persistent Docker sandbox with durable auth state and mounted Wake home data.
• Runner agnostic. Claude Code, Codex, Cursor, and fake runners sit behind runner adapters so Wake owns policy and routing rather than depending on one provider.
• Human resumption. A human can pick up the exact local agent session when a direct terminal intervention is the best way forward.
• Operator correlation escape hatch. wake correlate <resourceUri> <workItemId> lets an operator hand-declare that a resource (a PR, a Slack thread, etc.) belongs to an existing work item when nothing detected the link automatically. See docs/configuration.md.

Current runner capability differences are documented in docs/runner-comparison.md.

Where the Work Happens

Wake has no chat UI you need to check for status. Your ticketing system is the interface: Wake posts progress updates, asks clarifying questions, and reports results as comments on the ticket, and reflects stage and status as labels on it. When it's ready, it opens a pull request against your repo the normal way. Reviewing, approving, and merging happen exactly where they already do today - nothing new to learn, no separate dashboard to babysit.

A local control-plane UI exists for operators who want to watch runs, inspect events, or use the dedicated Conversation tab on a work item to read its canonical timeline. When surfaces.api.conversationMessages.enabled is enabled, the same tab also lets an operator add a message that Wake records and may use to resume an eligible agent stage. The UI is a window into the same state - not a required part of the workflow. The API and UI require an operator login: run wake ui token to print a single-use pairing link or temporary code, then enter it in the UI. Successful logins persist for two years across browser and Wake-container restarts. Use wake ui token set <key> to replace the durable access key; replacement signs out existing sessions.

Analytics provides live reports with selectable windows, run outcome buckets, and summary metrics alongside today's system activity counters. See Analytics API and web UI for definitions.

Supported Agent CLIs

Wake wraps existing coding-agent CLIs rather than replacing them. Runner adapters currently exist for:

• Claude Code
• Codex
• Cursor

Each runner sits behind the same execution contract, so Wake's routing, lifecycle, and sandbox behavior stay the same regardless of which CLI executes a given activity. A fake runner adapter also exists for zero-token testing of the control plane itself. See docs/runner-comparison.md for capability differences between runners.

Getting Started

npm install -g @atolis-hq/wake
cd ~/
wake init ./wake-home
cd ./wake-home
# point your agent CLI at the scaffolded SETUP.md to finish configuring
# (e.g. "read SETUP.md and help me configure this")
wake sandbox build
wake sandbox up
wake sandbox setup
wake start

Full setup instructions are in docs/getting-started.md. Run wake --help at any time for the full command list, or see docs/cli.md for the full command reference.

Documentation

• docs/getting-started.md - packaged-install setup, sandbox lifecycle, wake doctor.
• docs/cli.md - full CLI command reference.
• docs/vision.md - the rationale and long-term direction for Wake.
• docs/architecture.md - module boundaries and the event-sourced core.
• packages/eventing/README.md - public Eventing contracts, runtime, and in-memory test adapters.
• packages/eventing-filesystem/README.md - public Node filesystem adapters for Eventing ports.
• docs/workflows.md - how stages, prompts, and runner routes are configured.
• docs/prompts.md - how prompt templates map to workflow stages.
• docs/configuration.md - config.yaml/config.workflows.yaml options and the operator correlation escape hatch.
• docs/public-ui-access.md - expose the operator UI through ngrok or another secured ingress.
• docs/development.md - source-checkout dev setup (wake-dev), npm scripts, formatting, self-update, GitHub polling.
• docs/runner-comparison.md - capability differences between supported runners.

Issues & Feature Requests

Found a bug or have an idea for Wake? Open an issue - bug reports and feature requests are both welcome.

License

Wake is licensed under the Apache License 2.0.