Prime Coder

Codex-native project memory, task orchestration, and bounded cheap-model execution for solo developers working on large projects.

Prime Coder keeps Codex as the quality source for architecture, planning, review, and decisions. A cheaper OpenAI-compatible executor is used only for already-bounded implementation packets where the task, files, validation commands, and guardrails are explicit.

Install

Prerequisites:

• Node.js >=22.13.0 (node:sqlite is unflagged from 22.13.0);
• Codex with local plugin support;
• an OpenAI-compatible executor provider if you want bounded model execution.

Install the published local runtime:

npm install -g [email protected]
prime-coder --help
PRIME_CODER_RUNTIME_ROOT="$(npm root -g)/prime-coder-local-runtime"
codex plugin marketplace add "$PRIME_CODER_RUNTIME_ROOT"
codex plugin add prime-coder@prime-coder-local

The published runtime already contains the local marketplace manifest, plugin manifest, MCP server, CLI, connector, and required runtime dependencies. The Git repository flow below is only for source development and contributor validation; it is not the end-user install path.

Start a new Codex thread after installing so the MCP server is loaded.

For source/development validation, install from this repository:

git clone https://github.com/mykhailoPavliuk/Prime-coder.git
cd Prime-coder
npm ci
npm run install:server-deps
npm run install:web-deps
npm run release:check

codex plugin marketplace add "$PWD"
codex plugin add prime-coder@prime-coder-local

See docs/demo-walkthrough.md for the full runtime install and first-project walkthrough.

Optional decision-only routing through an external JevRouter launcher is documented in docs/jevrouter-integration.md. It is disabled by default and never executes a selected capability automatically.

Web Control Center can deliver FairPrice AI, JevRouter/TypeSafe, and JevRouter/OpenRouter API keys to an explicitly paired account device shared by that machine's project connectors. The browser encrypts each key to that device, the hosted backend relays only short-lived ciphertext, and the local connector installs it into the OS keychain after local approval. See docs/credential-delivery.md.

First Run In A Project

From the project you want Prime Coder to manage:

prime-coder os init
prime-coder os refresh-context
prime-coder os status
prime-coder os board

This creates local .prime-coder/ state:

• project, module, epic, and task YAML records;
• generated context packs for fast Codex resume;
• task packets for bounded executor work;
• session receipts for checkpoint discipline;
• a static Kanban board at .prime-coder/board/index.html;
• review and validation evidence artifacts.

The local state is durable project memory for Codex, but it is not meant to be committed to the application repository. Treat it like developer-local tooling state: back it up when needed, keep it out of product history, and let Codex sessions resume from the local .prime-coder/ directory.

prime-coder os init, prime-coder os migrate, and prime-coder os repair keep project .gitignore rules current for .prime-coder/, .prime-coder.backup.*/, graphify-out/, and local .codex/ settings.

Executor Setup

The executor talks to any OpenAI-compatible API through baseUrl, a local OS-keychain credential (or explicit environment override), and an optional model.

Recommended first setup is global so every Prime Coder project can reuse the same cheaper executor provider:

prime-coder executor presets
prime-coder executor setup --preset fair-price.ai
prime-coder executor config

Set the API key from Web Control Center under Settings → API keys, then run prime-coder os connector credentials apply --approve on the paired device. Environment variables remain an explicit per-process override; the fair-price.ai preset uses FAIR_PRICE_API_KEY.

Use the same MCP server settings gear to set PRIME_CODER_EXECUTOR_ENABLED=false when you want Prime Coder to stay Codex-only and avoid cheap-model calls. Unset it, or set it to true, to allow bounded executor work again.

Supported presets:

• fair-price.ai;
• openrouter;
• ollama;
• lm-studio;
• custom.

Custom provider example:

export PRIME_CODER_EXECUTOR_API_KEY="..."
prime-coder executor setup \
  --base-url "https://api.example.com/v1" \
  --api-key-env-var PRIME_CODER_EXECUTOR_API_KEY \
  --model "provider/model-name"

Prime Coder stores global provider metadata in ~/.config/prime-coder/executor-config.json by default and rejects plaintext API keys. Existing .prime-coder/executor-config.json files are treated as project-specific overrides only. Use prime-coder executor setup --project ... when a repository intentionally needs a different provider.

Daily Workflow

Create or inspect work:

prime-coder os epic list
prime-coder os task create --epic EPIC-001 --title "Add import flow"
prime-coder os resume TASK-001

Prepare bounded executor work:

prime-coder os packet TASK-001
prime-coder dispatch --target local --task TASK-001
prime-coder os run-result TASK-001

Checkpoint and review:

prime-coder os checkpoint TASK-001 --status done --validation "npm test: pass"
prime-coder os review-record TASK-001 --gate plan-eng-review --status clear
prime-coder os review-record TASK-001 --gate review --status clear
prime-coder os review-readiness TASK-001

Project hygiene:

prime-coder os status
prime-coder os audit --brief
prime-coder os uncheckpointed
prime-coder os review-reminders

For Prime Coder checkout health before publishing or sharing a build, run npm run doctor from the Prime Coder repository. Missing executor provider credentials are acceptable there as a warning before first setup.

Automations

Prime Coder ships read-only automation templates under automations/:

• project health;
• stale task audit;
• uncheckpointed work detection;
• review readiness reminders.

They are static JSON templates, not a resident app. Run them from Codex, cron, Vercel Cron, GitHub Actions, or another scheduler after reviewing the commands.

See docs/automations.md.

Validation And Release Checks

Before publishing or sharing a build:

npm run release:check

This runs plugin validation, generated MCP docs checks, the production Web Control Center build, CLI and MCP smoke tests, the test suite, doctor checks, package file checks, and clean-machine install smoke. GitHub CI separately enforces PostgreSQL integration and packed-runtime native keychain smokes on macOS, Windows, and Linux.

License And Terms

Prime Coder is distributed under custom Prime Coder terms, not the MIT license. See LICENSE and TERMS.md.

The current Terms grant permanent free use of releases through 0.3.1, including commercial project work. Later versions, hosted services, and premium features may require a paid entitlement; update policy cannot retroactively place releases through 0.3.1 behind a subscription.

Third-party material remains governed by its own notices in THIRD_PARTY_NOTICES.md.

The free-to-paid transition architecture is documented in docs/update-policy.md and docs/subscription-transition.md.

Runtime And Dev Artifacts

The runtime/local CLI artifact includes:

• .codex-plugin/plugin.json;
• .mcp.json;
• .agents/plugins/marketplace.json;
• bundled MCP server under packages/mcp-server;
• stable production bootstrap under skills/prime-coder;
• CLI runtime under packages/cli;
• executor runtime under packages/executor-runtime;
• local connector runtime under packages/local-connector.

The runtime artifact includes one small, stable bootstrap skill and excludes versioned local premium skills and prompt packs. Versioned workflow capabilities are discovered from the control plane after authentication and entitlement checks.

Release owners also build a separate dev/source/test artifact, prime-coder-project-os-<version>.tgz, which contains hosted web/backend source, tests, scripts, docs, migration skills/stubs, and fixture-only modules for contributor validation.

The source plugin skill surface contains the stable prime-coder bootstrap plus 58 explicit gstack migration skills/stubs under skills/prime-coder-gstack-*. The canonical row-level mapping is docs/gstack-migration-manifest.md, and the separate agent-format decision is in docs/agent-surface.md.

Detailed install notes are in docs/plugin-install.md, and the first-run walkthrough is in docs/demo-walkthrough.md. Generated MCP tool docs are in docs/mcp-tools.md.

Architecture Boundary

Codex:
  quality, architecture, review, task packets, validation decisions

Executor:
  bounded implementation using packet constraints and cheaper OpenAI-compatible model calls

Executor output is untrusted until diff guardrails and validation pass.

More product and architecture notes:

• docs/codex-native-product.md
• docs/gstack-adaptation.md
• docs/gstack-migration-manifest.md
• docs/agent-surface.md
• docs/executor-profiles.md
• docs/executor-runtime.md
• docs/update-policy.md
• docs/subscription-transition.md
• docs/task-packets.md
• docs/review-readiness.md
• docs/release-checklist.md
• CHANGELOG.md

Support, security, and privacy:

• TERMS.md
• SUPPORT.md
• SECURITY.md
• PRIVACY.md