for developers

The engineering detail.

One request, traced end to end.

A governed loop, shown as the structured trace an engineer would read: classified intent, assembled prompt, scoped execution, validation gates.

intentUser: "Add validation to the orders API"
governance→ Action classified as sensitive. Approval gate fires.
clean-prompt→ Prompt assembled: scope=src/orders, tools=[fs:read, fs:write, test:run], no secrets.
controlled-execution→ PTY zsh @/repo · 3 files changed · approval required before git commit.
validation→ typecheck ✓ · vitest ✓ · playwright smoke ✓. P0 filter: passed.
compact-memory→ Outcome stored to local SQLite (768d embedding · 142 tokens).
Illustration. Real runs differ in detail but pass through the same gates.

Built-in vs user-provided

CapabilityBuilt-in to DevAware OSUser-provided
Chat surface, governance, prompt assemblyBuilt-in—
Real PTY, terminal guards, file checkpointBuilt-in—
Validation gates (typecheck, lint, test, build, smoke)Built-in—
Local AI runtime (open-source, user-installed)DetectedUser-installed
Cloud providerRoutedUser-supplied API key
OAuth provider (CLI session)DetectedUser's own provider plan
Image gen / edit (Studio)Apple-Silicon onlyUser-installed mflux venv
MCP serversStdio clientUser-configured + trust grant
Third-party security tools (scanners / sandboxes / EDR)—User-installed; not bundled

Real surfaces in the app today.

Each row is a shipping surface with a file-path citation — not a roadmap claim.

  • Workspace

    Recent-projects list, folder open, project tree with ignored-dir pruning (capped ~5000 entries), file preview pane, symbol palette (⌘P), command palette (⌘K), per-project preset store.

    evidence · src/App.tsx · ProjectTreePanel.tsx · CommandPalette.tsx

  • Multi-terminal PTY

    Real PTYs via node-pty + xterm.js, multi-tab, branch-aware label, shell from $SHELL or /bin/zsh, resize/dispose handled, group-kill on detached spawn.

    evidence · electron/ipc/terminal.ts · TerminalTabs.tsx · TerminalPane.tsx

  • Preview + CDP inspection

    Webview on persist:uct-preview partition, DOM agent eval + screenshots, CDP network capture, console capture, Playwright smoke + step-driven navigation + screenshot.

    evidence · PreviewPanel.tsx · electron/ipc/domAgent.ts · network.ts · playwright.ts

  • Multi-provider chat

    Provider-independent routing across three lanes: a user-installed local open-source runtime (NDJSON stream), cloud provider APIs through your own keys (streaming), and an OAuth-CLI adapter for session tokens. You choose the lane per request.

    evidence · electron/ipc/qwen.ts · electron/ipc/models.ts · electron/util/claudeCliAuth.ts

  • Verb auto-continue

    Depth ≤ 3. Each turn parses <<read:…>>, <<grep:…>>, <<symbol:…>>, <<exec:…>>, <<pw:smoke:…>>, <<pw:steps:…|[…]>>, runs against existing IPC, injects results as synthetic role:tool followups that re-stream.

    evidence · electron/chat/coordinator.ts · electron/chat/verbs.ts

  • Governed agent exec

    Read-oriented allowlist (git status|diff|log|show|branch|remote|rev-parse|blame|ls-files, npm run typecheck|test|lint|build:renderer, tsc, eslint, ruff, rg, grep, find, ls, cat, head, tail, wc). Hard-deny regex blocks shell metacharacters, sudo, chmod 777, destructive patterns.

    evidence · electron/ipc/agentTools.ts

  • Code symbol index

    Regex-based symbol extraction for ts/tsx/js/jsx/py/rs/go/java/kt/swift/rb/php/c/cpp/cs/vue/svelte. SQLite snapshot cache. index:rebuild / search / find / byFile / fileSymbols.

    evidence · electron/ipc/codeIndex.ts

  • MCP stdio client

    JSON-RPC 2.0 over newline-delimited JSON. mcp:start / stop / list / tools / call. Project-scope servers require a trust grant.

    evidence · electron/ipc/mcp.ts

  • Compact memory + SQLite

    better-sqlite3, WAL, foreign keys, in-process migrations. v2 messages + parts schema, ULID-keyed, throttled DB flush, abort + interruption recovery. 768-dimension embeddings from a local open-source embedding model served by the local runtime.

    evidence · electron/db/* · electron/chat/db.ts · electron/orchestrator/memoryStore.ts

  • Secrets at rest

    Provider API keys encrypted via Electron safeStorage (Keychain on macOS, DPAPI on Windows, libsecret on Linux). Plaintext fallback marked in Settings when the OS keychain is unavailable. Keys never reach the renderer.

    evidence · electron/ipc/secrets.ts

  • 18 governance blocks

    Mandatory inspection · root-cause fix · anti-duplication · security guardrails · Supabase/migration safety · auth/permissions safety · UI/design standards · token Save/Normal/Spend · validation gates · compact final report · large execution wave · small targeted fix · refactor discipline · cleanup · Playwright preview · runtime smoke · do-not-touch-unrelated-areas.

    evidence · src/lib/blocks.ts · BlocksLibrary.tsx · PromptBuilder.tsx

  • Workflow-noise heuristics

    Detects P0 inflation, prompt bloat, emotional language, repeated lines, vague objectives, missing objective/validation/scope, conflicting token modes, root-cause framing on trivial changes. One-click auto-fix where safe.

    evidence · src/lib/heuristics.ts

18 default governance blocks.

Recommended blocks light up after intent analysis. Custom blocks can be authored and persisted per project. Each block compiles into the final prompt the agent receives.

  • inspect

    Mandatory inspection

    Read the actual implicated files before planning. Cite paths + line ranges.

  • scope

    Anti-duplication

    Search before adding. Reuse existing hooks, components, IPC channels. No parallel implementations.

  • root

    Root-cause discipline

    Patches that mask root cause are rejected. Fix at the source.

  • security

    Security guardrails

    Changes to CSP, env masking, destructive-command block, agent allowlist, safeStorage, or summarized model context must be reported explicitly.

  • db

    Supabase / migration safety

    Migrations are additive. Destructive operations against project DBs are blocked at the IPC boundary.

  • auth

    Auth / permissions safety

    Renderer cannot self-grant trust. Permission requests default-deny on the main session.

  • ui

    UI / design standards

    Density, hierarchy, empty/loading/error states, keyboard-first parity. WCAG 2.2 AA contrast floor.

  • token-save

    Token mode · Save

    Constrains the loop to the cheapest path that still satisfies validation.

  • token-normal

    Token mode · Normal

    Default balance between exploration and execution.

  • token-spend

    Token mode · Spend

    Allows wider inspection + parallel verification for high-risk changes.

  • validate

    Validation gates

    Typecheck · lint · test · build:renderer · smoke. Non-negotiable before the loop declares done.

  • report

    Compact final report

    Final-output contract: what changed, what was validated, what is intentionally pending.

  • wave

    Large execution wave

    Authorizes wide changes when scope and inspection match.

  • fix

    Small targeted fix

    Locks the loop to a minimum-edit posture.

  • refactor

    Refactor discipline

    Refactor must preserve behavior; validation suite must remain green.

  • cleanup

    Cleanup / deduplication

    Removes orphaned code, duplicate hooks, dead imports as part of the change.

  • preview

    Playwright preview

    Boots the dev server and checks the live page through Playwright.

  • smoke

    Runtime smoke test

    Console-error capture + DOM probe verifies the running app didn't break.

Six verbs for in-loop auto-context.

Verbs are parsed from each turn and executed against existing IPC. Results inject as synthetic role:tool followups that re-stream. Depth is capped at 3.

verbbehavior
<<read:path>>Read a file from the project (size-capped, mask applied for env-shaped paths)
<<grep:pattern>>Run agent:grep against the project root (path-glob filter, regex, size + extension guards)
<<symbol:name>>Look up a symbol in the SQLite code index (regex extraction for 17 languages)
<<exec:cmd>>Run an allowlisted command through agent:exec (read-oriented binaries only; hard-deny on shell metacharacters)
<<pw:smoke:url>>Drive a Playwright smoke run: boot dev server, navigate, screenshot, capture console errors + DOM probe
<<pw:steps:url|[steps]>>Drive a Playwright step sequence on top of the smoke harness

The chat timeline has structured lanes.

Chat is treated as a structured agent timeline, not a raw transcript. Streaming is visually distinct from finalized state.

  • user intent

    The natural-language request typed by the developer; the source of truth for what the loop is for.

  • assistant answer

    The model's primary response, formatted with streamdown markdown inside the structured timeline.

  • reasoning

    Collapsible thinking lane (ReasoningBlock). De-emphasized by default; expandable on demand.

  • tool request

    Each tool call the model proposes; routed through the verb layer or via the agent allowlist.

  • tool result

    The bounded output of a tool call. Hard caps apply at every boundary; bypasses are surfaced explicitly.

  • injected context

    Synthetic role:tool followups from verb execution. The model sees them; the user sees them too.

  • validation result

    Typecheck / lint / test / build:renderer / smoke results, surfaced as first-class lanes rather than raw exec output.

  • blocker

    Errors, aborts, interruptions. The loop stops here and reports rather than guessing.

  • next action

    An explicit, single next step. The agent does not act without a named action.

Evidence, not logos

DevAware OS is in active development; we have no formal audit on file. Instead of unverifiable badges, here is the evidence itself.

  • Architecture

    Local-first by architecture

    Renderer runs inside the Chromium sandbox with context isolation. CSP restricts connect-src to user-chosen provider endpoints.

    evidence · electron/main.ts:195-205 · 485-530

  • Privacy

    BYO-key for cloud providers

    Provider API keys are encrypted at rest in the OS keychain (Keychain / libsecret / DPAPI). They never reach the renderer.

    evidence · electron/ipc/secrets.ts:1-79

  • Measurement

    No telemetry

    chat:send outcomes write only to local SQLite. No analytics SDK in package.json.

    evidence · db/migrations.ts:415 · package.json

  • Control

    Approval gate on tool calls

    Flagged tool calls require renderer approval before they run. proc:spawn refuses destructive commands at the spawn boundary.

    evidence · electron/orchestrator/approvalGate.ts · electron/ipc/process.ts:18-31

Keep going.

Walk the pipeline, read the architecture, or browse the full docs.

How it works ArchitectureDocs