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;
• 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

Then register the installed runtime as a Codex plugin:

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

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 install
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.

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.*/, and local .codex/ settings.

Executor Setup

The executor talks to any OpenAI-compatible API through baseUrl, API key environment variable, and 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 once in the Codex plugin MCP server settings gear, using the env var shown by prime-coder executor config (FAIR_PRICE_API_KEY for the fair-price.ai preset). Shell users can export the same env var instead.

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, CLI and MCP smoke tests, the test suite, doctor checks, package file checks, and clean-machine install smoke.

License And Terms

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

The 0.1.x line is a free public pre-monetization release line. Future versions, premium features, hosted services, entitlement-gated packs, and enterprise workflows may require a paid annual Individual or Enterprise subscription after the paid transition takes effect through the official signed update policy.

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;
• CLI runtime under packages/cli;
• executor runtime under packages/executor-runtime;
• local connector runtime under packages/local-connector.

The runtime artifact intentionally excludes local premium skills and prompt packs. Premium workflow prompts are issued as backend-leased, short-lived skill packs after connector 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 plugin skill surface is exclusively 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