Decodex

Repo-native agent orchestration, upstream Codex radar, and public publishing.

Feature Highlights

• Rust CLI and runtime for repo-native retained coding-agent lanes.
• Native macOS app for Decodex Codex account-pool management.
• Explicit project registry under ~/.codex/decodex/projects/<service-id>/.
• Local operator listener with a dashboard at / and /dashboard, WebSocket snapshot/control traffic at /dashboard/control, Decodex App snapshot/account APIs under /api/, and GET /livez for liveness.
• Static Astro site that publishes curated Decodex Radar and Publisher output.
• Deterministic GitHub upstream Radar pipeline for review queues, change bundles, release deltas, rendered signal entries, and content validation.
• Repo-local Radar skills for upstream Codex triage, code analysis, release analysis, signal drafting, and X publishing.
• Publisher workflow for checked-in upstream reviews, impact classification, curated public signals, and automated low-frequency X publication records for @decodexspace.
• Installable Decodex plugin with reusable agent-facing skills for planning, manual CLI, automation, commit, land, and labels.
• Repository documentation split by question type into spec, runbook, reference, and decision lanes.

Status

Prototype / in active development.

This repository now integrates the former runtime repository and the static signal site into one Decodex workspace. The static site remains the public surface by default. Runtime and operator behavior does not become a public site backend just because both surfaces live in one workspace.

Supported runtime host targets are macOS and Linux. Windows remains unsupported for the runtime.

App identity

• Product display name: Decodex.
• Runtime CLI binary: decodex.
• Public site: https://decodex.space.
• Lower-case decodex remains only for stable technical identifiers such as the repository slug, Cargo package name, CLI binary, plugin package, config keys, and schema names.

Workspace posture

• apps/decodex/ owns the Rust package that builds the decodex CLI and runtime.
• apps/decodex-app/ owns the native macOS app that manages Decodex Codex accounts through the bundled Rust app helper.
• site/ owns the Astro static site and checked-in public content.
• apps/decodex/src/radar.rs owns Rust Radar queue, release-delta, bundle, render, validation, backfill, and ledger commands.
• scripts/github/ owns the automation-only Codex AI analysis helper and shared schema support for that helper.
• artifacts/github/ owns checked-in review queues, upstream reviews, GitHub bundles, impact records, and editorial analysis drafts.
• artifacts/archive/ owns checked-in recovery manifests for cold Radar batches stored as GitHub Release assets.
• artifacts/social/ owns checked-in Publisher publication records and generated-media evidence.
• plugins/decodex/ owns the installable Decodex plugin and reusable agent-facing skills.
• dev/skills/ owns repository-development skills for Radar analysis and Publisher publishing. They are not packaged with the installable Decodex plugin.
• docs/ remains the authoritative documentation surface.

Runtime authority stays in apps/decodex/src/, the registered project contracts under ~/.codex/decodex/projects/<service-id>/, and the governing specs under docs/spec/. Public site authority stays in site/, apps/decodex/src/radar.rs, artifacts/github/, and the site/content specs.

Historical Radar trace is local by default. decodex radar refresh-upstream-queue writes .decodex/radar.sqlite3 and refreshes upstream_review_queue/v1 so every inspected upstream commit can be tracked before AI review decides whether it deserves Decodex follow-up, public content, or only ledger trace.

Runtime platform support

• The Decodex runtime contract is Unix-only: macOS and Linux.
• Windows is outside the runtime contract.
• Current Codex/app-server compatibility is capability-gated and recorded in docs/spec/app-server.md.
• The public site is static and deploys through GitHub Pages.
• Starting decodex serve without its --config option schedules enabled projects from the explicit registry only. Operator and App snapshots still expose active runtime DB-backed attempts for disabled projects, because disabling a project pauses future dispatch rather than deleting visibility or ownership. It does not scan Codex history, repo-local config files, or currently open worktrees to infer projects.

Usage

Runtime CLI

From the workspace root:

cargo run -p decodex --bin decodex -- --help
cargo run -p decodex --bin decodex -- probe stdio://
cargo run -p decodex --bin decodex -- project list
cargo run -p decodex --bin decodex -- status
cargo run -p decodex --bin decodex -- status --live
cargo run -p decodex --bin decodex -- diagnose --json
cargo run -p decodex --bin decodex -- maintenance prune --dry-run
cargo run -p decodex --bin decodex -- lane steer <ISSUE> --run-id <RUN_ID> --expected-turn-id <TURN_ID> --message <TEXT>
cargo run -p decodex --bin decodex -- radar refresh-upstream-queue
cargo run -p decodex --bin decodex -- radar refresh-release-delta
cargo run -p decodex --bin decodex -- radar validate
cargo run -p decodex --bin decodex -- run --dry-run
cargo run -p decodex --bin decodex -- serve --listen-address 127.0.0.1:8912

Project-scoped commands accept --config <PROJECT_DIR> after the subcommand when the operator wants to override registry-based project resolution for that command. Use --allow-unverified-codex on run, serve, or probe only when deliberately dogfooding a Codex build outside the locally verified app-server range; the default guard remains fail-closed. decodex status prints the local runtime snapshot without refreshing live tracker, pull-request, or Codex account usage observers. Use decodex status --live when the operator needs fresh Linear/GitHub readback before acting; use the Accounts API refresh path, such as GET /api/accounts?refresh=1, when the operator needs fresh ChatGPT account usage probes. decodex serve uses hardcoded scheduler cadences: the local control-plane loop publishes snapshots every 15 seconds, and Linear-backed queue/status scans run at most every 5 minutes per project unless an operator or agent requests an explicit scan with POST /api/linear-scan.

Install from Source

git clone https://github.com/hack-ink/decodex
cd decodex

cargo install --path apps/decodex --force
decodex --version

Project contracts

Project contracts are managed outside checkouts under ~/.codex/decodex/projects/<service-id>/ with fixed filenames:

• project.toml for service paths and credential environment-variable names
• WORKFLOW.md for execution policy

The redacted template for a project config lives at decodex.example.toml. When a project enables [codex.accounts], the shared ChatGPT account pool is ~/.codex/decodex/accounts.jsonl; it is global Decodex state, not a project-local file, and project configs do not own an account-pool path override. Set [codex.accounts].fixed_account in ~/.codex/decodex/config.toml to pin all new account-pool runs to one account. When that global selector is absent, Decodex balances new runs across the pool. The operator dashboard Accounts UI writes and clears the same global selector; project configs do not pin specific accounts. Account display-name rerolls are also global Decodex state under [codex.account_names.offsets] in ~/.codex/decodex/config.toml so the operator dashboard and Decodex App show the same privacy-preserving names. Client-only presentation preferences such as theme, sorting, and whether identities are hidden remain local to each UI. Usage probes also read Codex profile token stats for local Accounts displays. Bounded seven-day account usage estimates are kept in ~/.codex/decodex/account-usage-history.jsonl; the file stores daily percentage snapshots plus non-secret capacity weights for local display and no token material. To switch the account used by the Codex CLI itself, run decodex account use <selector> or use the Decodex App row action; this overwrites $CODEX_HOME/auth.json or ~/.codex/auth.json from the matching accounts.jsonl entry. Later account-pool token refreshes also update that Codex auth target when it currently contains the same account id.

decodex diagnose --json writes the local agent evidence index under ~/.codex/decodex/agent-evidence/<service-id>/ and prints the same handoff index for repair agents.

decodex maintenance prune defaults to the same read-only report as decodex maintenance prune --dry-run. Add --apply to rotate oversized local logs and agent-evidence event streams, prune old backup files, compact old terminal-run protocol events after preserving their summary, and checkpoint the SQLite WAL. decodex serve also runs the auto-safe subset at startup and periodically while it is polling.

Static Site

The public site is an Astro static site under site/. It renders checked-in content and generated JSON artifacts, then deploys through GitHub Pages.

The public site owns:

• Codex signal cards
• release-delta presentation
• continuous Radar status presentation
• static assets and public page rendering

The public site does not own:

• retained-lane scheduling
• tracker writes
• local operator state
• app-server orchestration
• the operator dashboard served by decodex serve

The static-site boundary is recorded in docs/decisions/static-public-site.md. GitHub Pages setup for https://decodex.space lives in docs/runbook/github-pages-deploy.md.

Upstream Radar Pipeline

The upstream Codex Radar path starts deterministic and becomes editorial only after Codex automation reviews source evidence:

• decodex radar refresh-upstream-queue records every observed recent upstream commit, resolves PRs when possible, and refreshes artifacts/github/review-queue/openai-codex-latest.json.
• dev/skills/README.md routes the repo-local Radar and editorial instructions. They are not part of the installable Decodex plugin distribution.
• decodex radar bundle build builds normalized GitHub bundles under artifacts/github/bundles/ when a queued subject needs full source context.
• decodex radar backfill-release-range fills release-window gaps before a release or prerelease summary, but daily Radar still starts from the commit stream.
• docs/spec/upstream-review.md records the queue and AI review boundary.
• docs/spec/upstream-impact.md records how upstream Codex changes are classified for public signals and Control Plane follow-up work.
• decodex radar render-signal renders reviewed analysis drafts into site content.
• decodex radar validate validates the published signal collection and checked Radar artifact contracts.
• decodex radar refresh-upstream-queue, decodex radar refresh-release-delta, decodex radar bundle validate, decodex radar ledger ..., decodex radar render-signal, decodex radar backfill-release-range, and decodex radar validate provide the Rust-owned command surface for deterministic queue refresh, release-delta refresh, bundle validation, local ledger maintenance, signal rendering, release-window backfill, and checked Radar artifact validation.
• docs/spec/social-publishing.md and docs/runbook/social-publishing-workflow.md govern automated low-frequency X publication for @decodexspace.
• .github/workflows/refresh-upstream-radar.yml refreshes deterministic upstream queue metadata every six hours.
• .github/workflows/refresh-release-delta.yml refreshes release and prerelease checkpoint metadata every hour.
• .github/workflows/deploy-pages.yml publishes the Astro site to GitHub Pages on pushes to main.

The governing workflow lives at docs/runbook/local-github-signal-workflow.md.

Operator Dashboard

decodex serve owns the local operator listener. It serves the operator dashboard from GET / and GET /dashboard; published snapshots, active-run updates, and local dashboard controls flow through the /dashboard/control WebSocket. The HTTP surface is kept to dashboard pages/assets, GET /livez, and the local account-control API used by Decodex App.

For dashboard UI development, use the mock operator dashboard server:

node dev/operator-dashboard-mock.mjs --listen-address 127.0.0.1:57399
node dev/operator-dashboard-mock.mjs --listen-address 127.0.0.1:57399 --use-codex-auth

Use hidden decodex serve --dev --listen-address 127.0.0.1:8912 only when developing local account/app snapshot APIs against real runtime state while explicitly avoiding scheduler activity. Dev mode deliberately does not register projects, poll Linear, dispatch work, or accept --config. Decodex App's normal fallback server is ordinary decodex serve --listen-address 127.0.0.1:8192; the CLI owns the default scheduler cadences. App launch connects to an existing live default listener instead of starting a duplicate server. For dashboard-only UI work, prefer the mock server above.

The dashboard semantics and local-vs-external state boundary live in docs/reference/operator-control-plane.md.

Development

Repo-native validation is owned by Makefile.toml.

Runtime checks follow the Decodex task structure:

cargo make check
cargo make fmt
cargo make lint
cargo make test

Whole-workspace checks include runtime, static-site, and content validation:

cargo make checks

Static-site/content checks are available separately:

cargo make decodex-checks

Workspace Layout

The tracked workspace currently keeps:

• apps/decodex/ as the Rust package that builds the decodex CLI and runtime
• site/ as the Astro static site for the public Decodex signal surface
• scripts/github/ as the deterministic GitHub collection, normalization, render, and validation script surface
• artifacts/github/ as checked-in GitHub bundle and analysis artifacts
• plugins/decodex/ as the canonical installable Decodex plugin source
• dev/skills/ as repo-development Radar analysis and Publisher publishing skills that are not packaged with the installable Decodex plugin
• docs/spec/ as the normative runtime, workflow, site, and content contract lane
• docs/runbook/ as the operator procedures, validation sequences, deployment steps, and content workflow lane
• docs/reference/ as the current repository and artifact surface map lane
• docs/decisions/ as the durable design-rationale lane
• docs/research/ as machine-authored research artifacts used by shipped research tooling
• docs/plans/ as historical saved plan artifacts from the static-site bootstrap
• dev/ as local development helpers outside dev/skills/, such as the operator dashboard mock server
• assets/ as generated Decodex App icon source notes, Icon Composer foreground, generated .icns, and menu bar template assets
• .github/ as CI, release, Pages deployment, and content-refresh workflows

Generated or local-only directories such as target/, site/dist/, site/.astro/, .worktrees/, .workspaces/, and .codex/ are not part of the tracked repository structure. For the authoritative layout and ownership map, read docs/reference/workspace-layout.md.

Documentation

• Product and development overview: this README.md
• Unified documentation router: docs/index.md
• Normative specs: docs/spec/index.md
• Procedural runbooks: docs/runbook/index.md
• Current implementation references: docs/reference/index.md
• Durable design rationale: docs/decisions/index.md
• Documentation policy and placement rules: docs/policy.md

Support Me

If you find this project helpful and would like to support its development, you can buy me a coffee!

Your support is greatly appreciated and motivates me to keep improving this project.

• Fiat
  • Ko-fi
  • Afdian
• Crypto
  • Bitcoin
    • bc1pedlrf67ss52md29qqkzr2avma6ghyrt4jx9ecp9457qsl75x247sqcp43c
  • Ethereum
    • 0x3e25247CfF03F99a7D83b28F207112234feE73a6
  • Polkadot
    • 156HGo9setPcU2qhFMVWLkcmtCEGySLwNqa3DaEiYSWtte4Y

Thank you for your support!

Appreciation

We would like to extend our heartfelt gratitude to the following projects and contributors:

• The Rust community for their continuous support and development of the Rust ecosystem.

Additional Acknowledgements

• TODO

License

^{Licensed under GPL-3.0.}