Contextfolio

Contextfolio turns source-labeled AI context into portable profile artifacts you can review, edit, and install in other AI tools.

Useful working context often gets scattered across ChatGPT, Claude, Gemini, Cursor, Codex, OpenClaw, Hermes Agent, and personal notes. Contextfolio keeps the handoff explicit: claims cite source ids, weak or sensitive claims are flagged, and generated files stay inspectable before installation.

Quick Start

Use the npm CLI package through npx:

npx @contextfolio/cli@latest bootstrap chatgpt --target openclaw

This guided command is the shortest starting path for most users. It copies a ChatGPT bootstrap prompt, asks you to paste ChatGPT's JSON response back into the terminal, reviews the draft, writes target-shaped artifacts to .tmp/bootstrap-export, and offers to install the OpenClaw profile.

Supported Targets

Automatic local install targets:

• codex
• claude
• cursor
• gemini
• openclaw
• hermes

For any of those targets, guided bootstrap can finish from one command:

npx @contextfolio/cli@latest bootstrap chatgpt --target <target>

Manual targets:

• chatgpt: paste chatgpt/custom_instructions.md into ChatGPT Custom Instructions or equivalent personalization settings.
• generic: copy the generated profile files and sources/manifest.json into a target context your tool supports.

Global installs write into target-owned directories: Codex ~/.codex, Claude ~/.claude, Cursor ~/.cursor, Gemini ~/.gemini, OpenClaw ~/.openclaw/workspace, and Hermes ~/.hermes or $HERMES_HOME.

Use --scope project only when you intentionally want a local override for targets that support it. OpenClaw is global-workspace only.

For a safer manual install path, generate the export first, inspect a dry run, then install and verify:

npx @contextfolio/cli@latest bootstrap --provider chatgpt --input .tmp/bootstrap-provider-output.json --out .tmp/bootstrap-export --target openclaw --save-last
npx @contextfolio/cli@latest install --from .tmp/bootstrap-export --target openclaw --dry-run --backup
npx @contextfolio/cli@latest install --from .tmp/bootstrap-export --target openclaw --yes --backup
npx @contextfolio/cli@latest verify-install --target openclaw

Advanced Source-Pack Workflow

Use this path when you have prepared conversation summaries, transcripts, or notes and want stronger source-level evidence, a file-by-file audit trail, or a chance to edit the profile-draft/v1 JSON before compiling artifacts.

Generate an extraction prompt:

npx @contextfolio/cli@latest prompt --source-dir examples/source-pack --out .tmp/contextfolio-prompt.md

Paste .tmp/contextfolio-prompt.md into your AI tool, save the returned JSON to .tmp/profile-draft.json, review it, then compile:

npx @contextfolio/cli@latest review-draft --draft .tmp/profile-draft.json
npx @contextfolio/cli@latest compile-draft --draft .tmp/profile-draft.json --out .tmp/export

Generated outputs can include:

• AGENTS.md
• CLAUDE.md
• GEMINI.md
• chatgpt/custom_instructions.md
• .cursor/rules/contextfolio.mdc
• profile/personal_profile.md
• profile/technical_profile.md
• profile/working_profile.md
• sources/manifest.json
• privacy/redactions.md

Do not install privacy/redactions.md as normal profile context.

File-Based Bootstrap

If you prefer inspectable prompt and response files instead of guided clipboard handoff:

npx @contextfolio/cli@latest bootstrap-prompt chatgpt --out .tmp/chatgpt-bootstrap-prompt.md
npx @contextfolio/cli@latest bootstrap --provider chatgpt --input .tmp/bootstrap-provider-output.json --out .tmp/bootstrap-export --target openclaw --save-last

--save-last writes <out>/last/profile-draft.json only after JSON normalization and schema validation succeed. --from-stdin is also supported when you want a shell-driven handoff.

See docs/07-file-based-bootstrap.md for the fixed-file walkthrough and docs/08-target-clipboard-compatibility.md for target and clipboard behavior. For the full copy-paste rehearsal, follow docs/04-real-profile-workflow-rehearsal.md. Release handoff details live in docs/03-oss-split-handoff.md.

OpenAI documents the ChatGPT Custom Instructions surface at https://help.openai.com/en/articles/8096356-custom-instructions-for-chatgpt.

Core Concepts

• Source pack: a directory of conversation summaries, transcripts, or notes used as evidence.
• Profile draft: a profile-draft/v1 JSON file containing source-cited claims.
• Bootstrap: a guided provider handoff that creates a reviewed draft and export bundle from one provider's JSON response.
• Compile/export: validation and rendering from a reviewed draft into target-specific files.

Examples

• examples/source-pack/session-a.md is a source input for prompt generation.
• examples/drafts/profile-draft.json is a deterministic sample draft for compile validation.
• examples/drafts/chatgpt-memory-bootstrap-draft.json is a synthetic ChatGPT memory bootstrap sample.
• examples/README.md contains example-specific commands.

Public Data Scope

This repository contains code, docs, and synthetic examples. It does not include personal source packs, private profile drafts, generated user profiles, or raw AI conversation exports.

Keep your own source packs and draft files outside the repository or in ignored local paths such as .tmp/. Review generated artifacts before copying them into another AI tool.

Development

From a local checkout:

pnpm install
pnpm build
pnpm contextfolio bootstrap chatgpt --target openclaw

Run checks:

pnpm test
pnpm typecheck

The npm CLI package is @contextfolio/cli and exposes the contextfolio binary, so the published default is:

npx @contextfolio/cli@latest --help

npx contextfolio would require publishing a separate unscoped alias package. npx contextfolio/ is not the normal npm package invocation form.

Release Checks

Before preparing a public source export, run:

pnpm build
pnpm test
pnpm typecheck
pnpm contextfolio validate-oss --out .tmp/contextfolio-oss-validation
pnpm contextfolio export-oss --out .tmp/contextfolio-oss
pnpm contextfolio export-oss --check .tmp/contextfolio-oss

validate-oss creates a validation workspace, installs dependencies, runs build, test, and typecheck, packs the CLI tarball, verifies the published CLI does not depend on a separately published @contextfolio/core, installs the packed CLI into a temporary consumer project, and runs prompt and compile-draft smoke checks.

Publish command:

pnpm --filter @contextfolio/cli publish --access public

@contextfolio/core remains an internal workspace package and is vendored into the published CLI tarball. It should not be published separately.

The validation workspace is not the pristine release export. Commits, remotes, pushes, and repository visibility are separate release handoff steps.

Status

Current CLI coverage includes provider bootstrap prompts, reviewed provider JSON import, draft review, draft compilation, local install/verify for Codex, Claude, Cursor, Gemini, OpenClaw, and Hermes, plus the source-pack prompt workflow.

Deferred areas include direct raw conversation ingestion, hosted account extraction, workspace sync, public API integrations, and MCP integration.

License

MIT. See LICENSE.