contextplusplus

contextplusplus turns public urls and provider responses into clean markdown that agents and apps can actually use.

the same engine powers a cli, an http api, an mcp server, a public website, and an authenticated dashboard. this repo is the source of truth for all of them, plus contracts, sdk generators, database migrations, docs, and release wiring.

the 60-second version

• node 22 or newer
• pnpm 10.28.2
• typescript, effect-ts v3, turborepo, next.js, supabase, and vitest
• backend logic lives in packages/core
• runtime entrypoints live in apps/api, apps/cli, and apps/mcp
• product frontends live in apps/website and apps/dashboard
• current engineering knowledge lives in .trellis
• generated files have generators; don’t hand-edit them
• secrets belong in ignored env files or secret managers, never in git

get the repo running

git clone https://github.com/yigitkonur/contextplusplus.git
cd contextplusplus
corepack enable
pnpm install
pnpm run agent:check
pnpm run typecheck

copy .env.example to an ignored local env file and fill only the values needed for the surface you’re running. most provider, billing, auth, and observability integrations are optional for basic code navigation, but real hosted flows need their matching credentials.

use these local entrypoints:

pnpm --filter @contextplusplus/api dev
pnpm --filter contextplusplus dev -- --help
pnpm --filter contextplusplus dev -- process --url https://example.com --format markdown
pnpm --filter @contextplusplus/mcp dev
pnpm --filter @contextplusplus/website dev
pnpm --filter @contextplusplus/dashboard dev

install contextplusplus as a user

run the complete installer. on a first run it signs you in by email, asks which agents to configure, installs the appropriate native plugin or standalone skill, writes managed guidance, and verifies the selected transport. rerunning the bare command opens lifecycle management instead of repeating first-time setup:

npx -y [email protected]

pick cli for terminals, scripts, ci, headless systems, or agents that can run shell commands. pick mcp when the host supports native mcp tools. claude code and codex always receive the bundled native plugin; other registered agents receive their supported configuration, one transport-specific standalone skill, and managed guidance. credentials stay in private user state, and mcp targets use isolated revocable connections. setup never edits shell profiles or requires a global binary.

the canonical unattended interface is explicit and never prompts:

printf '%s\n' "$CTXPP_KEY" | npx -y [email protected] install \
  --agents claude-code,codex --mode mcp --scope global \
  --yes --no-input --json --api-key-stdin

npx -y [email protected] install \
  --agents gemini --mode cli --scope global \
  --yes --no-input --json --api-key-file /run/secrets/contextplusplus

init is a compatibility alias for this complete install flow. the deprecated --mcp, --cli, --project, --skills, and --api-key flags remain accepted when their meaning is unambiguous; new automation should use --mode, --scope, and stdin/file credential input.

transport transitions are additive. rerunning the same mode repairs drift idempotently; picking the other transport over an existing install unions into a "both" install — nothing installer-owned is removed or revoked, and both transport skills plus combined guidance land. unmanaged legacy artifacts require interactive adoption or explicit --adopt-existing in unattended runs.

operate or reverse recorded state with:

npx -y [email protected] repair --agents codex --yes --no-input --json
npx -y [email protected] status --json
npx -y [email protected] agents list --json
npx -y [email protected] uninstall --agents codex \
  --components plugin,skill --yes --no-input --json
npx -y [email protected] uninstall --all --all-scopes \
  --yes --no-input --json

cli-mode agents invoke the package at its pinned version; do not probe a bare ctxpp or contextplusplus executable:

npx -y [email protected] process https://example.com --format markdown

how the repo hangs together

users, agents, and apps
  -> cli: contextplusplus / ctxpp
  -> http api: processing, auth, billing, usage, and admin routes
  -> mcp: consultancy, search, evidence tools, and compatibility aliases
  -> website: marketing, pricing, install, and legal pages
  -> dashboard: auth, keys, billing, usage, and device approval

runtime boundaries
  apps/cli   \
  apps/api    -> packages/core -> providers -> markdown
  apps/mcp   /

frontend surfaces
  apps/website   \
  apps/dashboard  -> packages/ui + packages/contracts + packages/markdown

the important rule is dependency direction: application code must not import infrastructure or interface code. effect runtimes are executed only at boundary entrypoints. test/integration/legacy-boundary.test.ts and scripts/check-rules.mjs enforce the sharp edges.

workspace map

| path | what lives there | |---|---| | packages/core | domain schemas, effect services, workflows, ports, infrastructure, providers, rendering, cache, auth, billing, usage, and templates | | apps/api | express http boundary and server process | | apps/cli | published contextplusplus and ctxpp cli package, installer, auth, and local/hosted processing | | apps/mcp | authenticated mcp server and its seven research/conversion tools | | apps/website | public next.js site for product, pricing, installs, and legal pages | | apps/dashboard | authenticated next.js app for keys, connections, billing, usage, and account flows | | packages/ui | shared react components and browser-safe clients | | packages/contracts | serializable contracts shared by frontend surfaces | | packages/markdown | shared markdown helpers | | .trellis/reference/contracts/openapi.yaml | source http api contract | | sdk | generated typescript and python sdks | | supabase | local config, seed data, and ordered migrations | | test | unit, integration, e2e, fakes, and fixtures | | scripts | rule checks, generators, packaging, fixtures, and release helpers | | mintlify | generated public provider docs | | plugins/contextplusplus | credential-free claude/codex plugin, skills, and onboarding assets | | .trellis | workflow, active specs, detailed references, tasks, and local workspace state | | to-delete | ignored quarantine for retired material; never use it as live guidance |

what to read first

start narrow and expand only when the change needs it:

1. AGENTS.md for repo rules, commands, and skill routing.
2. .trellis/reference/project/CODEBASE_MAP_AND_ONBOARDING.md for file-level navigation and change recipes.
3. .trellis/reference/project/ARCHITECTURE.md for boundaries and the processing pipeline.
4. .trellis/reference/project/USE_CASES_SCREENS_AND_FLOWS.md for user-visible behavior.
5. .trellis/reference/project/INTERFACES_AND_INTEGRATIONS.md for external systems and contracts.
6. .trellis/reference/project/CONFIG_BUILD_RELEASE_AND_OPERATIONS.md before config, ci, deploy, or release work.
7. .trellis/reference/project/SECURITY_TESTING_AND_RISKS.md before auth, billing, quota, or security-sensitive work.

the nearest AGENTS.md adds folder-specific rules. read it before editing that area. trellis specs under .trellis/spec are short executable conventions; detailed project truth stays under .trellis/reference.

common change routes

| when you’re changing | start here | verify alongside it | |---|---|---| | http routes | apps/api/src/interfaces/http/app.ts | openapi contract, http integration tests, sdk drift when public shapes change | | cli commands or installer behavior | apps/cli/src/interfaces/cli | cli/installer integration tests and package smoke checks | | mcp tools or auth | apps/mcp/src/interfaces/mcp | mcp auth, quota, transport, and structured-error tests | | provider routing | packages/core/src/providers/definitions and packages/core/src/infrastructure/providers | provider schemas, strategy shape, fixtures, and mintlify drift | | markdown rendering | packages/core/src/infrastructure/markdown and packages/core/templates | renderer tests and live fixture drift | | auth, quota, billing, or api keys | core ports, matching infrastructure, and supabase/migrations | security tests, rpc/rls tests, and generated database types | | website or dashboard ui | the matching app plus packages/ui | typecheck, scoped react tests, ci build, and deployed browser proof when shipped | | openapi or sdk output | .trellis/reference/contracts/openapi.yaml and sdk generators | both sdk drift checks and contract tests | | ci, deploy, or release | .github/workflows, scripts/land.sh, and package scripts | release/operations reference and exact-sha ci |

generated files: hands off the output

change the source or generator, then regenerate:

| generated output | source or command | |---|---| | sdk/typescript/src/schema.d.ts | scripts/generate-sdk.ts and pnpm run sdk:check | | sdk/python/contextplusplus | scripts/generate_sdk_py.py and pnpm run sdk:check:py | | packages/core/src/infrastructure/supabase/database.types.ts | migrations plus scripts/gen-supabase-types.sh | | mintlify provider docs | provider catalog plus scripts/generate-mintlify-docs.ts | | live render fixtures | scripts/render-live-fixtures.ts |

checks that matter

run the narrowest checks that prove your change, then use the root gates before landing broad work.

pnpm run agent:check
pnpm run typecheck
pnpm run test
pnpm run test:e2e
pnpm run verify:fast
pnpm run verify

high-ripple checks:

pnpm run fixtures:check-live
pnpm run docs:mintlify:check
pnpm run sdk:check
pnpm run sdk:check:py
pnpm run supabase:check

package-scoped examples:

pnpm --filter @contextplusplus/core test
pnpm --filter contextplusplus typecheck
pnpm --filter @contextplusplus/mcp typecheck
pnpm exec vitest run test/integration/install-mode.test.ts

don’t weaken a check to get green. fix the source, rerun the original failure, and report only what you actually ran.

env and secrets

• use .env.example as the key inventory, not as a place for real values
• keep local values in ignored env files or the platform’s secret store
• never commit api keys, service-role keys, stripe secrets, connect urls, or provider credentials
• global smart installs may write private owner config; project installs must use env indirection
• use CONTEXTPLUSPLUS_API_KEY for ci/headless cli auth
• use CONTEXTPLUSPLUS_API_URL only when intentionally targeting a non-default backend

the main external systems are supabase, stripe, railway, vercel, redis, provider services, sentry, opentelemetry, and mintlify. the integration reference explains which variables and runtime surfaces own each one.

git and delivery

work on a task branch in its own worktree when the task is distinct. keep commits conventional and single-purpose. after local proof passes, fast-forward main, push the exact sha, and wait for every triggered ci run to reach a terminal result.

deploys and production migrations are separate, explicit operations. github workflows under .github/workflows own railway deploys, vercel prebuilt uploads, and supabase migrations. don’t treat a green merge as proof that production was deployed.

cleanup rules

keep .trellis, project skills, and integration assets tracked: they are part of how this repo is developed and distributed. caches, build output, local runtime state, and retired history do not belong in the live tree.

when something might still matter for provenance, move it into the ignored to-delete quarantine instead of using it as active guidance. never revive files from there without checking current code and specs first.

that’s the map. pick the smallest relevant surface, read its local rules, make the change, and prove the behavior.