MAAS

MAAS is a Codex-first control plane for supervising autonomous work.

It exists for the gap between “an agent can do work” and “an operator can safely trust an always-on system.” MAAS turns goals into issue inventories, runs Codex inside a governed execution loop, keeps review and recovery explicit, promotes reusable memory, and makes the entire control flow observable through runs, logs, traces, and incidents.

What It Is

MAAS is not a generic dashboard and not a thin Codex wrapper. The current product direction is:

Codex as the MVP execution runtime
Goal, Issue, Run, Agent, Event, and Incident as the core control objects
one human operator supervising execution instead of manually driving every task
explicit review, recovery, memory, and delivery loops around autonomous work

Why It Exists

Autonomous execution only becomes useful when the surrounding control loop is trustworthy. MAAS is designed to answer:

what is the system doing right now?
what needs operator judgment?
why is progress blocked?
what output did Codex actually produce?
what memory, checks, and recovery rules changed the result?

Core Objects

Goal
Issue
Run
Agent
Event
Incident

Operator Surfaces

Command: what needs judgment now
Theater: live issue ownership, run posture, and branch lineage in one execution map
Work: shared List | Board view of issues plus detail and execution history
Issues: approvals, blocked work, failed runs, grouped review, and recovery actions
Agents: active ownership, execution threads, spawned work, and health
Runs: live and historical execution truth
System: logs, metrics, queue posture, and machine health
Projects: create, import, clone, archive, delete, and posture management

What Makes It Different

project-level autopilot instead of manual “run cycle” babysitting
first-class run history, traces, and live execution truth
explicit review policy and grouped review packets
recovery playbooks instead of raw failure queues
retrieval-backed project memory with promotion, attribution, and usefulness tracking
delivery prep, GitHub draft PR sync, and verification-gated handoff

Current Status

Today MAAS is a substantial local prototype built around:

a Python/FastAPI backend with SQLite-backed state
a React control plane for Command, Theater, Work, Issues, Agents, Runs, System, and Projects
goal intake, issue synthesis, autopilot, review, recovery, retrieval, delivery-prep, and GitHub sync flows
reconciliation-backed truth inspection and repair for stale run, task, agent, and delivery linkage
retry-safe external effects for notifications, provider jobs, git workspaces, and GitHub PR sync
persisted trust runs with deterministic fault injection and replayable incident evidence
a GitHub Project-driven execution workflow for tracked issues, PRs, and review state
live and simulated Codex execution paths with operator-visible logs, traces, and artifacts

The implementation history is long because the product has pivoted several times. The public direction above is the one that matters now; the detailed historical roadmap is still preserved below for implementation tracking.

Quick Start

Install the backend and frontend dependencies, then launch the API and web app locally:

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

cd web
npm install
cd ..

./scripts/maas-dev up
./scripts/maas-dev status

The managed local preview workflow:

creates or reuses a demo workspace under /tmp/maas-dev/workspace
imports this repo into that workspace as a brownfield project
starts the API on 0.0.0.0:8000 and the web app on 0.0.0.0:5173
keeps pid files and logs under /tmp/maas-dev
remembers the last selected workspace and port settings under /tmp/maas-dev/dev-config.json

Stop or restart the stack with:

./scripts/maas-dev down
./scripts/maas-dev restart

Run a persisted local trust soak with deterministic failure injection:

PYTHONPATH=src ./scripts/maas-trust-run --project-root /tmp/maas-dev/workspace --cycles 12 --sleep-seconds 60

If :8000 or :5173 is already occupied on your machine, pass explicit overrides such as ./scripts/maas-dev --web-port 5183 up or ./scripts/maas-dev --api-port 8001 --web-port 5183 up. status, restart, and down reuse the last selected settings from /tmp/maas-dev/dev-config.json. If you want localhost-only binding instead of LAN exposure, pass --api-host 127.0.0.1 --web-host 127.0.0.1.

You can still bootstrap and run MAAS manually from the CLI when needed:

PYTHONPATH=src python3 -m maas init --project-root .
PYTHONPATH=src python3 -m maas db migrate --project-root .
PYTHONPATH=src python3 -m maas api --project-root .
cd web && npm run dev

Product Direction

Relevant design and roadmap documents:

There is also a standalone product mockup for the current direction in mockups/maas-codex-mvp/README.md.

Execution Workflow

Active planning and execution now live in GitHub, not in the numbered implementation docs.

execution layer: MAAS Delivery & Execution
current-truth docs: README.md, docs/implementation/STATUS.md, and docs/implementation/WORKFLOW.md
history/reference docs: the numbered implementation docs under docs/implementation

Use one GitHub issue per tracked task or roadmap item, keep project fields truthful, and link the PR once code work starts. Reconciliation now also repairs stale merged-state cards for this repo's own GitHub Project when a tracked issue is already closed by a merged PR.

For unattended local use, rely on the System surface trust gate rather than README prose. MAAS now exposes an explicit unattended-mode gate that only arms after a fresh passing trust soak, clean truth reconciliation, and healthy launch posture.

Roadmap and Implementation History

The rest of this README tracks shipped implementation and numbered delivery history as archive/reference.

Implementation Snapshot

Legend:

[x] completed in the current numbered delivery sequence
[ ] not yet completed in the current numbered delivery sequence

Use the stacked-branch references below to see whether a completed item is already on main or only exists on stacked branches.

Historical stacked development chain above main:

#82 exists on codex/project-aware-supervisor-orchestration
#83 exists on codex/brownfield-file-backed-planning
#84 exists on codex/recovery-circuit-breakers
#85 exists on codex/project-isolated-provider-runtime
#86 exists on codex/provider-job-queue
#87 exists on codex/provider-job-queue
#88 exists on codex/file-linked-task-scopes
#89 exists on codex/brownfield-runbook-command-catalog
#90 exists on codex/brownfield-runbook-command-catalog
#91 exists on codex/brownfield-runbook-command-catalog
#92 exists on codex/queue-capacity-controls
#93 exists on codex/session-runner-envelopes
#94 exists on codex/policy-driven-self-healing-v2
#95 exists on codex/brownfield-onboarding-review-v2
#96 exists on codex/remote-executor-worker-pool
#97 exists on codex/cross-project-scheduler-fairness
#98 exists on codex/repo-grounded-plan-synthesis
#99 exists on codex/verification-runners-evidence-capture
#100 exists on codex/git-aware-task-workspaces
#101 exists on codex/cross-project-command-center
#102 exists on codex/queue-worker-capacity-governance
#103 exists on codex/queue-worker-capacity-governance
#104 exists on codex/queue-worker-capacity-governance
#105 exists on codex/queue-worker-capacity-governance
#106 exists on codex/queue-worker-capacity-governance
#107 exists on codex/ux-product-redesign
#108 exists on codex/ux-product-redesign
#109 exists on codex/ux-product-redesign
#110 exists on codex/ux-product-redesign
#111 exists on codex/ux-product-redesign
#112 exists on codex/ux-product-redesign
#113 exists on codex/ux-product-redesign
#114 exists on codex/ux-product-redesign
#115 exists on codex/ux-product-redesign
#116 exists on codex/ux-product-redesign
#117 exists on codex/linear-vibekanban-cockpit
#118 exists on codex/linear-vibekanban-cockpit
#119 exists on codex/linear-vibekanban-cockpit
#120 exists on codex/linear-vibekanban-cockpit
#121 exists on codex/linear-vibekanban-cockpit
#122 exists on codex/linear-vibekanban-cockpit
#123 exists on codex/linear-vibekanban-cockpit
#124 exists on codex/linear-vibekanban-cockpit
#125 exists on codex/linear-vibekanban-cockpit
#126 exists on codex/linear-vibekanban-cockpit
#127 exists on codex/linear-vibekanban-cockpit
#128 exists on codex/linear-vibekanban-cockpit
#129 exists on codex/linear-vibekanban-cockpit
#130 exists on codex/linear-vibekanban-cockpit
#131 exists on codex/linear-vibekanban-cockpit
#132 exists on codex/linear-vibekanban-cockpit
#133 exists on codex/linear-vibekanban-cockpit
#134 exists on codex/linear-vibekanban-cockpit
#135 exists on codex/linear-vibekanban-cockpit
#136 exists on codex/linear-vibekanban-cockpit
#137 exists on codex/linear-vibekanban-cockpit
#138 exists on codex/linear-vibekanban-cockpit
#139 exists on codex/linear-vibekanban-cockpit
#140 exists on codex/linear-vibekanban-cockpit
#141 exists on codex/linear-vibekanban-cockpit
#142 exists on codex/linear-vibekanban-cockpit
#143 exists on codex/linear-vibekanban-cockpit
#144 exists on codex/linear-vibekanban-cockpit
#145 exists on codex/linear-vibekanban-cockpit
#146 exists on codex/linear-vibekanban-cockpit
#147 exists on codex/linear-vibekanban-cockpit
#148 exists on codex/linear-vibekanban-cockpit
#149 exists on codex/linear-vibekanban-cockpit
#150 exists on codex/linear-vibekanban-cockpit
#151 exists on codex/linear-vibekanban-cockpit
#161 exists on codex/codex-mvp-shell-integration
#162 exists on codex/codex-mvp-shell-integration
#163 exists on codex/codex-mvp-shell-integration
#164 exists on codex/codex-mvp-shell-integration
#165 exists on codex/codex-mvp-shell-integration
#166 exists on codex/codex-mvp-shell-integration
#167 exists on codex/codex-mvp-shell-integration
#168 exists on codex/codex-mvp-shell-integration
#169 exists on codex/codex-mvp-shell-integration
#170 exists on codex/codex-mvp-shell-integration
#171 exists on codex/codex-mvp-hardening
#172 exists on codex/codex-mvp-hardening
#173 exists on codex/codex-mvp-hardening
#174 exists on codex/codex-mvp-hardening
#175 exists on codex/codex-mvp-hardening
#176 exists on codex/codex-mvp-hardening
#177 exists on codex/codex-mvp-hardening
#178 exists on codex/codex-mvp-hardening

The current operator-value and capability sequence in docs/implementation/14-codex-mvp-next-batch-plan.md is now implemented on codex/codex-mvp-operator-scale. It adds truthful queue posture, readiness-aware launch strategy, shared Work/Issues scopes, first-class run detail reads, stronger agent/system execution diagnostics, verification-driven auto-approval, and cleaner fresh-project lifecycle controls.

The current autonomy-scale sequence in docs/implementation/15-codex-mvp-autonomy-scale-plan.md is now implemented on codex/codex-mvp-autonomy-scale. It adds first-class Runs, backend-owned exception grouping, retrieval across issues/runs/artifacts/events, clone-for-fresh-run project lifecycle, stronger stale-run diagnostics, cross-project supervision in Projects, and an async attention loop with optional desktop notifications.

The current autopilot-and-memory sequence in docs/implementation/16-codex-mvp-autopilot-memory-plan.md is now implemented on codex/codex-mvp-autopilot-memory. It adds project templates, project-level autopilot, memory promotion and retrieval-backed Codex prompts, backend-owned batch review, and stronger execution-state truth across Command, Issues, System, and issue detail.

The current control-loop hardening sequence in docs/implementation/17-codex-mvp-control-loop-hardening-plan.md is now implemented on codex/codex-mvp-control-loop-hardening. It adds durable autopilot lease state, a backend-owned operator inbox, lifecycle-safe clone posture resets, grouped review packet truth, notification failure integration, and fresher execution-memory attribution.

The current doctor, planning, and delivery-loop sequence in docs/implementation/18-codex-mvp-doctor-delivery-loop-plan.md is now implemented on codex/codex-mvp-doctor-delivery-loop. It adds an environment doctor, first-class goal creation and synthesis, delivery candidate reads plus PR-draft preparation, stronger autopilot governance gates, goal-scoped review packets, and usefulness-aware execution memory.

The current product-modeling sequence on codex/linear-vibekanban-cockpit now covers the cockpit pivot (#127-#136), the Linear/Vibekanban-inspired workflow cleanup (#137-#146), and the clarified Cockpit/Board role split (#147-#151).

The current Codex-MVP integration sequence on codex/codex-mvp-shell-integration carries that product reset into the real app with a new shell, canonical issue identity, issue detail and agent detail read models, and integrated Command / Work / Issues / Agents / System surfaces.

The current hardening sequence on codex/codex-mvp-hardening makes the integrated MVP truthful in live use: explicit run-cycle vs launch posture controls, review-first issue detail, simulation/live warnings, project delete plus fresh workspace creation, and tighter lifecycle regressions.

Current project state

MAAS is now a substantial single-project, greenfield, operator-supervised prototype.
The core loop exists end to end: bootstrap, board, supervisor, provider execution, failure handling, quarantine, recovery, and artifact inspection.
For that current prototype shape, the repo is roughly 85-90% complete.
For the broader roadmap vision, the repo is still materially incomplete.

Shipped on `main`

Still to do on `main`

Product UX simplification, clearer mental model, and stronger first-run guidance
Visually strong dual light/dark theme and a real design system instead of the current admin-tool feel
Broader automated restart, retry, backoff, and self-healing workflows beyond the current DLQ path
Broader external provider coverage beyond the current local CLI paths
Higher-level artifact retention policy automation beyond the current browser, provenance, and export flows
Deeper brownfield onboarding and multi-project execution support
Stronger sandboxing and isolation guarantees
Project-aware background orchestration beyond the current multi-project read scope

Current numbered delivery sequence

Current stacked branch progress

The current numbered #81-#126 sequence is fully implemented on the stacked branch chain above main.

UX and product-design sequence now implemented on the stacked branch

Dense operator control-room sequence now implemented on the stacked branch

Extended numbered roadmap

Quick Start

PYTHONPATH=src python3 -m maas init --project-root .
PYTHONPATH=src python3 -m maas db migrate --project-root .
PYTHONPATH=src python3 -m maas task ready --project-root . --refresh
PYTHONPATH=src python3 -m maas task allocate --project-root .
PYTHONPATH=src python3 -m maas supervisor --project-root . --once
PYTHONPATH=src python3 -m maas api --project-root .

The project bootstrap creates:

project.yaml
.maas/
.maas/state.db
.maas/artifacts/
.maas/logs/
.maas/quarantine/

Core API

GET /api/health
GET /api/board
GET /api/goals
GET /api/agents
GET /api/activity
GET /api/alerts
GET /api/escalations
GET /api/failures
GET /api/artifacts
GET /api/artifacts/export
GET /api/quarantine
GET /api/live
WS /api/live/ws
GET /api/overview
GET /api/goals/tree
GET /api/providers
GET /api/tasks/ready
GET /api/tasks/{task_id}/capabilities
POST /api/escalations/request
POST /api/escalations/{escalation_id}/actions/approve
POST /api/escalations/{escalation_id}/actions/reject
POST /api/providers/{provider_id}/actions/run-task
POST /api/tasks/actions/refresh-ready
POST /api/tasks/actions/allocate-ready
POST /api/tasks/{task_id}/actions/evaluate
POST /api/tasks/{task_id}/actions/recover
POST /api/tasks/{task_id}/actions/recover-and-requeue
POST /api/tasks/{task_id}/actions/resolve-repeated-failures
POST /api/quarantine/{queue_id}/actions/restore
POST /api/quarantine/{queue_id}/actions/dismiss
POST /api/agents/{agent_id}/actions/assign-next
POST /api/agents/{agent_id}/actions/recover
POST /api/supervisor/run

The primary operational surface is the Kanban board returned by /api/board.

Task Engine Commands

maas task ready --project-root . --refresh
maas task allocate --project-root .
maas task allocate --project-root . --agent-id <agent_id>
maas task evaluate --project-root . --task-id <task_id>
maas task recover --project-root . --task-id <task_id> --actor-id <agent_id>
maas task recover-and-requeue --project-root . --task-id <task_id> --actor-id <agent_id>
maas task resolve-repeated-failures --project-root . --task-id <task_id> --actor-id <agent_id>
maas agent recover --project-root . --agent-id <agent_id> --actor-id <agent_id>
maas supervisor --project-root . --once
maas failure list --project-root .
maas quarantine list --project-root .
maas quarantine restore --project-root . --queue-id <queue_id> --actor-id <agent_id>
maas quarantine dismiss --project-root . --queue-id <queue_id> --actor-id <agent_id>
maas escalation list --project-root .
maas escalation request --project-root . --project-id <project_id> --actor-id <agent_id> --action-type halt_task|reassign_task|pause_agent|resume_agent --resource-type task|agent --resource-id <resource_id>
maas escalation approve --project-root . --escalation-id <escalation_id> --actor-id <agent_id>
maas escalation reject --project-root . --escalation-id <escalation_id> --actor-id <agent_id>
maas worker --project-root . --provider-type python_script|claude_code|openai_codex ...

These commands expose the current dependency-aware ready queue, allocator flow, acceptance-gate evaluation, supervisor orchestration pass, and escalation approval flow from the CLI.

Security Notes

board and alert actions are gated by role-baseline board_actions permissions from project.yaml
task execution now uses task-scoped capability grants, so lifecycle writes are limited to the assigned agent and task
board cards and the task capabilities API expose the currently active task grants
risky task and agent interventions can now be routed through an escalation queue instead of being executed immediately
failed and timed-out sessions are now recorded in failure memory and can raise repeated-failure alerts
quarantined failure artifacts are isolated under .maas/quarantine/ and surfaced through the failure-memory reads
first-class quarantine queue reads and actions now track open, restored, and dismissed artifact incidents
recent failure and overview surfaces expose direct operator actions for recovery, restore, dismiss, reopen, and repeated-failure resolution
operators can return failure-blocked tasks to the planning queue without resuming the old execution context
timed-out and failed sessions can auto-retry under project recovery policy with tracked retry state
operators can recover timeout-stranded agents from error back to idle once no active session remains

Provider Notes

python_script is the reference local worker adapter
claude_code supports both the simulated adapter and a real local claude -p path when enabled in project.yaml
openai_codex supports both the simulated adapter and a real local codex exec path when enabled in project.yaml
/api/providers and the Providers view expose configured mode, effective mode, config warnings, recent provider runs, safe manual run targets, mode switching, and editable runtime settings
/api/artifacts and the Artifacts view expose artifact state, missing-file detection, quarantine metadata, and server-side filtering
artifact detail now includes preview, guarded single-file download, task/session export bundles, same-task compare, same-session lineage, and dependency-linked provenance pivots

Name		Name	Last commit message	Last commit date
Latest commit History 353 Commits
.github		.github
docs		docs
migrations		migrations
mockups		mockups
scripts		scripts
src/maas		src/maas
tests		tests
web		web
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
testsupport.py		testsupport.py

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

MAAS

What It Is

Why It Exists

Core Objects

Operator Surfaces

What Makes It Different

Current Status

Quick Start

Product Direction

Execution Workflow

Roadmap and Implementation History

Implementation Snapshot

Current project state

Shipped on `main`

Still to do on `main`

Current numbered delivery sequence

Current stacked branch progress

UX and product-design sequence now implemented on the stacked branch

Dense operator control-room sequence now implemented on the stacked branch

Extended numbered roadmap

Quick Start

Core API

Task Engine Commands

Security Notes

Provider Notes

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

MAAS

What It Is

Why It Exists

Core Objects

Operator Surfaces

What Makes It Different

Current Status

Quick Start

Product Direction

Execution Workflow

Roadmap and Implementation History

Implementation Snapshot

Current project state

Shipped on main

Still to do on main

Current numbered delivery sequence

Current stacked branch progress

UX and product-design sequence now implemented on the stacked branch

Dense operator control-room sequence now implemented on the stacked branch

Extended numbered roadmap

Quick Start

Core API

Task Engine Commands

Security Notes

Provider Notes

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Shipped on `main`

Still to do on `main`

Packages