* feat(cli): add Gemini CLI support to setup command
Adds Gemini CLI as a supported agent in `ctx7 setup`. Configures MCP
server in `.gemini/settings.json` using `httpUrl` (Gemini's HTTP
streaming transport), appends rules to `GEMINI.md`, and installs skills
to `.gemini/skills/`. Also adds a permission fix tip when skill
installation fails with EACCES.
* chore: add changeset for Gemini CLI setup
* fix(cli): use GITHUB_TOKEN for skill downloads to avoid rate limits
Closes#2363
* chore: add changeset for gh ratelimit fix
* fix(cli): fallback to gh auth token for skill downloads
Supports private repos and users with gh CLI but no env vars set.
Closes#2369
* feat(cli): support installing skills from private/unindexed repos
When the Context7 backend doesn't know about a repo, the CLI now falls
back to fetching the repo tree from GitHub directly, parsing SKILL.md
frontmatter locally, and downloading skill files. Uses GitHub API status
codes to differentiate non-existent repos from repos without skills.
Closes#2369
* fix(setup): allow re-selecting already configured agents and overwrite existing MCP config
Previously, agents with existing Context7 MCP config were disabled in the
selection prompt with "(already configured)" and their config was never
updated. This made it impossible to reconfigure an agent (e.g. rotate API
key or fix a broken URL) without manually editing config files.
Now all agents are always selectable, existing config is overwritten with
fresh entries on re-setup, and TOML replacement correctly handles
sub-sections like http_headers.
* fix(setup): eliminate double file read and whitespace drift in TOML overwrite
Inline the server existence check into appendTomlServer to avoid reading
the file twice. Normalize whitespace around the replaced block so repeated
re-configurations do not accumulate blank lines.
* chore: add patch changeset for setup reconfiguration fix
* fix(setup): resolve all OpenCode config file variants for MCP setup
OpenCode supports 4 config file names (opencode.json, opencode.jsonc,
.opencode.json, .opencode.jsonc) but setup only checked opencode.json
and opencode.jsonc. Users with dotfile variants were never detected as
"already configured" and setup would create a duplicate opencode.json.
Changed mcp.projectPath/globalPath (single string) to
mcp.projectPaths/globalPaths (string[]) so agents can declare all valid
config paths. resolveMcpPath now takes the full candidates array and
returns the first existing file, falling back to the first entry.
Closes#2313
* chore: add patch changeset for OpenCode config variant fix
* refactor(setup): update rule template to be selective with examples
Based on eval benchmarks showing that selective rules with explicit
should/should-not examples achieve 98% recall with 0 false positives,
vs the previous broad rule.
Split RULE_CONTENT into MCP_RULE_CONTENT and CLI_RULE_CONTENT to
support both MCP and CLI setup modes with appropriate tool references.
* feat(setup): install CLI rule alongside skill in ctx7 setup --cli
Previously, CLI setup mode only installed the find-docs skill (66% trigger
rate). Now it also installs a rule file with ctx7 CLI instructions for each
selected agent, matching the MCP setup behavior.
Benchmarks show skill + rule achieves 96-98% trigger rate vs 66% skill-only.
* feat(find-docs): update skill description to improve trigger rate
Replace passive description with pushy version that explicitly names common
libraries and counters Claude's undertriggering tendency.
Eval results: 66% -> 98% clean recall, 72% -> 92% with-context recall.
* chore(setup): remove deprecated RULE_CONTENT export and alwaysApply frontmatter
alwaysApply is not a Claude Code feature (it's Cursor-specific). Claude Code
rules without paths frontmatter load unconditionally by default. Remove the
deprecated alias now that all callers use MCP_RULE_CONTENT or CLI_RULE_CONTENT.
* refactor(setup): fetch rules from GitHub, add alwaysApply for Cursor
- Rule source of truth in rules/context7-mcp.md and rules/context7-cli.md
- templates.ts fetches from GitHub raw (master then main)
- getRuleContent(mode, agent) adds alwaysApply frontmatter for Cursor
- CLI setup now logs rule install failures instead of silently swallowing
* refactor(setup): add Codex agent, remove needsAlwaysApply field, use shared installRule
- Add Codex agent config with AGENTS.md append support
- Remove needsAlwaysApply field (hardcoded cursor check in templates.ts)
- CLI setup uses shared installRule instead of inline CLI_RULE_PATHS
- installRule handles both file-based (Claude/Cursor/OpenCode) and
append-based (Codex/AGENTS.md) rule installation
* refactor(setup): unify CLI setup with MCP agent picker, group output by agent
- CLI setup now uses the same agent picker as MCP setup (no auto-detection)
- Output grouped by agent instead of repeating find-docs for each path
- Removed unused promptForInstallTargets/getTargetDirs imports
* fix(setup): add branch fallback URL for rule fetch, show error on rule failure
* fix(setup): OpenCode uses AGENTS.md, fix append logic for existing files
- OpenCode rule changed from .opencode/rules/ to AGENTS.md (append type)
since OpenCode reads AGENTS.md natively, not a rules directory
- Fixed append logic: proper spacing for empty/non-empty files, clean
idempotent replacement on re-run, preserves existing content
* test(setup): add tests for rule install, MCP config, and AGENTS.md append
* chore(setup): remove unused mergeInstructions and instructionsGlob
* fix: lint formatting, add changeset
* fix(setup): Codex global rule goes to ~/.codex/AGENTS.md
* fix(setup): align CLI output format with MCP output
* feat(setup): add --codex flag for MCP and CLI setup
* docs(rules): align trigger language with skill, use npx ctx7@latest in CLI rule
* docs(rules): prefer ctx7 over web search for library docs
* docs(find-docs): prefer skill over web search in description
* docs(rules): consolidate trigger language, add selection criteria
* docs(rules): add query quality guidance and auth env var to CLI rule
* cleanup
* fix: remove branch URL, add offline fallback matching rule files exactly
* fix(setup): support opencode.jsonc, strip JSON comments, fix detect path
- readJsonConfig now strips // and /* */ comments before parsing (JSONC support)
- resolveMcpPath checks for .jsonc variant when .json is specified
- OpenCode detect paths include both opencode.json and opencode.jsonc
- Fixed OpenCode project path from .opencode.json to opencode.json
* fix(setup): fix JSONC comment stripping to preserve URLs in strings
The regex-based comment stripper was matching // inside string values
(e.g., https:// URLs), corrupting the JSON. Replaced with a character-
level parser that skips string literals before stripping comments.
* fix(setup): Codex uses TOML config.toml, detect .opencode.json variant
- Codex MCP writes to ~/.codex/config.toml using [mcp_servers.context7]
TOML sections instead of JSON (matches Codex docs and add-mcp tool)
- OpenCode detection checks opencode.json, opencode.jsonc, and .opencode.json
- Added TOML server block writer with idempotent append
- stripJsonComments now handles URLs in strings correctly
* test(setup): add JSONC, TOML, and resolveMcpPath tests
12 new tests covering:
- JSONC: comment stripping preserves URLs, block comments, plain JSON
- resolveMcpPath: .jsonc resolution, .json fallback, non-json passthrough
- TOML: buildTomlServerBlock output, http_headers, readTomlServerExists,
appendTomlServer (empty file, preserve existing, idempotent)
* fix(setup): Codex MCP needs type=http, fix checkbox disabled item selection
- Codex TOML entry now includes type = "http" (required by Codex)
- Checkbox cursor starts on first non-disabled item
- Checkbox navigation skips disabled items
* fix: address PR review feedback on rules and skill description
- Surface libraryId format (/org/project) in step 2 where selection happens
- Suggest retrying with alternate names/queries instead of just punctuation
- MCP rule: explicitly require resolve-library-id unless /org/repo provided
- Skill description: explicitly warn against relying on training data for APIs
* fix: consistent /org/project format in MCP rule
* fix: revert opencode detection paths to original
* fix(cli): use ~/.agents/skills for global universal skill installs
The universal global path was ~/.config/agents/skills, but the
canonical standard (used by Vercel's skills CLI and OpenAI Codex)
is ~/.agents/skills. This aligns context7 with the broader ecosystem.
Fixes#2276
* chore: add changeset for global skills path fix
* fix(cli): remove shell:true from spawn in generate command
Removes shell:true from the child_process.spawn() call that opens
the user's editor. The editor path and preview file path are already
passed as separate arguments, so shell interpolation is unnecessary.
Using shell:true allows shell metacharacters in EDITOR or file paths
to be interpreted, which is a command injection vector.
Fixes#2240
This contribution was developed with AI assistance (Claude Code).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* chore: add changeset for shell:true removal
---------
Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Fahreddin Özcan <ozcanfahrettinn@gmail.com>
* fix(cli): prevent directory traversal in skill file installation
installSkillFiles() used path.join() with unsanitized file paths from
GitHub API responses. A malicious skill repository could include files
with "../" sequences in their paths, allowing writes outside the
intended skill directory.
Changes:
- installer.ts: use path.resolve() and verify the resolved path stays
within the skill directory boundary before writing
- github.ts: reject file paths containing ".." at download time as an
additional defense-in-depth check
* chore: add changeset for directory traversal fix
* fix: format installer.ts to pass prettier lint
---------
Co-authored-by: Fahreddin Özcan <ozcanfahrettinn@gmail.com>
* fix(cli): add token refresh support and centralize auth constants
Expired OAuth tokens are now automatically refreshed via getValidAccessToken()
instead of silently failing. CLI_CLIENT_ID moved to constants.ts to avoid
duplication across auth.ts and setup.ts.
* refactor(cli): internalize baseUrl and clientId in refreshAccessToken
Make refreshAccessToken a private function that resolves getBaseUrl()
and CLI_CLIENT_ID internally instead of requiring them as parameters.
* test(cli): add unit tests for auth utilities and commands
Add comprehensive vitest test suite covering OAuth PKCE flow, token
persistence, token refresh, and CLI auth commands (login/logout/whoami).
* chore: add changeset for CLI auth improvements
* refactor: move CLI auth tests to src/__tests__/
Move auth test files from colocated __tests__ directories to a
centralized src/__tests__/ directory, adjusting mock import paths
accordingly.
* feat(cli): add teamspace name to whoami command
Replace direct Clerk userinfo call with new /api/dashboard/whoami
endpoint that returns name, email, and active teamspace in one request.
* chore: add changeset for whoami teamspace feature
* feat(cli): enumerate popularity and trust in skill search results
Replace raw install counts with star-based popularity rating (★☆☆/★★☆/★★★)
and numeric trust scores with High/Medium/Low labels in skill search,
install, and suggest commands. Show install range and raw trust score
in the hover description. Also reorder setup command to show CLI before MCP.
* feat(cli): use 4-star popularity scale matching install count ranges
* fix(cli): replace hardcoded "docs" with "find-docs" in setup output
* chore: add changeset for skill search enumeration and find-docs rename
* refactor(skills): consolidate skills under /skills with canonical sources
- Rename skills/docs → skills/find-docs (name: find-docs)
- Rename skills/ctx7-cli → skills/context7-cli (name: context7-cli)
- Add skills/context7-mcp as canonical MCP skill source
- Rename plugin skill folders to context7-mcp and unify name to context7-mcp
- MCP setup now downloads context7-mcp skill from GitHub instead of using hardcoded SKILL_CONTENT
- Remove SKILL_CONTENT from templates.ts — skills/context7-mcp/SKILL.md is the single source of truth
- Add Error Handling section to find-docs skill for quota errors
- Update agents.ts skill name: documentation-lookup → context7-mcp
- Update docs/clients/cli.mdx and setup references accordingly
* chore: add changeset for skills consolidation
* fix(skills): update plugin skill frontmatter name and setup docs to context7-mcp
* feat(cli): add CLI mode to ctx7 setup with docs skill installation
- Add MCP vs CLI mode selection prompt at the start of setup
- CLI mode authenticates user and installs docs skill via promptForInstallTargets
- Add --cli, --universal, --antigravity flags to setup command
- --yes skips the detected-locations confirmation prompt
- Default CLI install scope to global (override with --project)
- Fix checkbox selected choices to render in green (consistent with select prompt)
- Move Claude Code above Universal in IDE selection order
- Add forceUniversal=false option to promptForInstallTargets for setup flow
- Add yes? to AddOptions to support auto-confirm in promptForInstallTargets
* chore: add changeset for ctx7 setup CLI mode
* feat(cli): rename CLI mode to CLI + Skills, add --mcp flag, remove recommended label
* feat(cli): add --api-key support to CLI mode and update docs
- Pass apiKey through to resolveCliAuth in CLI mode setup
- Store provided API key as bearer token for subsequent API calls
- Update cli.mdx and setup.md to reflect both MCP and CLI + Skills modes
* docs: update setup docs to reflect --api-key for both modes and --cursor for CLI
- --api-key works in both MCP and CLI + Skills mode (not MCP-only)
- --oauth clarified as MCP-only
- Added --cursor to CLI + Skills mode examples (Cursor has a skills directory)
- Updated auth table row for ctx7 setup
* fix(cli): improve library ID validation and add telemetry headers
- Validate /owner/repo format locally before spinner starts, showing
consistent error + hint for both "react" and "/react" inputs
- Send X-Context7-Source, X-Context7-Client-IDE, X-Context7-Client-Version,
and X-Context7-Transport headers on library/docs requests so CLI
appears in the admin telemetry dashboard
* feat(cli): show source repo next to skill name in search and suggest results
Adds the project repo in parentheses after each skill name to help
disambiguate skills with identical names from different repositories.
* chore: add changeset for repo display in skill search
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* feat(docs): add dedicated docs skill and restructure CLI documentation
- Add new `docs` skill as a single-file skill for documentation retrieval
- Align skill prompts with MCP tool descriptions (selection process, query guidance, 3-call limit)
- Enrich CLI docs page with result fields, query tips, and version-specific IDs
- Move CLI page to Overview section in docs nav
- Make `query` required for `ctx7 library` across all skills and docs
- Update trust score display label in skills.mdx
* feat(cli): align library output format with MCP labels
Use labeled fields and categorical Source Reputation labels
(High/Medium/Low/Unknown) instead of numeric trust scores to match
the MCP transport format.
* refactor: move skills from .agents/skills to skills/ at repo root
Source-control location for skills — users install them into
.agents/, .claude/, etc. via the CLI. Also updates install
instructions to use `npm install -g ctx7@latest` or `npx ctx7@latest`.
* docs: use natural-language query examples across skills and CLI docs
Replace keyword-style queries ("useEffect cleanup") with full
question-style queries ("How to clean up useEffect with async
operations") to better demonstrate how the query parameter works.
* docs: fix trust score description to show numeric range
* feat(cli): add resolve and query commands for library documentation
Expose Context7's resolve-library and query-docs API as CLI commands,
enabling agents and developers to fetch documentation directly from
the terminal without MCP setup.
- `ctx7 resolve <library> [query]` - resolve library name to Context7 ID
- `ctx7 query <libraryId> <query>` - fetch documentation for a library
- Both support --json for structured output
- TTY-aware: spinners and colors in terminal, clean output when piped
- Auth: CONTEXT7_API_KEY env var > OAuth token > unauthenticated
* refactor(cli): rename resolve/query to library/docs commands
Rename commands for a more natural CLI interface:
- `ctx7 library <name> [query]` instead of `ctx7 resolve`
- `ctx7 docs <libraryId> <query>` instead of `ctx7 query`
* fix(cli): show benchmark score and all versions in library results
* chore: add changeset for library and docs commands
* style(cli): fix lint formatting in api.ts
* refactor(cli): remove redundant spinner success messages
The output itself is self-evident, no need for "Found 5 libraries"
or "Documentation retrieved" messages.
* feat(cli): install documentation-lookup skill during ctx7 setup
The setup command now installs the Context7 documentation-lookup skill
alongside the MCP server and rule for each agent.
Skill paths per agent:
- Claude: .claude/skills/documentation-lookup/SKILL.md
- Cursor: .cursor/skills/documentation-lookup/SKILL.md
- OpenCode: .agents/skills/documentation-lookup/SKILL.md (universal)
* chore: add changeset for skill install in setup
* add `ctx7 setup` command for configuring MCP and rules
Adds an interactive setup command that configures the Context7 MCP server
and agent rules for Claude Code, Cursor, and OpenCode. Authenticates via
OAuth, generates an API key, and writes per-agent config files.<noreply@anthropic.com>
* revert auth.ts client ID change
* add changeset for setup command
* fix lint: format import line
* feat(cli): adopt .agents/skills as universal install target
Install to .agents/skills/ by default as the shared standard directory.
Universal agents (Amp, Codex, OpenCode, Gemini CLI, GitHub Copilot) all
read from this path natively. Vendor-specific agents (Claude Code, Cursor,
Antigravity) get symlinks pointing back to .agents/skills/.
- Add "universal" as a first-class IDE type across all path maps
- Auto-detect .agents/ and vendor dirs: detected → confirm, nothing
detected → checkbox picker with Universal pre-checked
- Update list/remove commands to check universal + vendor-specific dirs
- Update DEFAULT_CONFIG.defaultIde from "claude" to "universal"
- Show labeled install summary (Universal, Claude Code, etc.) with paths
* feat(cli): consolidate agent flags into single --universal option
Replace --codex, --opencode, and --amp flags with a single --universal flag that points to .agents/skills/. This simplifies the CLI interface since these agents all share the same installation path.
* refactor(cli): simplify IDE types and remove UNIVERSAL_AGENTS Set
- Simplify IDE type from 7 types to 4 (remove codex, opencode, amp)
- Remove UNIVERSAL_AGENTS Set and replace with direct equality checks
- Update documentation to add --universal flag examples throughout
- Consolidate Supported Clients table to show single Universal row
All universal agents (Amp, Codex, Gemini CLI, GitHub Copilot, OpenCode, etc.)
are now represented by the single "universal" type since they're functionally
identical and use the same .agents/skills/ directory.
* docs(skills): update CLI flags to use --universal
- Replace --codex, --opencode, --amp flags with single --universal flag
- Update all command examples (install, list, remove, suggest, generate)
- Consolidate Supported Clients table with Universal at top
- Reorder tables to prioritize Universal agents
* discover
* feat(cli): use backend suggest endpoint for skill suggestions
Replace client-side NOTABLE_SET filtering with a single POST request to
/api/v2/skills/suggest. The backend now handles SKIP_SET filtering,
vector search, install count enrichment, and ranking.
- Remove NOTABLE_SET/SKIP_SET from deps.ts
- Add suggestSkills API function
- Add SuggestGroup and SuggestResponse types
- Simplify suggestCommand to use backend response
* feat(cli): send auth token with suggest request
Pass the user's OAuth token (if logged in) when calling the suggest
endpoint so the request counts against their quota.
* chore: add changeset
* refactor: simplify suggest API usage
- Remove ecosystem field from deps detection
- Use flat skills array from backend instead of groups
- Simplify display logic
* fix: use white color for Relevant value in metadata panel
* refactor: rename DiscoverOptions to SuggestOptions
* feat(cli): add trust score column and improve skill search display
Add trust score and installs columns with aligned headers to skill search results.
Trust scores use yellow/red color coding (0-10 scale).
* chore: add changeset for trust score column
* feat(cli): auto-login when generate requires authentication
Extract login flow into reusable `performLogin()` function.
Generate command now triggers OAuth login automatically instead of
showing an error asking the user to run 'ctx7 login' manually.
* feat(cli): show recommended option first in generate questions
Reorder options so the recommended answer is always displayed at
position 1 with cursor starting on it, regardless of original index.
* feat(cli): open generated skill in default editor instead of inline view
Replace inline terminal "View full skill" with "View skill" that opens
the content in the system default editor ($EDITOR or 'open' fallback)
via a temp file.
* feat(cli): revamp generate UX with improved copy and examples
Update skill generation flow:
- Show do/don't examples (✕/✓) for skill descriptions
- Rename "libraries" to "sources" in user-facing text
- Add explanation of what sources are used for
- Update spinner text for questions and generation steps
- Remove unused libraryNames variable
* chore: update changeset to include generate UX changes
* fix(cli): show dash placeholder for missing installs and trust scores
* feat(cli): add external link icon to terminal hyperlinks and show dash for empty fields
* feat(cli): improve view/edit skill with persistent edits and preview cleanup
Save preview files to ~/.context7/previews/ instead of OS temp dir, read
edits back before install, and clean up preview files on exit.
* feat(cli): improve generate UX copy and flow polish
Update skill generation flow with clearer descriptions, better spinner
messages, and improved finalize menu options.
* fix(cli): fix stale editor preview, install count side effect, and editor spawn
- Reset previewFileWritten between regeneration cycles so editor shows fresh content
- Add placeholder param to formatInstallCount to avoid showing "-" in list command
- Replace execFile with spawn for proper $EDITOR support (terminal editors, args)
- Move trustScore to Skill base type and remove redundant installCount from SkillSearchResult
Display exact install count numbers instead of rounded values (e.g. 41 instead of 40+), sort skills by install count descending in the install command, and show "installs" column header inline with the prompt.
* feat: add oauth 2.0 support with login,whoami and logout commands
* ci: lockfile
* fix: address security and port issues in OAuth flow
- Fix XSS vulnerability by escaping HTML in error page messages
- Change callback port from 9876 to 52417 (high ephemeral range, less likely to conflict)
* refactor: clean up auth code and remove unnecessary comments
- Remove obvious comments that duplicate function names
- Extract duplicate expiration display logic into printTokenExpiration helper
- Simplify logoutCommand (remove async, inline condition)
- Remove unused saved_at field from token storage
* fix: address auth bugs and remove unused code
Bug fixes:
- whoami now shows "Session expired" instead of misleading "Logged in" when token is invalid
- expires_at calculation preserves existing value instead of overwriting
- Login check now allows re-login when tokens are expired with no refresh token
Simplifications:
- Remove unused getAccessToken and refreshAccessToken functions
- Simplify printTokenExpiration (remove unused showExpired parameter)
* refactor: improve whoami output formatting
- Align labels using padEnd for consistent output
- Remove expiration time display from whoami
- Show login status first, then fetch user details
* chore: add changeset for OAuth feature
* feat: enumerate search results
* feat: select hovered item on Enter in checkbox prompts
* refactor: improve types in prompts.ts
* feat: improve skill list UI with metadata panel and install counts
* chore: update version and changelog
* feat: add consistent green highlighting to IDE/scope prompts
Apply green highlight theme to all selection prompts in ide.ts
for visual consistency with skill selection prompts.
github-actions[bot]