How hack-ink/decodex works
1. Workspace shape
- This is a Rust-first monorepo centered on apps/decodex, with three other executable products: apps/radar, apps/decodex-publisher, and the macOS app in apps/decodex-app.
- The repo also includes a static Astro site in site/, installable Codex plugins in plugins/, and authoritative docs/specs in docs/.
2. Core runtime: decodex CLI + daemon
- apps/decodex is the main runtime and CLI binary.
- It is both an operator command surface and a local control-plane daemon (decodex serve) that schedules retained work, polls external systems, publishes snapshots, and serves local APIs/UI.
3. Persistent state boundary
- The runtime keeps authoritative local state in a SQLite-backed store under the state/ subsystem.
- That store persists run control, review records, runtime events, autonomy objects, leases, account metadata, and derived projections.
- The key architectural boundary is: external systems are observed and reconciled into local state first; the daemon then drives dispatch from that local state.
4. Operator control plane
- decodex serve exposes the local operator listener on HTTP.
- It serves the dashboard at / and /dashboard, liveness at /livez, account APIs for the Decodex App, and a WebSocket control channel at /dashboard/control.
- This is the human-facing coordination layer for snapshots, control actions, and live activity updates.
5. MCP gateway
- The mcp/ subsystem is a protocol gateway for desktop/CLI clients.
- It serves resources, prompts, and tools over stdio or streamable HTTP, with capability profiles that gate what operations are exposed.
- Architecturally, it is a read/plan/operate/admin facade over the same runtime state and control logic, not a separate engine.
6. Execution and orchestration
- The orchestrator/ subtree is the main policy engine for retained lanes and loop execution.
- It coordinates scheduling, run cycles, lane control, dispatch policy, recovery, reconciliation, and status projection.
- It also owns the HTTP/operator integration, worktree lifecycle, and the logic that decides whether a project/run is active, stalled, or needs recovery.
7. External integrations
- The runtime integrates with Linear, GitHub, Git, and Codex app-server / app helper APIs.
- These are not treated as isolated adapters; they feed into orchestration, status projection, and retained lane state.
- The data flow is typically: poll or receive external facts → normalize into local state → project into dashboard/status/MCP resources → decide whether to dispatch or recover.
8. Account management
- The accounts/ and agent/codex_accounts/ areas manage the shared Codex account pool, login state, token/usage tracking, and selection policy.
- The native macOS app in apps/decodex-app is a UI over these account APIs and the shared local runtime state.
- Account identity, privacy-preserving display names, usage history, and auth failure handling are all modeled as local Decodex state rather than project-local config.
9. Autonomy and research pipeline
- The repo has a distinct autonomy model: autonomy_objective, autonomy_proposal, autonomy_signal, loop_contract, execution_program, program_intake, and research_design.
- The flow is intentionally staged: draft or compile a contract, promote it if accepted, then materialize executable work through program intake.
- This separates non-executable research/proposal artifacts from executable Linear/program state.
10. Recovery and hygiene
- recovery/, maintenance/, archive_hygiene/, and related orchestration modules handle failure recovery, stale state cleanup, ghost lane repair, worktree cleanup, and log/evidence retention.
- These are bounded subsystems that repair or reconcile local/runtime state after interrupted runs, stale worktrees, or terminal failures.
- They support the daemon’s “keep running safely” posture without conflating cleanup with normal execution.
11. Public site vs runtime
- site/ is a static Astro site for the public product surface and download entry.
- It is explicitly separate from the runtime and does not own scheduling, tracker writes, or local operator state.
- Publication is externalized; the site is a presentation boundary, not part of the operational control plane.
12. Auxiliary tools
- apps/radar is a standalone analysis/ledger tool for release validation, upstream review, signal rendering, and artifact tracking.
- apps/decodex-publisher is a separate CLI for social candidate validation, reservation, and post publishing workflows.
- Both are adjacent tools in the ecosystem, but they are not the main runtime loop.
13. Plugins and docs as governance layers
- plugins/ packages reusable skills and policies consumed by Codex workflows.
- docs/spec, docs/runbook, docs/reference, and docs/decisions define the governing contracts, operating procedures, current behavior, and design rationale.
- In architecture terms, docs and plugins are part of the control surface and policy boundary around the runtime, not mere commentary.
14. Overall system diagram
- The clean mental model is: local SQLite-backed runtime state at the center; external systems (Linear/GitHub/Git/Codex app-server) feeding it; orchestration deciding dispatch/recovery; operator UI and MCP exposing it; and auxiliary tools plus docs/plugins surrounding it as governance and specialized workflows.
Main entry points: orchestrator.rs Orchestrator · state.rs Local state · main.rs decodex CLI · index.md Docs
Components 23
Decodex runtime
Main CLI daemon, orchestration, state, and local control planes.
- decodex CLI · Primary operator command surface and daemon entrypoint.
apps/decodex/src/main.rs - Commands · Operator commands for control, recovery, intake, and account actions.
apps/decodex/src/cli.rs - Orchestrator · Retained-lane scheduler, dispatch policy, run cycles, recovery, and status projection.
apps/decodex/src/orchestrator.rs - Local state · Authoritative persistent boundary for runs, reviews, events, leases, accounts, and projections.
apps/decodex/src/state.rs - MCP gateway · Tools, prompts, resources, and capability-gated access over shared runtime state.
apps/decodex/src/mcp.rs - Operator HTTP · Local dashboard, account APIs, liveness, snapshot delivery, and WebSocket control channel.
apps/decodex/src/orchestrator/operator_http.rs - Status · Derived run, lane, worktree, queue, and recovery views for operator-facing presentation.
apps/decodex/src/orchestrator/status.rs - Lane control · Lane selection, interrupts, steering, and retained execution coordination.
apps/decodex/src/orchestrator/lane_control.rs - Run cycle · Prepares, executes, and completes retained runs and project ticks.
apps/decodex/src/orchestrator/run_cycle.rs - Recovery · Recoveries for stale active runs, ghost lanes, handoffs, and terminal failures.
apps/decodex/src/recovery.rs - Accounts · Shared Codex account identity, login state, usage tracking, and selection policy.
apps/decodex/src/accounts.rs - Autonomy · Objectives, proposals, signals, contracts, and execution-program intake/promotion.
apps/decodex/src/autonomy_objective.rs
External integrations
Systems observed and reconciled into Decodex state.
- Tracker · Linear issue tracking, record projections, privacy classification, and public text rendering.
apps/decodex/src/tracker.rs - GitHub · Repository, branch, comment, and merge/readback integration used by orchestration and recovery.
apps/decodex/src/github.rs - Git ops · Branching, selection, diagnostics, rewrites, and worktree lifecycle used by the runtime.
apps/decodex/src/orchestrator/git_ops.rs - App server · Protocol bridge to the Codex app-server/runtime, including turn loop and preflight.
apps/decodex/src/agent/app_server.rs - App helper · Small binary used by the macOS app to bridge into the local runtime.
apps/decodex/src/bin/decodex-app-helper.rs
Adjacent apps
Separate products in the repository ecosystem.
- decodex-app · macOS client UI over account APIs and shared operator/runtime state.
apps/decodex-app/Sources/DecodexApp/DecodexApp.swift - radar · Release validation, upstream review, artifact tracking, and ledger analysis.
apps/radar/src/main.rs - publisher · Social candidate validation, reservation, and publish workflows.
apps/decodex-publisher/src/main.rs
Governance surface
Docs, plugins, and public site that shape behavior and usage.
- Public site · Static product surface and download entry, separate from the runtime control plane.
site/src/pages/index.astro - Plugins · Reusable skills, references, and hooks consumed by Codex workflows.
plugins/decodex/.codex-plugin/plugin.json - Docs · Authoritative contracts, runbooks, decisions, and reference material.
docs/spec/index.md
Connections 27
- decodex CLI → Commands: dispatches to · The binary exposes the operator command surface and daemon entrypoints.
- decodex CLI → Orchestrator: boots · Core runtime logic is centered in the orchestrator.
- decodex CLI → Local state: persists in · Daemon state is backed by the local SQLite store.
- Orchestrator → Local state: reads/writes · Orchestration reconciles external facts into local state before dispatch.
- Orchestrator → Status: projects · The orchestrator derives operator-facing status and dashboard views.
- Orchestrator → Lane control: controls · Lane policy governs retained execution and steering.
- Orchestrator → Run cycle: runs · Retained work is advanced through scheduled run cycles.
- Orchestrator → Recovery: repairs · Stale or interrupted work is recovered through repair flows.
- Orchestrator → Tracker: ingests · Tracker facts feed status projection and retained lane state.
- Orchestrator → GitHub: integrates · GitHub events and repository state inform orchestration and recovery.
- Orchestrator → Git ops: uses · Worktree and branch operations support run execution and repair.
- Orchestrator → App server: bridges · Codex app-server protocol is surfaced through orchestration.
- Local state → Accounts: stores · Account identity, login state, and usage history are persisted locally.
- Local state → Autonomy: stores · Autonomy objectives, proposals, signals, and programs live in local state.
- Local state → Recovery: records · Recovery decisions and repair metadata are written as runtime state.
- MCP gateway → Local state: reads · MCP resources and projections are backed by the same runtime state.
- MCP gateway → Orchestrator: operates over · MCP tools plan, inspect, and act through the runtime control logic.
- Operator HTTP → Status: serves · HTTP dashboard and live views are rendered from status projections.
- Operator HTTP → Local state: serves data from · Operator APIs expose local persisted state and snapshots.
- decodex-app → Operator HTTP: connects to · The macOS app is a UI over local operator APIs and dashboard sockets.
- App helper → decodex-app: supports · Native helper bridges the app to local runtime capabilities.
- publisher → Local state: coordinates with · Publishing workflow uses local runtime state and reservations.
- radar → GitHub: analyzes · Radar consumes GitHub and release artifacts for validation workflows.
- Public site → Docs: documents · Public site is governed by repo contracts and documentation.
- Plugins → MCP gateway: extends · Plugins define skills and policies used by Codex-facing workflows.
- Docs → Orchestrator: specifies · Specs and runbooks define the intended behavior of the runtime.
- Docs → Public site: separates · Docs explicitly distinguish the public site from the operational control plane.