Dev404 documentation

Quickstart#

Connect a repository, open a project chat, and describe the result you want. Include any constraints or checks that matter. Dev404 creates a working branch and shows its progress in the conversation.

1. Connect GitHub or GitLab and select a repository.
2. Start a chat with a concrete task.
3. Open Workspace to inspect files, the browser, terminal output, and tests.
4. Review the final diff and evidence before opening a change request.

Follow-ups stay in the same conversation. You can ask for a repair or a more focused check without starting over.

Sessions#

A session ties together the accepted message, branch, run status, events, and output. The timeline includes the agent’s updates and tool activity, so you can see what happened before the final reply.

Sleep holds queued work or pauses a running agent at a model boundary. Resume continues the held work. Stop cancels the run and its active subagents. The chat remains available after a run ends, and a follow-up can continue the task.

A checkpoint records the agent’s compact working context. Repository changes also need their branch or workspace backup; an in-memory process alone is not a durable copy of the work.

Subagents#

The main agent can delegate a specific assignment to a named subagent and keep working while that subagent runs. Its messages, tools, checks, and result appear in the Subagents tab. The main agent can wait for a result, send a follow-up, or stop a child.

General subagents start from a snapshot of the parent’s files. Their later commits merge into the parent checkout when it is clean. A conflict leaves the child branch intact for resolution. The parent still owns final verification; a child’s answer does not by itself prove that the combined result works.

One run can have up to three active children and eight children per execution slice. They share the parent’s model, tool, write, and time budgets. Children do not spawn more agents.

Missions#

A mission is one objective that runs with no input from you for hours, weeks, or months. Use it for work too large for a single session, such as building every module that a set of Markdown specs describes in one repository. A mission is finished when every spec section is implemented, verified, and merged, or recorded as out of scope with a reason.

Missions are rolling out gradually. Where they are enabled, you start one from a chat in your own project by typing /mission followed by what you want built. Typing / opens a command menu above the composer, with the best match first. Tab completes the command, and Escape closes the menu. The request and an acknowledgement appear as two ordinary messages, and every role in the mission uses the model selected in the composer. A chat runs one mission at a time, and a shared project cannot start one.

How a mission works

An orchestrator agent plans, assigns, verifies, merges, and re-plans. It never writes code. It decides what to build next, how to split work, whether an agent is stuck or only slow, and what a failure means. A fleet of workers does the building. Underneath both, a small piece of code called the kernel keeps the mission’s state and enforces a short list of guarantees. The kernel never makes a judgment call; it validates each action, records it durably, and makes sure the orchestrator is awake whenever something needs deciding.

Every worker is an ordinary Dev404 run in its own container, so it keeps the same checkpoints, recovery after a lost machine, workspace backups, and billing as any other run. Worker chats are internal and do not appear in your chat list.

Units and contracts

The spec is indexed by heading into sections, and the work is split into units sized for one worker in one sitting: about 2,000 changed lines or fewer, at most 25 owned files, at most two hours of agent time, and at least one executable check. Units are planned in rolling waves, so each plan stays close to the code that exists. The orchestrator keeps about twice as many ready units as there are active builders.

Each unit carries a contract: the goal, the spec sections it covers, the base commit and branch, the files it owns, the files that are frozen, the interfaces it provides and consumes, its acceptance commands, what is out of scope, and notes from earlier attempts. A builder cannot write outside the files it owns or inside the frozen ones, and it cannot finish without a valid hand-back.

Hand-backs and review

A builder finishes by submitting a hand-back. The runner measures it rather than trusting the builder: it commits and pushes the unit branch, takes the changed files from the diff, checks them against the contract, and runs every acceptance command itself. The hand-back records the summary, the interfaces it changed, follow-ups it found, assumptions it made where the spec was silent, open issues, and its confidence.

The orchestrator reads the hand-back and decides whether to request a review. The starting policy is one reviewer for a build unit, two for contract units, wide changes, and later attempts, and a third when two disagree. A reviewer answers with a verdict (approve, changes requested, or reject) and its findings. The orchestrator then accepts the unit or sends it back with the findings. A review is not an attempt, so it does not use up the unit’s retries.

Merging

A mission works on its own integration branch, mission/<id>/main, and by default keeps a pull request open from that branch to your default branch. You decide when to merge it. The integration branch moves only when the integrator pushes a commit whose acceptance commands and global checks passed on the merged code.

The integrator merges accepted units in batches of up to eight with separate file ownership. If a batch fails, it reports exactly what failed and can bisect to find the unit at fault. When the branch goes red, the usual policy is to revert first and repair second, so it stays green for every other worker. The full test suite also runs on the integration branch every 20 merges and every six hours. After each green batch, a Git bundle of the branch is stored as a backup.

Staying coherent for months

No conversation is the source of truth. The mission’s state lives in a database, and the orchestrator reads what it needs instead of carrying it. A shift ends after six hours, or after the orchestrator’s conversation has been compacted three times, and a fresh shift starts from the charter, a state summary, the previous shift’s handoff, recent decisions, and the open inbox. The auditor runs at every shift change, so a new shift reads the old one with fresh eyes. Every decision is logged with its reason.

When something goes wrong

Signals such as no progress for 30 minutes, a repeating tool-call loop, writes outside a contract, heavy compaction, or going over a time budget wake the orchestrator with evidence. They do not act on their own, because a worker running a 45-minute test suite looks the same as a stuck one. Only a few unambiguous backstops act without the orchestrator: a lost machine resumes from its checkpoint, a run with no heartbeat for two hours is cancelled and its unit returned to the queue, an attempt at four times its time budget is stopped, and a mission spending faster than its ceiling pauses new assignments.

• Container or deploy interruption: the run resumes from its checkpoint. Infrastructure failures do not count against a unit.
• Orchestrator model unavailable: the shift moves to the next strongest model. With none available, running work finishes, results wait, and nothing new is assigned or merged until a shift is running again.
• Out of credits: the mission pauses instead of failing units, and resumes when credits return.
• Unclear spec: there is no one to ask, so the worker or orchestrator records an assumption. The digest lists assumptions so you can overrule one later without blocking anything now.

Following a mission and stopping it

A mission has no dashboard of its own. It reports in the chat you started it from, through ordinary assistant messages: milestones, blockers, periodic summaries, and completion. The Stop control on that chat cancels the whole mission, including every worker that is still running. The finished work is visible where it normally would be, on the integration branch and its pull request.

A mission can hold a large number of containers for weeks, so it has its own capacity limit, separate from your other chats, which keep their full room. Missions are different from the Ultra Code team in a single session: a mission is built for tasks that need hundreds or thousands of units of work.

Side Ask#

Use Side Ask for a question that should not interrupt the main run. It reads a snapshot of the checkout taken when the question starts and cannot edit files or run commands. If the live checkout is gone, Dev404 may restore a retained workspace backup into an isolated read-only tree. Without a restorable snapshot, it declines the question.

IDE and files#

The Files tab uses Monaco for code editing. It includes highlighting, folding, find and replace, undo and redo, and language support for common web files. Search, definitions, references, file creation, rename, and delete are available through the workspace API.

Text files in the editor are limited to 500 KB. A save includes the file version that was read, so a stale tab cannot silently overwrite a newer change. Editing is disabled while an agent or manual terminal process owns the checkout. Unsaved drafts remain in the page when you switch chats.

Cloud workspace#

The task workspace runs in a Cloudflare Container. It is often called a VM in conversation, but the current runtime is a Linux container rather than a dedicated virtual machine. It contains the repository checkout, a Bash terminal, headed Chromium, and an Xfce desktop.

The checked-in image is based on Node.js 22 and Debian Bookworm slim. The deployment configuration uses the standard-3 container class. It includes Git, ripgrep, Python, browser and desktop utilities, and common build tools. A general subagent gets a Git worktree inside the same task environment, not a separate machine.

Containers can sleep when idle. Branch commits, checkpoints, and durable workspace backups carry work across continuations; a running process or an unpushed disk change is not automatically permanent.

Terminal and browser#

The terminal is a persistent Bash pseudo-terminal. Commands see a TTY, can accept input, and retain shell exports across commands. The panel keeps command history, live output, exit status, and time limits.

The browser opens a real page in headed Chromium. Dev404 can navigate, inspect the DOM, interact with controls, and capture screenshots. The Computer tab shows the Linux desktop and supports pointer and keyboard input. You can view the screen while an agent runs; manual input waits until the agent no longer owns execution.

Tests and evidence#

The Tests tab gathers commands, checks, browser observations, screenshots, and recordings made during the task. Each proof belongs to the checkout and behavior it actually tested. After an edit, an earlier pass may no longer describe the current branch.

A command exiting successfully shows that the command ran. It only verifies a requirement when the check exercises that requirement. A skipped check, a running command, or an old screenshot cannot establish completion. For UI work, inspect the affected page and viewport again after a repair.

Review changes#

Open Review changes to read the branch diff before merge. Files are grouped so you can move between related changes and inspect line context. Review findings should refer to the current commit and the evidence behind them. From a finding, you can ask the agent to make a correction and return to the diff.

Change requests#

Dev404 can publish the task branch and open or update a pull or merge request. It can use a repository change-request template, target another published branch for stacked work, read review feedback, and inspect remote checks. A missing or failed required check is not a pass.

Knowledge and skills#

Project and account knowledge stores short notes you want the agent to remember. Repository instructions, including nested AGENTS.md files, add guidance from the checkout. Skills package a repeatable procedure; they can accept arguments and restrict a subagent’s tools.

A message beginning with /skill-name can start a matching repository skill. If that name is not in the repository, Dev404 can use an installed account skill.

Schedules and automations#

Schedules start a task once or on a recurring cron expression in a selected timezone. Automations respond to configured events such as a webhook, filter the event, and start a task or send a message. Their status and invocation history show what ran.

Integrations#

Repository connections let Dev404 clone code, create branches, publish changes, and work with reviews on GitHub and GitLab. The app also has authenticated project, chat, workspace, run, and agent APIs. An inbound MCP endpoint provides access to a subset of Dev404 resources.

For a full inventory of product areas, including planned connectors and platform capabilities, see All features.

Architecture#

The web app and Worker API are deployed separately. The Worker handles authentication, project data, dispatch, and runner callbacks. D1 shards hold accounts, projects, chats, run state, and subagent activity. Durable Objects coordinate run supervision, event replay, and capacity. R2 holds larger durable objects such as workspace backups. A queue sends accepted work to the task container.

Runner admission gives each execution a scoped identity before workspace activity starts. Checkpoints and event retries help preserve accepted work through interruption; they do not turn every local test into a production reliability guarantee.

Models and budgets#

The model selector uses a cached catalog of tool-capable text models from OpenRouter. When discovery is unavailable, a saved catalog can keep the selector usable. A listed model ID is not a guarantee of provider uptime, account entitlement, or coding quality.

Runs have model, tool, write, and time budgets. Subagents draw from the same limits. The timeline records usage, but it is not an invoice or a complete billing ledger.

Up next#

These three experiences are being designed for Dev404. They are described in the All features reference alongside the rest of the product.

Live Code

Multiple people will work in the same Dev404 IDE with shared presence, cursors, and synchronized code edits. The agent will participate in that shared workspace without overwriting newer human changes.

Fullstack Mode

You will be able to describe an application and have Dev404 build the frontend, backend, database, tests, and deployment, then host the result. The workflow will need review points, environment provisioning, health checks, and rollback.

Send to Cloud

From the IDE, you will be able to transfer the current branch, changes, and task context to a cloud workspace so Dev404 can keep working after you leave. The handoff will need a reviewable snapshot and a safe way to reconcile results with newer local work.