PCA CLI

PCA = Persistent Context Architecture.

Markdown files are the source of truth. RAG is the mandatory access layer. Agents must not read the full pca/ folder by default.

Install

npm install

Create a local .env file with:

OPENAI_API_KEY=sk-...

Development

npm run dev -- help

src/ is the development source. dist/ is generated by npm run build and is included in the npm package through the files allowlist, but it does not need to be edited by hand during development.

Local global install

npm install
npm run build
npm link
pca help

Windows note:

• PowerShell may block the npm pca.ps1 shim depending on ExecutionPolicy. Use pca.cmd help.
• CMD can use pca help.

To unlink:

npm unlink -g @quantpartners/pca

Alternative:

npm install -g .
pca help

NPX Usage

After publishing to npm:

npx -y @quantpartners/pca@latest help
npx -y @quantpartners/pca@latest doctor
npx -y @quantpartners/pca@latest init

Recommended API key setup:

export OPENAI_API_KEY="sk-..."
npx -y @quantpartners/pca@latest init

PowerShell:

$env:OPENAI_API_KEY="sk-..."
npx -y @quantpartners/pca@latest init

Alternative, less recommended:

npx -y @quantpartners/pca@latest init --api-key "sk-..."

Warning: passing API keys via CLI flags can expose them in shell history.

OPENAI_API_KEY

PCA reads OPENAI_API_KEY in this order:

1. Explicit --api-key flag.
2. Existing environment variable.
3. .env in the current project where you run pca.
4. .env in this CLI project during local development.

Bash:

export OPENAI_API_KEY="sk-..."

PowerShell:

$env:OPENAI_API_KEY="sk-..."

CMD:

set OPENAI_API_KEY=sk-...

Project .env:

OPENAI_API_KEY=sk-...

CLI flag:

pca init --api-key "sk-..."
pca --api-key "sk-..." init

Passing API keys via CLI flags can expose them in shell history. Prefer using OPENAI_API_KEY or a local .env file.

Full MVP Flow

npm run dev -- init
npm run dev -- sync
npm run dev -- query "project architecture"
npm run dev -- task "crear hero mobile"
npm run dev -- visual add ./example.png --type reference --note "landing reference"
npm run dev -- close

Recommended working loop:

pca init
pca sync
pca task "crear hero mobile"
# paste .pca/last-task-context.md into Codex
pca close
pca sync

Critical Rules

• PCA sin RAG no opera.
• No fallback to reading the full pca/ folder.
• Only PCA_INDEX.md is read at task start.
• Vector Store is required.
• Roadmap/changelog update only after closure confirmation.

MVP Limitations

• No web UI.
• No own database.
• No login, billing, dashboard, or multiuser support.
• No deep Git integration.
• No advanced vector store deduplication or replacement yet.
• Visual memory stores local images plus textual metadata in pca/visual/visual-index.md; real multimodal analysis comes in v2.

Technical TODOs

• v2: add pca install codex, pca install cursor, and pca install claude to install agent-specific PCA rules. Do not use install for global CLI installation.
• Add vector store deduplication/replacement in v2 after stable local path to OpenAI file mapping is introduced.
• Add multimodal visual analysis in v2.

Publish to npm

npm login
npm run build
npm pack --dry-run
npm publish --access public

Then test:

npx -y @quantpartners/pca@latest help